pktmn-ui

pktmn-ui is a React component library inspired by theme-heavy game UI like Pokémon Emerald. Transpiled with Vite library mode, pktmn-ui ships with styles organized via Tailwind CSS theming, defined in pktmn-ui/foundations.css.

Links

• Documentation — component/prop documentation
• Storybook — interactive component explorer
• Figma — pktmn-ui community file

Installation

pktmn-ui ships with tailwindcss as a dependency, so it installs automatically. You only need to install the integration for your bundler, for example if building with Vite:

1. Install pktmn-ui

npm install pktmn-ui

2. Add the Tailwind Vite plugin to your config

@tailwindcss/vite is included with pktmn-ui — just register it:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})

This plugin is what compiles the @import "tailwindcss" and @theme { … } directives inside foundations.css (Tailwind v4 is configured in CSS, not a tailwind.config.js), turning the pktmn-ui design tokens into real utility classes. It also scans your source files for the classes you use and generates CSS on demand, so styling your own markup with pktmn-ui utilities (see step 4) only works with the plugin registered. pktmn-ui ships @tailwindcss/vite for you, but it can't edit your config — only you can add it here. On a non-Vite bundler, use the matching Tailwind integration instead (e.g. @tailwindcss/postcss).

3. Import foundations.css in your CSS entry

In your main CSS file (e.g. src/index.css), replace any existing @import "tailwindcss" with:

@import "pktmn-ui/foundations.css";

foundations.css includes @import "tailwindcss" internally. It provides the theme tokens, font faces, and all named themes.

4. Use components and tokens

import { PrimaryFilledButton } from 'pktmn-ui'

<PrimaryFilledButton theme="legendary-blue" size="medium">Start game</PrimaryFilledButton>

Each component injects its own scoped styles, so importing foundations.css once (step 3) is all the setup required. Alternatively, theme tokens from pktmn-ui can be used to style your own markup:

<p data-theme="legendary-blue" className="font-textLg text-content bg-background p-16 text-xl">
  Let's battle!
</p>

What's included

Components: PrimaryFilledButton, SecondaryFilledButton, InputField, Label, Badge, ListItem, Menu, Dialog, Overlay, ContentCard, Icon, plus a set of pixel-art icon components (e.g. ArrowRightIcon, SearchIcon). All are named exports from pktmn-ui.

Theming: every component accepts a theme prop that sets data-theme on its root element. Available themes: default, fairy-magenta, fire-red, joyful-orange, desert-olive, expansion-lime, technician-green, ace-trainer-sky, legendary-blue, galactic-violet. You can also set data-theme="<name>" on any ancestor element to theme a whole subtree.

What's available:

• Fonts — font-displaySm, font-displayLg, font-textSm, font-textLg (the retro pixel/bitmap inspired font families).
• Type scale — text-xs through text-10xl, each with a matching line-height.
• Semantic colors — bg-background, text-content, text-accent (and the -cmp complements: bg-background-cmp, text-content-cmp, text-accent-cmp). These resolve from the active data-theme, so they restyle automatically per theme. They need a data-theme on the element or an ancestor.
• Primitive colors — the raw palette, e.g. text-blue-saturated, bg-magenta-base, text-olive-faded. These are fixed values and work anywhere, with or without a theme.
• Spacing — utilities are in raw pixels (--spacing: 1px), so p-16 is 16px of padding, gap-8 is 8px, etc.

AI-assisted Figma ↔ code

pktmn-ui is built in the spirit of 1:1 translations between design and code, shipping with AI coding tools to help facilitate both sides:

• pktmn-ui/dist/CLAUDE.md — an AI context file describing how the library maps to its Figma counterpart: theming via Figma variable modes, prop-naming conventions, font/runtime caveats, and gotchas when generating Figma frames from code.
• pktmn-ui/dist/code-connect/*.figma.tsx — Mapping files for every component and icon, declaring which Figma node maps to which pktmn-ui component and how Figma properties map to props.

Point your AI assistant (e.g. Claude Code) at these files when:

• Figma → code: turning a pktmn-ui Figma design into React — the .figma.tsx files tell it the correct component and prop values, and CLAUDE.md covers theming and conventions.
• Code → Figma: generating or updating Figma frames from your code via the Figma MCP / plugin API — CLAUDE.md documents the non-obvious rules (theme variable modes, unloadable fonts, slot population) that trip up a naive translation.

These files are reference material for tooling only — they are not imported at runtime and have no effect on your bundle.