---

name: design-system description: | Design token systems and component architecture for web and React Native. Use when: implementing design-system, building UI components, defining tokens, creating themed interfaces. Do not use for: UX decisions (use ux-design), business logic, data fetching. Workflow: ux-design (what/why) → this skill (tokens, components) → nextjs/expo-react-native (integration). references:

• token-examples.md # W3C DTCG format examples, theme files
• examples.md # Headless hooks, Compound components examples

---

Design System

Token Architecture

Multi-Tier Hierarchy

CopyTier 1: Primitive     →  Raw values, no meaning
Tier 2: Semantic      →  Intent/purpose ← USE THIS
Tier 3: Component     →  (Optional) Component-specific overrides

Copycolor.blue.500              (primitive) - NEVER use directly
    ↓
color.interactive.primary   (semantic) ← use this in components
    ↓
button.bg.primary           (component, optional)

Rule: Components only reference Semantic tokens. Never Primitive.

Why 3 Tiers?

Semantic Token Categories

---

Component Architecture

Headless + Styled Separation

Copy┌──────────────────────────────────────┐
│  Headless Layer                      │
│  Behavior + A11y + Keyboard          │
│  No styles, reusable across brands   │
└──────────────────────────────────────┘
                 ↓
┌──────────────────────────────────────┐
│  Styled Layer                        │
│  Headless + Tokens = UI Component    │
└──────────────────────────────────────┘

Rule: Headless handles behavior. Styled handles appearance. Never mix.

Why Separate?

File Structure

Copysrc/shared/ui/
├── tokens/          # primitive, semantic, themes
├── headless/        # useButton, useToggle, useDialog
├── styled/          # Button, Toggle, Dialog (uses headless)
├── primitives/      # Box, Text, Stack
└── patterns/        # FormField, ConfirmDialog

---

Preferred Patterns

Rule: Variant props over booleans. Composition over configuration.

---

Platform Output

Web (CSS Custom Properties)

Copy:root {
  --color-bg-primary: #ffffff;
  --color-text-primary: #0f172a;
  --color-interactive-primary: #2563eb;
}

[data-theme="dark"] {
  --color-bg-primary: #0f172a;
  --color-text-primary: #f9fafb;
}

React Native (TypeScript)

Copyexport const tokens = {
  color: {
    bg: { primary: '#ffffff', secondary: '#f9fafb' },
    text: { primary: '#0f172a', secondary: '#475569' },
    interactive: { primary: '#2563eb' },
  },
  spacing: {
    component: { xs: 4, sm: 8, md: 12, lg: 16, xl: 24 },
  },
} as const;

---

Accessibility Requirements

Rule: Color is never the only indicator. Always pair with icon, text, or pattern.

Focus States

Copy:focus-visible {
  outline: 2px solid var(--color-border-focus);
  outline-offset: 2px;
}

:focus:not(:focus-visible) {
  outline: none;
}

Reduced Motion

Copy@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

---

Quick Checklist

Tokens

• No hardcoded values in components (colors, spacing, etc.)
• Using Semantic tokens, not Primitive
• Dark theme remaps Semantic tokens only

Components

• Headless hook for behavior + a11y
• Styled component uses tokens only
• Using variant / size / colorScheme props (not booleans)
• All states defined: default, hover, focus, active, disabled, loading

Accessibility

• Color not sole indicator
• Focus visible (2px+ outline)
• Touch targets 44pt+
• Reduced motion respected
• ARIA attributes correct