Design System

primitive/          — raw color values (gray-50 through gray-950, blue-500, etc.)
semantic/           — meaning-based aliases
  ├── background    — page, card, surface, overlay
  ├── foreground    — text-primary, text-secondary, text-muted, text-inverse
  ├── border        — default, muted, focus, error
  ├── accent        — primary, secondary
  └── status        — success, warning, error, info
interactive/        — state-based
  ├── hover         — bg-hover, text-hover
  ├── active        — bg-active
  ├── focus         — ring-color, ring-offset
  └── disabled      — bg-disabled, text-disabled

font-family/        — sans, mono, serif (if used)
font-size/          — xs (12px), sm (14px), base (16px), lg (18px), xl (20px), 2xl-5xl
font-weight/        — normal (400), medium (500), semibold (600), bold (700)
line-height/        — tight (1.2), normal (1.5), relaxed (1.75)
letter-spacing/     — tight (-0.025em), normal (0), wide (0.025em)

0: 0px, 0.5: 2px, 1: 4px, 1.5: 6px, 2: 8px, 2.5: 10px, 3: 12px, 4: 16px,
5: 20px, 6: 24px, 8: 32px, 10: 40px, 12: 48px, 16: 64px, 20: 80px, 24: 96px

radius/             — none (0), sm (4px), md (8px), lg (12px), xl (16px), full (9999px)
shadow/             — none, sm, md, lg, xl, 2xl, inner
border-width/       — 0, 1px, 2px, 4px
z-index/            — dropdown (50), sticky (100), modal (200), popover (300), toast (400)
breakpoint/         — sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px)

duration/           — fast (100ms), normal (200ms), slow (300ms), slower (500ms)
easing/             — ease-in, ease-out, ease-in-out, cubic-bezier(0.4, 0, 0.2, 1)

{
  "$schema": "design-tokens",
  "version": "1.0.0",
  "colors": {
    "primitive": { "gray": { "50": "#fafafa", "900": "#171717" } },
    "semantic": {
      "background": { "page": "{colors.primitive.gray.50}", "card": "#ffffff" },
      "foreground": { "text-primary": "{colors.primitive.gray.900}", "text-secondary": "#737373", "text-muted": "#a3a3a3" },
      "accent": { "primary": "#7c6ff0", "primary-foreground": "#ffffff", "secondary": "#6b7280" }
    }
  },
  "typography": { ... },
  "spacing": { ... }
}

## Component: [Name]

**Category:** atoms | molecules | organisms
**Shadcn equivalent:** [shadcn-svelte component name, if applicable]

### Variants
- [List all visual variants]

### States
- Default, Hover, Active, Focus, Disabled, Loading, Error

### Props / Slots
- [What's configurable — size, color, icon, label, etc.]

### Accessibility
- Role: [ARIA role]
- Keyboard: [Tab, Enter, Escape, Arrow keys behavior]
- Screen reader: [What gets announced]

### Usage Guidelines
- When to use vs. alternatives
- Do's and don'ts

### Token Dependencies
- Colors: [which tokens]
- Typography: [which tokens]
- Spacing: [which tokens]

## Design System Audit — [Date]

### Summary
- Components: X in Penpot, Y in code, Z fully synced
- Token drift: [list mismatches]
- Missing states: [list components with incomplete states]

### 🔴 Critical
- [Issues that break consistency or accessibility]

### 🟡 Important
- [Issues that should be fixed soon]

### 🔵 Minor
- [Nice-to-haves, polish items]

### ✅ Healthy
- [What's in good shape]

// tailwind.config.js (generated from tokens)
export default {
  theme: {
    extend: {
      colors: {
        // From semantic tokens
        background: 'var(--color-background)',
        foreground: 'var(--color-foreground)',
        primary: { DEFAULT: 'var(--color-accent-primary)', foreground: 'var(--color-accent-primary-foreground)' },
      },
      borderRadius: {
        // From radius tokens
        sm: 'var(--radius-sm)',
        md: 'var(--radius-md)',
        lg: 'var(--radius-lg)',
      }
    }
  }
}