---
name: design-system-tokens
description: Design token definitions, base component visual specs, dark mode patterns, and pattern library for building consistent UIs
topics: [design-system, tokens, colors, typography, spacing, components, dark-mode, pattern-library]
---

## Summary

## Design Tokens

Design tokens are the atomic values that define the visual language. They are variables, not hard-coded values. Every visual property in the application references a token.

### Color Tokens

**Brand colors:**

```
--color-primary: #2563EB          // Main brand/action color
--color-primary-hover: #1D4ED8    // Interactive state
--color-primary-active: #1E40AF   // Pressed/active state
--color-primary-light: #DBEAFE    // Backgrounds, subtle highlights
--color-primary-lighter: #EFF6FF  // Very subtle tints

--color-secondary: #7C3AED        // Supporting brand color
--color-secondary-hover: #6D28D9  // Interactive state
--color-secondary-light: #EDE9FE  // Backgrounds
```

**Neutral scale:**

```
--color-neutral-50: #FAFAFA       // Lightest background
--color-neutral-100: #F5F5F5      // Card backgrounds, zebra stripes
--color-neutral-200: #E5E5E5      // Borders, dividers
--color-neutral-300: #D4D4D4      // Disabled borders
--color-neutral-400: #A3A3A3      // Muted text, placeholders, disabled text
--color-neutral-500: #737373      // Secondary icons
--color-neutral-600: #525252      // Tertiary text
--color-neutral-700: #404040      // Secondary text
--color-neutral-800: #262626      // Dark backgrounds (dark mode cards)
--color-neutral-900: #171717      // Primary text, dark mode page background
```

**Semantic colors:**

```
--color-success: #16A34A          // Success states, positive actions
--color-success-light: #DCFCE7    // Success backgrounds
--color-success-dark: #15803D     // Success text on light backgrounds

--color-warning: #CA8A04          // Warning states, caution
--color-warning-light: #FEF9C3    // Warning backgrounds
--color-warning-dark: #A16207     // Warning text on light backgrounds

--color-error: #DC2626            // Error states, destructive actions
--color-error-light: #FEE2E2      // Error backgrounds
--color-error-dark: #B91C1C       // Error text on light backgrounds

--color-info: #2563EB             // Informational states
--color-info-light: #DBEAFE       // Info backgrounds
```

**Surface and overlay:**

```
--color-surface: #FFFFFF          // Card/panel surfaces
--color-overlay: rgba(0,0,0,0.5)  // Modal/dialog backdrop
--color-focus-ring: rgba(37,99,235,0.5)  // Focus indicator
```

## Deep Guidance

### Typography Tokens

**Font families:**

```
--font-family: 'Inter', system-ui, -apple-system, sans-serif
--font-family-mono: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace
```

**Font sizes (modular scale):**

```
--text-xs: 0.75rem    // 12px — fine print, labels, badges
--text-sm: 0.875rem   // 14px — secondary text, table cells, help text
--text-base: 1rem     // 16px — body text (default)
--text-lg: 1.125rem   // 18px — subheadings, emphasis
--text-xl: 1.25rem    // 20px — section titles
--text-2xl: 1.5rem    // 24px — page titles
--text-3xl: 1.875rem  // 30px — hero text, major headings
--text-4xl: 2.25rem   // 36px — display headings (marketing, landing)
```

**Font weights:**

```
--font-weight-normal: 400    // Body text
--font-weight-medium: 500    // Buttons, labels, navigation
--font-weight-semibold: 600  // Subheadings, emphasis
--font-weight-bold: 700      // Headings, strong emphasis
```

**Line heights:**

```
--line-height-tight: 1.25    // Headings, single-line labels
--line-height-normal: 1.5    // Body text (default)
--line-height-relaxed: 1.75  // Long-form content, help text
```

**Letter spacing:**

```
--tracking-tight: -0.025em   // Large headings
--tracking-normal: 0         // Body text
--tracking-wide: 0.025em     // Uppercase labels, small caps
```

### Spacing Tokens

Based on a 4px base unit. Every spacing value in the application uses one of these tokens -- no arbitrary pixel values.

```
--space-0: 0           // 0px  — no spacing
--space-0.5: 0.125rem  // 2px  — hairline gaps
--space-1: 0.25rem     // 4px  — tight gaps (icon to label)
--space-1.5: 0.375rem  // 6px  — compact inline spacing
--space-2: 0.5rem      // 8px  — compact spacing (list items, badge padding)
--space-3: 0.75rem     // 12px — default padding (buttons, inputs)
--space-4: 1rem        // 16px — standard spacing (form fields, card padding)
--space-5: 1.25rem     // 20px — medium gaps
--space-6: 1.5rem      // 24px — section padding
--space-8: 2rem        // 32px — large gaps (section spacing)
--space-10: 2.5rem     // 40px — major section gaps
--space-12: 3rem       // 48px — section separators
--space-16: 4rem       // 64px — page-level spacing
--space-20: 5rem       // 80px — hero section padding
--space-24: 6rem       // 96px — page-level vertical rhythm
```

### Border and Shadow Tokens

**Border radii:**

```
--radius-none: 0         // Sharp corners
--radius-sm: 0.25rem     // 4px  — subtle rounding (tags, badges)
--radius-md: 0.5rem      // 8px  — standard rounding (cards, inputs, buttons)
--radius-lg: 0.75rem     // 12px — prominent rounding (modals, panels)
--radius-xl: 1rem        // 16px — large containers, hero cards
--radius-full: 9999px    // Pill shapes, avatars, toggles
```

**Elevation (box shadows):**

```
--shadow-sm: 0 1px 2px rgba(0,0,0,0.05)                          // Subtle lift (buttons, badges)
--shadow-md: 0 4px 6px -1px rgba(0,0,0,0.07), 0 2px 4px -2px rgba(0,0,0,0.05)   // Cards, dropdowns
--shadow-lg: 0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.05)   // Popovers, floating elements
--shadow-xl: 0 20px 25px -5px rgba(0,0,0,0.1), 0 8px 10px -6px rgba(0,0,0,0.04)  // Modals, dialogs
--shadow-inner: inset 0 2px 4px rgba(0,0,0,0.05)                 // Pressed states, input wells
```

**Border widths:**

```
--border-width-thin: 1px     // Default borders (inputs, cards, dividers)
--border-width-medium: 2px   // Focus rings, active tab indicators
--border-width-thick: 4px    // Left-border accents on alerts
```

### Transition Tokens

```
--transition-fast: 150ms ease      // Hover states, color changes
--transition-base: 200ms ease      // Most interactions
--transition-slow: 300ms ease      // Layout shifts, modals appearing
--transition-spring: 300ms cubic-bezier(0.34, 1.56, 0.64, 1)  // Playful bounces (optional)
```

## Dark Mode

When dark mode is required, define a parallel set of semantic tokens that switch based on the color scheme. Components reference semantic tokens, never raw color tokens directly.

### Semantic Token Mapping

```css
:root {
  /* Surfaces */
  --bg-primary: var(--color-neutral-50);
  --bg-secondary: var(--color-neutral-100);
  --bg-card: white;
  --bg-input: white;
  --bg-overlay: rgba(0, 0, 0, 0.5);

  /* Text */
  --text-primary: var(--color-neutral-900);
  --text-secondary: var(--color-neutral-700);
  --text-muted: var(--color-neutral-400);
  --text-inverse: white;

  /* Borders */
  --border-default: var(--color-neutral-200);
  --border-strong: var(--color-neutral-300);
  --border-focus: var(--color-primary);

  /* Shadows */
  --shadow-color: rgba(0, 0, 0, 0.1);
}

@media (prefers-color-scheme: dark) {
  :root {
    /* Surfaces */
    --bg-primary: var(--color-neutral-900);
    --bg-secondary: #1a1a1a;
    --bg-card: var(--color-neutral-800);
    --bg-input: var(--color-neutral-800);
    --bg-overlay: rgba(0, 0, 0, 0.7);

    /* Text */
    --text-primary: var(--color-neutral-50);
    --text-secondary: var(--color-neutral-400);
    --text-muted: var(--color-neutral-500);
    --text-inverse: var(--color-neutral-900);

    /* Borders */
    --border-default: var(--color-neutral-700);
    --border-strong: var(--color-neutral-600);
    --border-focus: #60A5FA;

    /* Shadows — reduced in dark mode, use border emphasis instead */
    --shadow-color: rgba(0, 0, 0, 0.3);
  }
}
```

### Dark Mode Implementation Rules

- **Always use semantic tokens** (`--bg-primary`, `--text-primary`) in components, never raw color tokens (`--color-neutral-900`). This makes dark mode automatic.
- **Test both modes**: Every visual change must be verified in both light and dark mode.
- **Avoid pure black backgrounds**: Use `--color-neutral-900` (#171717) instead of `#000000` -- pure black creates harsh contrast and eye strain.
- **Reduce shadow prominence in dark mode**: Shadows are less visible on dark backgrounds. Use border emphasis or subtle glow effects instead.
- **Adjust semantic color intensity**: Success, warning, and error colors may need lighter variants in dark mode for readability on dark surfaces.
- **Images and illustrations**: Consider providing dark-mode-optimized versions or applying CSS filters (e.g., `brightness(0.9)`) to prevent overly bright images on dark backgrounds.

## Responsive Breakpoints

Define breakpoints as min-width values for mobile-first responsive design:

```
--breakpoint-sm: 640px     // Small devices (landscape phones)
--breakpoint-md: 768px     // Tablets
--breakpoint-lg: 1024px    // Laptops, small desktops
--breakpoint-xl: 1280px    // Large desktops
--breakpoint-2xl: 1536px   // Extra-large screens
```

### Breakpoint Usage

```css
/* Mobile-first: base styles apply to all sizes */
.container { padding: var(--space-4); }

/* Tablet and up */
@media (min-width: 768px) {
  .container { padding: var(--space-6); max-width: 768px; }
}

/* Desktop and up */
@media (min-width: 1024px) {
  .container { padding: var(--space-8); max-width: 1024px; }
}

/* Large desktop */
@media (min-width: 1280px) {
  .container { max-width: 1200px; }
}
```

### Responsive Patterns

- **Stack to grid**: Single-column on mobile, multi-column on desktop
- **Navigation collapse**: Full nav on desktop, hamburger menu below `--breakpoint-md`
- **Table adaptation**: Full table on desktop, card layout below `--breakpoint-md`
- **Touch targets**: Minimum 44x44px on touch devices (below `--breakpoint-lg`)
- **Font scaling**: Base size stays at 16px; heading sizes may reduce on mobile

## Accessibility Requirements

### Color Contrast

All text must meet WCAG 2.1 AA contrast requirements:
- **Normal text (< 18px)**: minimum 4.5:1 contrast ratio against background
- **Large text (>= 18px bold or >= 24px)**: minimum 3:1 contrast ratio
- **UI components and graphical objects**: minimum 3:1 against adjacent colors
- **Focus indicators**: must have 3:1 contrast against both the component and the background

### Focus Indicators

Every interactive element must have a visible focus indicator:

```css
:focus-visible {
  outline: var(--border-width-medium) solid var(--border-focus);
  outline-offset: 2px;
}
```

- Do not remove focus outlines (`outline: none`) without providing an alternative
- Use `:focus-visible` (not `:focus`) to show focus rings only for keyboard navigation
- Focus ring must be visible in both light and dark mode

### Touch Targets

- Minimum interactive element size: 44x44 CSS pixels (WCAG 2.5.5 Target Size)
- Minimum spacing between adjacent touch targets: 8px
- Clickable area may be larger than the visual element (use padding, not just visual size)

### Motion and Animation

- Respect `prefers-reduced-motion`: disable non-essential animations
- Essential animations (loading spinners) should still play but with reduced motion
- Auto-playing animations should have a pause mechanism

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

## Base Components

Define the standard appearance and behavior for every common component:

### Buttons

**Variants:**
- **Primary**: Solid fill (`--color-primary` background, white text). Main call-to-action.
- **Secondary**: Subtle fill (`--color-neutral-100` background, `--text-primary` text). Secondary actions.
- **Outline**: Border only (`--border-default` border, `--text-primary` text). Tertiary actions.
- **Ghost**: No background or border. Minimal visual weight. Navigation, icon-only actions.
- **Destructive**: Red/danger (`--color-error` background, white text). Delete, remove, cancel actions.

**Sizes:**
- **sm**: 28px height, `--text-xs`, `--space-2` horizontal padding
- **md**: 36px height, `--text-sm`, `--space-3` horizontal padding (default)
- **lg**: 44px height, `--text-base`, `--space-4` horizontal padding

**States:**
- **Default**: Normal appearance
- **Hover**: Darker background (e.g., `--color-primary-hover`), cursor pointer
- **Active**: Even darker background (`--color-primary-active`), slight scale-down
- **Focused**: Focus ring visible (`--border-focus` outline)
- **Disabled**: Reduced opacity (0.5), no hover effects, `cursor: not-allowed`
- **Loading**: Label replaced with spinner, interaction disabled, maintains button width

### Form Elements

**Text inputs and textareas:**
- Border: `--border-default`, `--radius-md`
- Focus: `--border-focus` with focus ring
- Error: `--color-error` border + error message below in `--color-error`
- Disabled: `--color-neutral-100` background, reduced opacity
- Height: 36px for inputs (matches button md)

**Labels:**
- Always visible (never use placeholder as the only label)
- Required indicator: asterisk or "(required)" text
- Associated with input via `for`/`id` or wrapping

**Help text:**
- Below input, `--text-xs`, `--text-muted` color
- Explains format expectations (e.g., "Must be at least 8 characters")

**Error messages:**
- Below input, `--text-xs`, `--color-error`
- Describes what went wrong and how to fix it (not just "Invalid")
- Replaces help text when error is active

**Select inputs and dropdowns:**
- Same dimensions and borders as text inputs
- Chevron indicator aligned right
- Option list uses `--shadow-lg` elevation

**Checkboxes and radio buttons:**
- Minimum 20x20px visual size, 44x44px touch target
- Checked state uses `--color-primary`
- Labels always to the right, clickable

### Cards

- Background: `--bg-card`
- Border: `--border-default` or `--shadow-sm`
- Padding: `--space-4` to `--space-6`
- Border radius: `--radius-md`
- **Interactive cards**: hover state increases shadow (`--shadow-md`), cursor pointer
- **Header/footer sections**: separated by `--border-default` divider, visually distinct padding

### Feedback Components

**Toast notifications:**
- Temporary, non-blocking, positioned top-right or bottom-center
- Auto-dismiss after 5 seconds with manual dismiss (X button)
- Variants: success (green), error (red), warning (yellow), info (blue)
- Includes icon + message + optional action link

**Alert banners:**
- Persistent until explicitly dismissed
- Full-width or contained within a section
- Left border accent (`--border-width-thick`) with semantic color
- Variants: info, warning, error, success

**Empty states:**
- Centered illustration or icon
- Explanatory heading and description text
- Call-to-action button ("Create your first [item]")
- Uses `--text-muted` for description

**Loading states:**
- **Skeleton loaders** (preferred for content areas): animated placeholder shapes matching content layout
- **Spinners** (for actions): 20px for inline, 32px for section, 48px for page-level
- **Progress bars** (for known-duration operations): determinate with percentage

### Navigation

- **Header/navbar**: fixed or sticky, `--shadow-sm` or border-bottom, contains logo + primary nav + user menu
- **Sidebar**: collapsible on desktop, overlay on mobile, active item highlighted with `--color-primary-light` background
- **Breadcrumbs**: `--text-sm`, separator chevrons, current page not linked
- **Tabs**: underline style (active tab has `--color-primary` bottom border, `--border-width-medium`), equal or auto width
- **Pagination**: prev/next buttons + page numbers, disabled state for first/last, compact mode on mobile (prev/next only)

### Data Display

- **Tables**: header row with `--bg-secondary` background, row hover state, sortable column headers with indicator icon, responsive (horizontal scroll or card layout on mobile)
- **Lists**: consistent item height and spacing (`--space-2` to `--space-3` between items), interactive items have hover state
- **Badges/tags**: `--radius-full`, `--text-xs`, `--space-1` vertical / `--space-2` horizontal padding, semantic color variants
- **Avatars**: `--radius-full`, sizes 24/32/40px, fallback shows initials on `--color-primary-light` background
- **Stats/metrics**: large value (`--text-2xl`, `--font-weight-bold`), label below (`--text-sm`, `--text-secondary`), optional trend indicator (up/down arrow with green/red)

## Pattern Library

Document recurring UI patterns with implementation guidance:

- **Search with autocomplete**: Debounced input (300ms), dropdown results panel with `--shadow-lg`, keyboard navigation (arrow keys + Enter), "no results" state with suggestion, clear button (X) when input has value
- **Confirmation dialogs**: Modal with overlay, clearly states what will happen ("Delete 3 items? This cannot be undone."), "Cancel" as default/primary action (preventing accidents), destructive action in `--color-error`
- **Inline editing**: Click to edit transforms display text into input, Enter to save, Escape to cancel, loading indicator during save, validation feedback
- **Bulk actions**: Checkbox selection, "Select all" header checkbox, floating action toolbar appears when items selected, count indicator ("3 selected")
- **Wizard/stepper**: Numbered step indicator, completed steps show checkmark, back/next navigation, save progress between steps, summary step before final submit
- **Infinite scroll vs. pagination**: Use pagination for data tables and search results (users need to reference positions). Use infinite scroll for feeds and timelines (users scan sequentially).

## Common Pitfalls

**Inconsistent spacing and typography.** Five different font sizes that are all "kind of like body text." Spacing that varies randomly between 12px and 17px with no system. Fix: define a spacing scale and type scale in the design system. Only use values from the scale.

**Hard-coded color values in components.** Using `#2563EB` directly in a component instead of `var(--color-primary)`. When the brand color changes, you must find-and-replace across the entire codebase. Fix: always reference tokens. Lint for hard-coded color/size values.

**Placeholder text as labels.** Using placeholder text instead of labels for form fields. Placeholders disappear when the user starts typing, leaving them with no indication of what the field expects. Fix: always use visible labels. Placeholders are supplementary hints, not replacements for labels.

**Ignoring touch targets on mobile.** Tiny links and buttons that require precise finger tapping. Fix: ensure all interactive elements meet minimum 44x44px touch target size on mobile.

**Dark mode as an afterthought.** Building the entire UI with hard-coded light colors, then trying to add dark mode later. Fix: use semantic tokens from day one. The cost is near-zero upfront and saves a complete restyle later.

**Missing reduced-motion support.** Animations that cause discomfort for users with vestibular disorders. Fix: always wrap non-essential animations in a `prefers-reduced-motion` check.

**Inconsistent elevation hierarchy.** A card inside a modal has a higher shadow than the modal itself, breaking the visual stacking order. Fix: define an elevation scale (sm < md < lg < xl) and assign levels consistently: page content (none), cards (sm), dropdowns (lg), modals (xl).
