Design System Starter

<!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->
---
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):
```json
{
  "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):
```json
{
  "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

```json
{
  "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):

```json
{
  "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

```json
{
  "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:**
```typescript
// 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):**
```typescript
// 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:**
```typescript
<Button as="a" href="/login">Login</Button>
<Button as="button" onClick={handleClick}>Submit</Button>
```

## Theming & Dark Mode

### Approach 1: CSS Variables

```css
: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

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

### Approach 3: ThemeProvider

```typescript
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

| Avoid | Why | Instead |
|---|---|---|
| Hardcoded colors/sizes | Can't theme or maintain | Use design tokens |
| Inconsistent prop names | API confusion | Standard: variant, size, disabled |
| Everything required | Too verbose to use | Sensible defaults |
| Prop-heavy components | Rigid, hard to extend | Compound component pattern |
| Skipping accessibility | Excludes users, legal risk | Accessible by default |
| No documentation | Adoption fails | Document as you build |

## References

- Based on [softaworks/agent-toolkit design-system-starter](https://github.com/softaworks/agent-toolkit/tree/main/skills/design-system-starter) (MIT License)
- [W3C Design Tokens](https://www.w3.org/community/design-tokens/)
- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [Atomic Design](https://bradfrost.com/blog/post/atomic-web-design/)

<!-- Source: .faos/custom/skills/frontend/design-system-starter/SKILL.md -->