Design System Starter

name: design-system-starter description: Create and evolve design systems with design tokens, component architecture, accessibility guidelines, and theming. Use when building a new design system, setting up design tokens (colors, typography, spacing), implementing atomic design component hierarchy, ensuring WCAG 2.1 compliance, or adding dark mode support. tags: [design-system, tokens, components, accessibility]

Design System Starter

Build robust, scalable design systems with design tokens, component architecture, accessibility, and theming.

When to Use

• Building a new design system from scratch
• Setting up design tokens (colors, typography, spacing, shadows)
• Implementing atomic design component hierarchy
• Ensuring WCAG 2.1 Level AA compliance
• Adding dark mode / theming support

Core Principles

1. Consistency Over Creativity -- Predictable patterns reduce cognitive load
2. Accessible by Default -- WCAG 2.1 Level AA minimum, keyboard nav built-in
3. Scalable and Maintainable -- Tokens enable global changes, composition reduces duplication
4. Developer-Friendly -- Clear API contracts, comprehensive documentation

Design Tokens

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

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}",
        "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}"
      }
    }
  }
}

Contrast requirements (WCAG 2.1 AA):

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

Typography Tokens

{
  "typography": {
    "fontFamily": {
      "sans": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
      "mono": "'Fira Code', 'Courier New', monospace"
    },
    "fontSize": {
      "xs": "0.75rem", "sm": "0.875rem", "base": "1rem",
      "lg": "1.125rem", "xl": "1.25rem", "2xl": "1.5rem",
      "3xl": "1.875rem", "4xl": "2.25rem", "5xl": "3rem"
    },
    "fontWeight": {
      "normal": 400, "medium": 500, "semibold": 600, "bold": 700
    },
    "lineHeight": {
      "tight": 1.25, "normal": 1.5, "relaxed": 1.75
    }
  }
}

Spacing Tokens

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

{
  "spacing": {
    "0": "0", "1": "0.25rem", "2": "0.5rem", "3": "0.75rem",
    "4": "1rem", "5": "1.25rem", "6": "1.5rem", "8": "2rem",
    "10": "2.5rem", "12": "3rem", "16": "4rem", "20": "5rem"
  }
}

Shadow & Border Radius Tokens

{
  "shadow": {
    "sm": "0 1px 3px 0 rgba(0,0,0,0.1), 0 1px 2px -1px rgba(0,0,0,0.1)",
    "md": "0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -2px rgba(0,0,0,0.1)",
    "lg": "0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1)",
    "xl": "0 20px 25px -5px rgba(0,0,0,0.1), 0 8px 10px -6px rgba(0,0,0,0.1)"
  },
  "borderRadius": {
    "none": "0", "sm": "0.125rem", "base": "0.25rem",
    "md": "0.375rem", "lg": "0.5rem", "xl": "0.75rem", "full": "9999px"
  }
}

Component Architecture

Atomic Design Methodology

Atoms (Button, Input, Label, Icon, Badge, Avatar) -> Molecules (SearchBar, FormField, Card) -> Organisms (NavBar, ProductGrid, UserProfile) -> Templates (DashboardLayout, SettingsLayout) -> Pages (specific instances with real data)

Component API Patterns

Predictable prop names:

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

Compound components (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} />

Polymorphic components:

<Button as="a" href="/login">Login</Button>
<Button as="button"

Theming & Dark Mode

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 Dark Mode

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

Approach 3: ThemeProvider

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

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

Accessibility

Keyboard Navigation

All interactive elements must be keyboard accessible:

• Tab order follows logical reading order
• Focus indicators are visible (never outline: none without replacement)
• Modal dialogs trap focus
• Escape closes overlays

ARIA Essentials

• aria-label: Accessible names for icon-only buttons
• aria-expanded: Communicate expanded/collapsed state
• aria-controls: Associate controls with controlled content
• aria-live: Announce dynamic content changes
• Use semantic HTML (<button>, <nav>, <main>) over div soup

Screen Reader Support

• Meaningful labels for all controls
• Alt text for informational images
• Skip links for navigation
• Status announcements for async operations

Design System Workflow

1. Audit -- Identify existing inconsistencies
2. Define tokens -- Colors, typography, spacing
3. Build atoms -- Start with primitive components
4. Compose upward -- Molecules, then organisms
5. Document -- Write docs alongside code
6. Adopt -- Migration guide + team workshops
7. Maintain -- Semantic versioning, deprecation strategy, changelog

Quick Start Checklist

• Define design principles and values
• Create primitive color palette (50-950 scale)
• Define semantic color tokens
• Set typography scale and font families
• Establish spacing scale
• Design atomic components (Button, Input, Label)
• Implement theming system (light/dark)
• Ensure WCAG 2.1 Level AA compliance
• Set up component documentation (Storybook or similar)
• Establish versioning and release strategy

Anti-Patterns

References

• Based on softaworks/agent-toolkit design-system-starter (MIT License)
• W3C Design Tokens
• WCAG 2.1 Guidelines
• Atomic Design