/design-system-starter

name: design-system-starter
description: Create and evolve design systems with design tokens, component architecture, accessibility guidelines, and documentation templates. Ensures consistent, scalable, and accessible UI across products.
license: MIT
metadata:
  version: 1.0.0
  tags: [design-system, ui, components, design-tokens, accessibility, frontend]

Design System Starter

Build robust, scalable design systems that ensure visual consistency and exceptional user experiences.

---

Quick Start

Just describe what you need:

Create a design system for my React app with dark mode support

That's it. The skill provides tokens, components, and accessibility guidelines.

---

Triggers

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

1. **Design Tokens**: Foundational design decisions (colors, spacing, typography) 2. **Components**: Reusable UI building blocks 3. **Patterns**: Common UX solutions and compositions 4. **Guidelines**: Rules, principles, and best practices 5. **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**:

{