Trigger	Example
Create design system	"Create a design system for my app"
Design tokens	"Set up design tokens for colors and spacing"
Component architecture	"Design component structure using atomic design"
Accessibility	"Ensure WCAG 2.1 compliance for my components"
Dark mode	"Implement theming with dark mode support"

Quick Reference

Task	Output
Design tokens	Color, typography, spacing, shadows JSON
Component structure	Atomic design hierarchy (atoms, molecules, organisms)
Theming	CSS variables or ThemeProvider setup
Accessibility	WCAG 2.1 AA compliant patterns
Documentation	Component docs with props, examples, a11y notes

Bundled Resources

references/component-examples.md - Complete component implementations
templates/design-tokens-template.json - W3C design token format
templates/component-template.tsx - React component template
checklists/design-system-checklist.md - Design system audit checklist

Design System Philosophy

What is a Design System?

A design system is more than a component library—it's a collection of:

Design Tokens: Foundational design decisions (colors, spacing, typography)
Components: Reusable UI building blocks
Patterns: Common UX solutions and compositions
Guidelines: Rules, principles, and best practices
Documentation: How to use everything effectively

Core Principles

1. Consistency Over Creativity

Predictable patterns reduce cognitive load
Users learn once, apply everywhere
Designers and developers speak the same language

2. Accessible by Default

WCAG 2.1 Level AA compliance minimum
Keyboard navigation built-in
Screen reader support from the start

3. Scalable and Maintainable

Design tokens enable global changes
Component composition reduces duplication
Versioning and deprecation strategies

4. Developer-Friendly

Clear API contracts
Comprehensive documentation
Easy to integrate and customize

Design Tokens

Design tokens are the atomic design decisions that define your system's visual language.

Token Categories

1. Color Tokens

Primitive Colors (Raw values):

{
  "color": {
    "primitive": {
      "blue": {
        "50": "#eff6ff",
        "100": "#dbeafe",
        "200": "#bfdbfe",
        "300": "#93c5fd",
        "400": "#60a5fa",
        "500": "#3b82f6",
        "600": "#2563eb",
        "700": "#1d4ed8",
        "800": "#1e40af",
        "900": "#1e3a8a",
        "950": "#172554"
      }
    }
  }
}

Semantic Colors (Contextual meaning):

{
  "color": {
    "semantic": {
      "brand": {
        "primary": "{color.primitive.blue.600}",
        "primary-hover": "{color.primitive.blue.700}",
        "primary-active": "{color.primitive.blue.800}"
      },
      "text": {
        "primary": "{color.primitive.gray.900}",
        "secondary": "{color.primitive.gray.600}",
        "tertiary": "{color.primitive.gray.500}",
        "disabled": "{color.primitive.gray.400}",
        "inverse": "{color.primitive.white}"
      },
      "background": {
        "primary": "{color.primitive.white}",
        "secondary": "{color.primitive.gray.50}",
        "tertiary": "{color.primitive.gray.100}"
      },
      "feedback": {
        "success": "{color.primitive.green.600}",
        "warning": "{color.primitive.yellow.600}",
        "error": "{color.primitive.red.600}",
        "info": "{color.primitive.blue.600}"
      }
    }
  }
}

Accessibility: Ensure color contrast ratios meet WCAG 2.1 Level AA:

Normal text: 4.5:1 minimum
Large text (18pt+ or 14pt+ bold): 3:1 minimum
UI components and graphics: 3:1 minimum

2. Typography Tokens

{
  "typography": {
    "fontFamily": {
      "sans": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
      "serif": "'Georgia', 'Times New Roman', serif",
      "mono": "'Fira Code', 'Courier New', monospace"
    },
    "fontSize": {
      "xs": "0.75rem",     // 12px
      "sm": "0.875rem",    // 14px
      "base": "1rem",      // 16px
      "lg": "1.125rem",    // 18px
      "xl": "1.25rem",     // 20px
      "2xl": "1.5rem",     // 24px
      "3xl": "1.875rem",   // 30px
      "4xl": "2.25rem",    // 36px
      "5xl": "3rem"        // 48px
    },
    "fontWeight": {
      "normal": 400,
      "medium": 500,
      "semibold": 600,
      "bold": 700
    },
    "lineHeight": {
      "tight": 1.25,
      "normal": 1.5,
      "relaxed": 1.75,
      "loose": 2
    },
    "letterSpacing": {
      "tight": "-0.025em",
      "normal": "0",
      "wide": "0.025em"
    }
  }
}

3. Spacing Tokens

Scale: Use a consistent spacing scale (commonly 4px or 8px base)

{
  "spacing": {
    "0": "0",
    "1": "0.25rem",   // 4px
    "2": "0.5rem",    // 8px
    "3": "0.75rem",   // 12px
    "4": "1rem",      // 16px
    "5": "1.25rem",   // 20px
    "6": "1.5rem",    // 24px
    "8": "2rem",      // 32px
    "10": "2.5rem",   // 40px
    "12": "3rem",     // 48px
    "16": "4rem",     // 64px
    "20": "5rem",     // 80px
    "24": "6rem"      // 96px
  }
}

Component-Specific Spacing:

{
  "component": {
    "button": {
      "padding-x": "{spacing.4}",
      "padding-y": "{spacing.2}",
      "gap": "{spacing.2}"
    },
    "card": {
      "padding": "{spacing.6}",
      "gap": "{spacing.4}"
    }
  }
}

4. Border Radius Tokens

{
  "borderRadius": {
    "none": "0",
    "sm": "0.125rem",   // 2px
    "base": "0.25rem",  // 4px
    "md": "0.375rem",   // 6px
    "lg": "0.5rem",     // 8px
    "xl": "0.75rem",    // 12px
    "2xl": "1rem",      // 16px
    "full": "9999px"
  }
}

5. Shadow Tokens

{
  "shadow": {
    "xs": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
    "sm": "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1)",
    "base": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)",
    "md": "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)",
    "lg": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)",
    "xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)"
  }
}

Component Architecture

Atomic Design Methodology

Atoms → Molecules → Organisms → Templates → Pages

Atoms (Primitive Components)

Basic building blocks that can't be broken down further.

Examples:

Button
Input
Label
Icon
Badge
Avatar

Button Component:

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  icon?: React.ReactNode;
  children: React.ReactNode;
}

See references/component-examples.md for complete Button implementation with variants, sizes, and styling patterns.

Molecules (Simple Compositions)

Groups of atoms that function together.

Examples:

SearchBar (Input + Button)
FormField (Label + Input + ErrorMessage)
Card (Container + Title + Content + Actions)

FormField Molecule:

interface FormFieldProps {
  label: string;
  name: string;
  error?: string;
  hint?: string;
  required?: boolean;
  children: React.ReactNode;
}

See references/component-examples.md for FormField, Card (compound component pattern), Input with variants, Modal, and more composition examples.

Organisms (Complex Compositions)

Complex UI components made of molecules and atoms.

Examples:

Navigation Bar
Product Card Grid
User Profile Section
Modal Dialog

Templates (Page Layouts)

Page-level structures that define content placement.

Examples:

Dashboard Layout (Sidebar + Header + Main Content)
Marketing Page Layout (Hero + Features + Footer)
Settings Page Layout (Tabs + Content Panels)

Pages (Specific Instances)

Actual pages with real content.

Component API Design

Props Best Practices

1. Predictable Prop Names

// ✅ Good: Consistent naming
<Button variant="primary" size="md" />
<Input variant="outlined" size="md" />

// ❌ Bad: Inconsistent
<Button type="primary" sizeMode="md" />
<Input style="outlined" inputSize="md" />

2. Sensible Defaults

// ✅ Good: Provides defaults
interface ButtonProps {
  variant?: 'primary' | 'secondary';  // Default: primary
  size?: 'sm' | 'md' | 'lg';          // Default: md
}

// ❌ Bad: Everything required
interface ButtonProps {
  variant: 'primary' | 'secondary';
  size: 'sm' | 'md' | 'lg';
  color: string;
  padding: string;
}

3. Composition Over Configuration

// ✅ Good: Composable
<Card>
  <Card.Header>
    <Card.Title>Title</Card.Title>
  </Card.Header>
  <Card.Body>Content</Card.Body>
  <Card.Footer>Actions</Card.Footer>
</Card>

// ❌ Bad: Too many props
<Card
  title="Title"
  content="Content"
  footerContent="Actions"
  hasHeader={true}
  hasFooter={true}
/>

4. Polymorphic Components Allow components to render as different HTML elements:

<Button as="a" href="/login">Login</Button>
<Button as="button" onClick={handleClick}>Click Me</Button>

See references/component-examples.md for complete polymorphic component TypeScript patterns.

Theming and Dark Mode

Theme Structure

interface Theme {
  colors: {
    brand: {
      primary: string;
      secondary: string;
    };
    text: {
      primary: string;
      secondary: string;
    };
    background: {
      primary: string;
      secondary: string;
    };
    feedback: {
      success: string;
      warning: string;
      error: string;
      info: string;
    };
  };
  typography: {
    fontFamily: {
      sans: string;
      mono: string;
    };
    fontSize: Record<string, string>;
  };
  spacing: Record<string, string>;
  borderRadius: Record<string, string>;
  shadow: Record<string, string>;
}

Dark Mode Implementation

Approach 1: CSS Variables

:root {
  --color-bg-primary: #ffffff;
  --color-text-primary: #000000;
}

[data-theme="dark"] {
  --color-bg-primary: #1a1a1a;
  --color-text-primary: #ffffff;
}

Approach 2: Tailwind CSS Dark Mode

<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
  Content
</div>

Approach 3: Styled Components ThemeProvider

const lightTheme = { background: '#fff', text: '#000' };
const darkTheme = { background: '#000', text: '#fff' };

<ThemeProvider theme={isDark ? darkTheme : lightTheme}>
  <App />
</ThemeProvider>

Accessibility Guidelines

WCAG 2.1 Level AA Compliance

Color Contrast

Normal text (< 18pt): 4.5:1 minimum
Large text (≥ 18pt or ≥ 14pt bold): 3:1 minimum
UI components: 3:1 minimum

Tools: Use contrast checkers like WebAIM Contrast Checker

Keyboard Navigation

// ✅ All interactive elements must be keyboard accessible
<button
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  Click me
</button>

// ✅ Focus management
<Modal>
  <FocusTrap>
    {/* Modal content */}
  </FocusTrap>
</Modal>

ARIA Attributes

Essential ARIA patterns:

aria-label: Provide accessible names
aria-expanded: Communicate expanded/collapsed state
aria-controls: Associate controls with content
aria-live: Announce dynamic content changes

Screen Reader Support

Use semantic HTML elements (<button>, <nav>, <main>)
Avoid div/span soup for interactive elements
Provide meaningful labels for all controls

See references/component-examples.md for complete accessibility examples including Skip Links, focus traps, and ARIA patterns.

Documentation Standards

Component Documentation Template

Each component should document:

Purpose: What the component does
Usage: Import statement and basic example
Variants: Available visual styles
Props: Complete prop table with types, defaults, descriptions
Accessibility: Keyboard support, ARIA attributes, screen reader behavior
Examples: Common use cases with code

Use Storybook, Docusaurus, or similar tools for interactive documentation.

See templates/component-template.tsx for the standard component structure.

Design System Workflow

1. Design Phase

Audit existing patterns: Identify inconsistencies
Define design tokens: Colors, typography, spacing
Create component inventory: List all needed components
Design in Figma: Create component library

2. Development Phase

Set up tooling: Storybook, TypeScript, testing
Implement tokens: CSS variables or theme config
Build atoms first: Start with primitives
Compose upward: Build molecules, organisms
Document as you go: Write docs alongside code

3. Adoption Phase

Create migration guide: Help teams adopt
Provide codemods: Automate migrations when possible
Run workshops: Train teams on usage
Gather feedback: Iterate based on real usage

4. Maintenance Phase

Version semantically: Major/minor/patch releases
Deprecation strategy: Phase out old components gracefully
Changelog: Document all changes
Monitor adoption: Track usage across products

Quick Start Checklist

When creating a new design system:

design-system-starter

Design System Starter

Quick Start

Triggers