ui-kit/DESIGN.md

# Design System — @jason/ui-kit

The single source of truth for how every app looks and feels. Tokens live in
`src/lib/tokens.json`; TypeScript consumes it directly, the CSS theme is generated,
and the Tailwind preset exposes it as utilities. `npm run tokens:check` prevents drift.

## Color
Warm-tinted neutrals (never pure black/gray) on a warm dark base, with a single
gold brand accent. Semantic colors: success / warning / danger / info.

| Token | Dark (default) | Light | Use |
|---|---|---|---|
| `bg` | #232022 | #FAF8F4 | Page background |
| `surface` / `surface-2` | #2B282A / #333031 | #FFFFFF / #F4F0EA | Cards, raised panels |
| `border` | #3A3638 | #DED8D1 | Hairlines, inputs |
| `text` / `muted` | #F5F1EC / #A99F97 | #272326 / #665F62 | Body / secondary |
| `brand` | #DCBB4F | #79640E | Accent and action |

Every filled semantic color has a matching `*-foreground` token. Do not reuse a
background color as text without a contrast check. `ThemeProvider` supports dark,
light, and system modes; `ThemeScript` prevents a flash before hydration.

## Type
- Display / headings: **Montserrat** (600/700)
- Body / UI: **Open Sans**
- Code / data: **JetBrains Mono**

Import `@jason/ui-kit/fonts.css` to self-host the Latin variable fonts. Without it,
the declared system fallbacks remain safe. Never use Inter or Arial for headings.

## Radius, elevation, motion
- Radius scale: 6 / 10 / 14 / 20px.
- Shadows are **layered and tinted** (`shadow-sm/md/lg/glow`) — depth, not flat.
- Motion: 120/180/320ms with an ease-out curve. **No bounce/elastic easing.**
- Everything honors `prefers-reduced-motion`.

## Component rules
1. Use `cn()` for all conditional classes.
2. Variants via `class-variance-authority`, not ad-hoc conditionals.
3. Interactive primitives wrap Radix (focus traps, keyboard nav, ARIA for free).
4. Focus-visible ring on every interactive element.
5. Don't nest cards inside cards. Use semantic foreground tokens on colored fills.
6. Review every new state in the showcase in dark, light, narrow, and reduced-motion modes.

## Included
Primitives: Button, Card, FormField, Input, Select, Textarea, Label, Checkbox,
Switch, Tabs, Tooltip, Badge, Dialog, DropdownMenu, Table, Pagination, Skeleton,
Toaster, Spinner, EmptyState, StatCard.
Motion: FadeIn, Stagger/StaggerItem.
Animated: AnimatedNumber, SpotlightCard.
Blocks: AppShell, CommandPalette, Hero, FeatureGrid, Pricing.