Design System Starter

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

---

Quick Reference

---

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:

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

• [ ] Define design principles and values
• [ ] Establish design token structure (colors, typography, spacing)
• [ ] Create primitive color palette (50-950 scale)
• [ ] Define semantic color tokens (brand, text, background, feedback)
• [ ] Set typography scale and font families
• [ ] Establish spacing scale (4px or 8px base)
• [ ] Design atomic components (Button, Input, Label, etc.)
• [ ] Implement theming system (light/dark mode)
• [ ] Ensure WCAG 2.1 Level AA compliance
• [ ] Set up documentation (Storybook or similar)
• [ ] Create usage examples for each component
• [ ] Establish versioning and release strategy
• [ ] Create migration guides for adopting teams

Design System Checklist

Use this comprehensive checklist when creating or auditing a design system.

---

Foundation

Design Principles

• [ ] Principles Defined: Core design principles documented (consistency, accessibility, simplicity, etc.)
• [ ] Values Articulated: Team values reflected in design decisions
• [ ] Design Language Documented: Visual design language explained (tone, personality)

Design Tokens

Color Tokens

• [ ] Primitive Colors Defined: Base color palette (50-950 scale for each hue)
• [ ] Semantic Colors Mapped: Brand, text, background, border, feedback colors
• [ ] Color Contrast Validated: All text meets WCAG 2.1 Level AA (4.5:1 for normal text, 3:1 for large text)
• [ ] Dark Mode Colors: Dark theme variants defined (if applicable)
• [ ] Token Naming: Consistent, semantic naming (text-primary vs gray-900)

Typography Tokens

• [ ] Font Families Selected: Primary (sans), secondary (serif), mono fonts
• [ ] Type Scale Established: Font sizes from xs (12px) to 5xl (48px)
• [ ] Font Weights Defined: At least 3 weights (normal, medium, bold)
• [ ] Line Heights Set: Tight (headings), normal (body), relaxed (paragraphs)
• [ ] Letter Spacing: Defined for uppercase and large headings

Spacing Tokens

• [ ] Spacing Scale Created: Consistent scale (4px or 8px base)
• [ ] Spacing Values: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24
• [ ] Component Spacing: Specific spacing for components (button padding, card gap)

Other Tokens

• [ ] Border Radius: none, sm, base, md, lg, xl, 2xl, full
• [ ] Shadows: xs, sm, base, md, lg, xl
• [ ] Transitions: Duration and easing functions
• [ ] Z-Index Scale: Defined layering system

---

Components

Atomic Components (Atoms)

Button

• [ ] Variants: Primary, secondary, outline, ghost
• [ ] Sizes: sm, md, lg
• [ ] States: Default, hover, active, focus, disabled, loading
• [ ] Icons: Support for left/right icons
• [ ] Full Width: Option for full-width buttons
• [ ] Accessibility: Keyboard accessible, ARIA attributes

Input

• [ ] Types: Text, email, password, number, search
• [ ] Sizes: sm, md, lg
• [ ] States: Default, focus, error, disabled
• [ ] Icons: Support for left/right icons
• [ ] Helper Text: Support for hints and error messages
• [ ] Accessibility: Labels, ARIA descriptions

Checkbox & Radio

• [ ] Sizes: sm, md, lg
• [ ] States: Default, checked, indeterminate, disabled
• [ ] Labels: Properly associated labels
• [ ] Accessibility: Keyboard navigation, ARIA states

Select / Dropdown

• [ ] Single Select: Basic dropdown
• [ ] Multi Select: Multiple selection support
• [ ] Search: Searchable options (if applicable)
• [ ] States: Default, open, disabled
• [ ] Accessibility: Keyboard navigation, ARIA combobox

Badge

• [ ] Variants: Default, success, warning, error, info
• [ ] Sizes: sm, md, lg
• [ ] Removable: Option for dismiss button

Avatar

• [ ] Sizes: xs, sm, md, lg, xl
• [ ] Fallback: Initials or default icon
• [ ] Status Indicator: Online/offline dot (if applicable)

Icon

• [ ] Icon Set: Consistent icon library (Heroicons, Lucide, etc.)
• [ ] Sizes: 16px, 20px, 24px, 32px
• [ ] Accessibility: ARIA labels or aria-hidden

Molecular Components (Molecules)

Form Field

• [ ] Composition: Label + Input + Helper/Error
• [ ] Required Indicator: Asterisk or (required) text
• [ ] Error States: Validation error display
• [ ] Accessibility: Proper label associations

Search Bar

• [ ] Composition: Input + Search button/icon
• [ ] Clear Button: X to clear search
• [ ] Keyboard Support: Enter to submit

Card

• [ ] Variants: Default, outlined, elevated
• [ ] Composition: Header, body, footer sections
• [ ] Hover State: If interactive
• [ ] Clickable Area: Full card clickable (if applicable)

Alert / Toast

• [ ] Variants: Success, warning, error, info
• [ ] Dismissible: Close button
• [ ] Icons: Contextual icons for each variant
• [ ] Actions: Optional action buttons

Organism Components

Navigation Bar

• [ ] Responsive: Mobile hamburger menu
• [ ] Logo: Branding placement
• [ ] Links: Primary navigation links
• [ ] Actions: Login/signup buttons
• [ ] Dropdown: Nested menu support
• [ ] Accessibility: Keyboard navigation, ARIA navigation

Modal / Dialog

• [ ] Overlay: Background overlay
• [ ] Close Button: X button and ESC key
• [ ] Focus Trap: Focus stays within modal
• [ ] Sizes: sm, md, lg, full
• [ ] Accessibility: Focus management, ARIA dialog

Table

• [ ] Header: Column headers
• [ ] Sortable: Click to sort columns
• [ ] Selectable: Checkbox selection
• [ ] Pagination: Built-in or separate component
• [ ] Responsive: Mobile-friendly (stacked or scrollable)
• [ ] Accessibility: Proper table semantics

Pagination

• [ ] Page Numbers: Current and nearby pages
• [ ] Previous/Next: Arrow navigation
• [ ] First/Last: Jump to first/last page
• [ ] Page Size: Option to change items per page

---

Patterns

Layout Patterns

• [ ] Grid System: Responsive grid (12-column or flexbox/grid-based)
• [ ] Container: Max-width container for content
• [ ] Stack: Vertical spacing component
• [ ] Cluster: Horizontal spacing component
• [ ] Sidebar Layout: Sidebar + main content

Form Patterns

• [ ] Form Validation: Client-side validation patterns
• [ ] Multi-Step Forms: Wizard/stepper component
• [ ] Inline Editing: Edit-in-place pattern
• [ ] Auto-Save: Periodic save pattern

Navigation Patterns

• [ ] Breadcrumbs: Path navigation
• [ ] Tabs: Tab navigation component
• [ ] Sidebar Navigation: Collapsible sidebar
• [ ] Mega Menu: Large dropdown navigation

Feedback Patterns

• [ ] Loading States: Skeletons, spinners, progress bars
• [ ] Empty States: Illustrations and CTAs for empty data
• [ ] Error States: User-friendly error pages (404, 500)
• [ ] Success Confirmation: Post-action feedback

---

Accessibility (WCAG 2.1 Level AA)

Perceivable

• [ ] Color Contrast: 4.5:1 for normal text, 3:1 for large text
• [ ] Color Independence: Information not conveyed by color alone
• [ ] Text Alternatives: Alt text for images
• [ ] Captions: Video/audio content has captions (if applicable)

Operable

• [ ] Keyboard Navigation: All interactive elements keyboard accessible
• [ ] Focus Indicators: Visible focus states (outline, ring)
• [ ] No Keyboard Traps: Users can navigate away from all elements
• [ ] Skip Links: "Skip to main content" link
• [ ] Touch Targets: Minimum 44x44px for mobile

Understandable

• [ ] Language Attribute: <html lang="en">
• [ ] Labels: Form inputs have labels
• [ ] Error Messages: Clear, specific error messages
• [ ] Consistent Navigation: Navigation is consistent across pages

Robust

• [ ] Valid HTML: Markup validates
• [ ] ARIA Attributes: Proper ARIA labels, roles, states
• [ ] Name, Role, Value: Interactive elements have accessible name

---

Documentation

Component Documentation

• [ ] Usage Examples: Code examples for each component
• [ ] Props API: Table of props with types and defaults
• [ ] Variants: Visual examples of all variants
• [ ] States: Examples of all interactive states
• [ ] Accessibility Notes: Keyboard shortcuts, ARIA attributes
• [ ] Do's and Don'ts: Usage guidelines with examples

Design Guidelines

• [ ] When to Use: Guidance on component selection
• [ ] Composition: How to combine components
• [ ] Content Guidelines: Copywriting standards
• [ ] Spacing Guidelines: How to apply spacing tokens
• [ ] Responsive Patterns: Mobile-first approach

Getting Started

• [ ] Installation: How to install the design system
• [ ] Setup: Configuration instructions
• [ ] Theming: How to customize tokens
• [ ] Migration Guide: Upgrading from previous versions

---

Tooling & Infrastructure

Development Tools

• [ ] Component Library: React/Vue/Angular/Web Components
• [ ] Storybook: Component playground and documentation
• [ ] TypeScript: Type definitions for all components
• [ ] Testing: Unit and visual regression tests
• [ ] Linting: ESLint/Stylelint configured

Build & Distribution

• [ ] Package Manager: NPM/Yarn package published
• [ ] Versioning: Semantic versioning (major.minor.patch)
• [ ] Changelog: All changes documented
• [ ] Tree-Shaking: Components importable individually
• [ ] Bundle Size: Optimized for performance

Design Tools

• [ ] Figma Library: Component library in Figma
• [ ] Design Tokens: Tokens exported to Figma (Style Dictionary, Figma Tokens)
• [ ] Shared Styles: Colors, text styles, effects synced
• [ ] Component Variants: All variants available in Figma

---

Theming & Customization

Theme Support

• [ ] Light Theme: Default light mode
• [ ] Dark Theme: Dark mode variant
• [ ] Theme Toggle: Mechanism to switch themes
• [ ] System Preference: Respect OS theme preference
• [ ] Persistent Choice: Remember user's theme choice

Customization

• [ ] Token Override: Ability to override design tokens
• [ ] CSS Variables: Tokens exposed as CSS variables
• [ ] Theme API: Programmatic theme customization
• [ ] Brand Variants: Support for multiple brands (if applicable)

---

Quality Assurance

Visual Testing

• [ ] Visual Regression Tests: Chromatic, Percy, or similar
• [ ] Cross-Browser Testing: Chrome, Firefox, Safari, Edge
• [ ] Responsive Testing: Mobile, tablet, desktop viewports
• [ ] Dark Mode Testing: All components in dark mode

Functional Testing

• [ ] Unit Tests: Component logic tested
• [ ] Integration Tests: Component interactions tested
• [ ] Accessibility Tests: Automated a11y tests (axe, WAVE)

Performance

• [ ] Bundle Size: < 100KB gzipped for core components
• [ ] Lazy Loading: Heavy components lazy-loaded
• [ ] Tree-Shaking: Unused components not included

---

Governance

Contribution Guidelines

• [ ] CONTRIBUTING.md: How to contribute
• [ ] Code of Conduct: Community standards
• [ ] PR Template: Standard pull request format
• [ ] Review Process: How contributions are reviewed

Versioning & Deprecation

• [ ] Semantic Versioning: Follow SemVer
• [ ] Deprecation Policy: How long deprecated components are supported
• [ ] Migration Guides: Help for breaking changes
• [ ] Release Notes: What changed in each version

Roadmap

• [ ] Public Roadmap: Future plans visible
• [ ] Feedback Channel: Users can request features
• [ ] Regular Releases: Predictable release schedule

---

Adoption & Maintenance

Onboarding

• [ ] Getting Started Guide: Quick start documentation
• [ ] Tutorial: Step-by-step walkthrough
• [ ] Video Demos: Recorded demos (optional)
• [ ] Support Channel: Slack, Discord, or forum

Metrics

• [ ] Adoption Tracking: Monitor usage across products
• [ ] Component Usage: Which components are most used
• [ ] Issue Tracking: Bug reports and feature requests
• [ ] Performance Metrics: Bundle size, load times

Iteration

• [ ] Quarterly Reviews: Regular design system audits
• [ ] User Research: Gather feedback from users
• [ ] Component Deprecation: Remove unused components
• [ ] Design Updates: Refresh styles periodically

---

Pre-Launch Checklist

Before publishing v1.0:

• [ ] All Atoms Complete: Button, Input, Checkbox, Radio, Select, Badge, Avatar, Icon
• [ ] Key Molecules Complete: FormField, Card, Alert, SearchBar
• [ ] Core Organisms Complete: Modal, Navigation, Table, Pagination
• [ ] Design Tokens Finalized: Colors, typography, spacing locked
• [ ] Accessibility Audit: WCAG 2.1 Level AA compliance verified
• [ ] Documentation Complete: All components documented
• [ ] Tests Passing: 100% test pass rate
• [ ] Figma Library Published: Design library available
• [ ] NPM Package Published: Package available on NPM
• [ ] Migration Guide: From previous system or custom components

---

Post-Launch

• [ ] Announce Launch: Internal announcement and blog post
• [ ] Training Sessions: Workshops for teams
• [ ] Office Hours: Regular Q&A sessions
• [ ] Gather Feedback: Collect early adopter feedback
• [ ] Iterate Quickly: Address issues in patch releases

---

Checklist Version: 1.0.0 Skill: design-system-starter v1.0.0 Last Updated: 2025-10-31

Design System Starter

A comprehensive Claude Code skill for creating and evolving production-ready design systems with design tokens, component architecture, accessibility guidelines, and documentation templates.

Purpose

This skill helps you build robust, scalable design systems that ensure visual consistency and exceptional user experiences across your products. It provides structured guidance for:

• Defining and organizing design tokens (colors, typography, spacing, shadows)
• Architecting components using atomic design methodology
• Implementing theming and dark mode support
• Ensuring WCAG 2.1 Level AA accessibility compliance
• Creating comprehensive component documentation
• Establishing maintainable design system workflows

When to Use

Use this skill when you need to:

• Create a new design system from scratch
• Standardize UI patterns across multiple products
• Implement design tokens for consistent styling
• Structure components using atomic design principles
• Ensure accessibility compliance (WCAG 2.1 AA)
• Set up theming and dark mode support
• Document component libraries effectively
• Migrate from inconsistent UI patterns to a unified system

How It Works

The skill provides comprehensive guidance and templates organized around five core areas:

1. Design Tokens

Structured JSON templates for defining foundational design decisions:

• Color systems: Primitive colors (50-950 scale) and semantic tokens (brand, text, background, feedback)
• Typography: Font families, sizes, weights, line heights, letter spacing
• Spacing: Consistent scale based on 4px or 8px units
• Border radius: Reusable corner rounding values
• Shadows: Elevation system for depth

2. Component Architecture

Atomic design methodology for building UI:

• Atoms: Primitive components (Button, Input, Label, Icon)
• Molecules: Simple compositions (FormField, SearchBar, Card)
• Organisms: Complex compositions (Navigation, Modal, ProductGrid)
• Templates: Page layouts
• Pages: Specific instances with real content

3. Accessibility

Built-in WCAG 2.1 Level AA compliance:

• Color contrast validation (4.5:1 for normal text, 3:1 for large text)
• Keyboard navigation patterns
• ARIA attributes and screen reader support
• Focus management

4. Theming

Multiple approaches for light/dark mode:

• CSS custom properties
• Tailwind CSS dark mode utilities
• Styled Components ThemeProvider

5. Documentation

Standards for component documentation:

• Component purpose and usage
• Props API with types and defaults
• Accessibility notes
• Common examples

Key Features

Design Token System

• W3C design tokens format
• Primitive and semantic color systems
• Typography scales with accessibility in mind
• Consistent spacing based on mathematical scale
• Shadow system for elevation

Component Templates

• TypeScript-first component templates
• Polymorphic component patterns
• Compound component API design
• Variant and size systems
• Complete accessibility support

Bundled Resources

The skill includes ready-to-use templates and references:

• templates/design-tokens-template.json - Complete token structure
• templates/component-template.tsx - React component boilerplate
• references/component-examples.md - Full implementations with variants
• checklists/design-system-checklist.md - Audit checklist

Accessibility First

• WCAG 2.1 Level AA compliance by default
• Color contrast guidelines and testing recommendations
• Keyboard navigation patterns
• ARIA best practices
• Screen reader support patterns

Usage Examples

Example 1: Create a New Design System

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

The skill will guide you through: 1. Setting up design tokens (colors, typography, spacing) 2. Creating atomic components (Button, Input, Card) 3. Implementing dark mode with CSS variables 4. Ensuring accessibility compliance 5. Setting up documentation structure

Example 2: Add Design Tokens

Set up design tokens for colors and spacing using the 8px scale

Provides:

• Color token structure (primitive + semantic)
• Spacing scale based on 8px units
• JSON format compatible with Style Dictionary
• CSS variable implementation

Example 3: Component Architecture

Design component structure using atomic design for my dashboard

Delivers:

• Breakdown of atoms, molecules, organisms needed
• Component hierarchy and relationships
• Props API design patterns
• Composition guidelines

Example 4: Accessibility Audit

Ensure WCAG 2.1 compliance for my button components

Checks:

• Color contrast ratios
• Keyboard navigation support
• ARIA attributes
• Focus states
• Screen reader announcements

Example 5: Theming Implementation

Implement theming with dark mode using CSS variables

Provides:

• CSS custom property structure
• Light/dark theme definitions
• Theme switching logic
• Component integration patterns

Triggers

The skill activates on these common phrases:

Output Examples

Design Tokens Output

Complete JSON structure with:

• Color primitives (50-950 scale for each hue)
• Semantic color tokens mapped to primitives
• Typography scale (xs to 5xl)
• Spacing scale (0 to 24)
• Border radius and shadow tokens

Component Architecture Output

• Atomic design hierarchy diagram
• Component inventory by category
• Props interface definitions
• Implementation examples with TypeScript
• Accessibility notes for each component

Theming Output

• Theme structure interface
• Light and dark theme definitions
• CSS variable mapping
• Theme provider setup
• Component integration patterns

Accessibility Checklist Output

• Color contrast validation results
• Keyboard navigation requirements
• ARIA attribute recommendations
• Screen reader testing notes
• Focus management patterns

Design Philosophy

The skill is built on four core principles:

1. Consistency Over Creativity: Predictable patterns reduce cognitive load and help users learn once, apply everywhere

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

4. Developer-Friendly: Clear API contracts, comprehensive documentation, easy to integrate and customize

Integration

Works seamlessly with popular tools and frameworks:

• React/TypeScript: Primary target with complete TypeScript support
• Style Dictionary: Compatible token format for multi-platform output
• Tailwind CSS: Design token mapping to Tailwind config
• Styled Components: Theme provider integration
• Storybook: Documentation templates and story patterns
• Figma: Token naming aligned with Figma variables

Related Skills

• landing-page-guide-v2: Uses design system principles for landing pages
• nextjs15-init: Can initialize projects with design system structure
• mui: Material-UI specific patterns (alternative approach)

License

MIT

Version

1.0.0

Design System Component Examples

Detailed implementation examples for common design system components.

Button Component (Complete Implementation)

/**
 * Button Component - Primary interactive element
 */

import React from 'react';
import { cn } from '../utils/cn';

export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost';
export type ButtonSize = 'sm' | 'md' | 'lg';

export interface ButtonProps {
  variant?: ButtonVariant;
  size?: ButtonSize;
  disabled?: boolean;
  loading?: boolean;
  icon?: React.ReactNode;
  children: React.ReactNode;
  onClick?: () => void;
}

const buttonStyles = {
  base: 'inline-flex items-center justify-center font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',

  variants: {
    primary: 'bg-blue-600 text-white hover:bg-blue-700 focus-visible:ring-blue-500',
    secondary: 'bg-gray-600 text-white hover:bg-gray-700 focus-visible:ring-gray-500',
    outline: 'border border-gray-300 bg-transparent hover:bg-gray-100 focus-visible:ring-gray-500',
    ghost: 'hover:bg-gray-100 focus-visible:ring-gray-500',
  },

  sizes: {
    sm: 'h-8 px-3 text-sm rounded-md',
    md: 'h-10 px-4 text-base rounded-md',
    lg: 'h-12 px-6 text-lg rounded-lg',
  },
};

export function Button({
  variant = 'primary',
  size = 'md',
  disabled = false,
  loading = false,
  icon,
  children,
  onClick
}: ButtonProps) {
  return (
    <button
      className={cn(
        buttonStyles.base,
        buttonStyles.variants[variant],
        buttonStyles.sizes[size],
        { 'pointer-events-none opacity-50': loading }
      )}
      disabled={disabled || loading}
      onClick={onClick}
      aria-busy={loading}
    >
      {icon && <span className="mr-2">{icon}</span>}
      <span>{children}</span>
      {loading && <span className="ml-2 animate-spin">⏳</span>}
    </button>
  );
}

Form Field Component (Molecule)

/**
 * FormField - Composition of Label + Input + Helper/Error
 */

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

export function FormField({
  label,
  name,
  error,
  hint,
  required,
  children
}: FormFieldProps) {
  return (
    <div className="form-field space-y-2">
      <label
        htmlFor={name}
        className="block text-sm font-medium text-gray-700"
      >
        {label}
        {required && <span className="text-red-500 ml-1">*</span>}
      </label>

      {children}

      {hint && !error && (
        <p className="text-sm text-gray-500">{hint}</p>
      )}

      {error && (
        <p className="text-sm text-red-600" role="alert">
          {error}
        </p>
      )}
    </div>
  );
}

Card Component (Compound Component Pattern)

/**
 * Card - Composable container component
 */

interface CardProps {
  variant?: 'default' | 'outlined' | 'elevated';
  children: React.ReactNode;
  className?: string;
}

const cardStyles = {
  default: 'bg-white border border-gray-200',
  outlined: 'bg-white border-2 border-gray-300',
  elevated: 'bg-white shadow-lg',
};

export function Card({
  variant = 'default',
  children,
  className
}: CardProps) {
  return (
    <div
      className={cn(
        'rounded-lg p-6',
        cardStyles[variant],
        className
      )}
    >
      {children}
    </div>
  );
}

// Compound components
Card.Header = function CardHeader({ children }: { children: React.ReactNode }) {
  return <div className="mb-4 border-b border-gray-200 pb-4">{children}</div>;
};

Card.Title = function CardTitle({ children }: { children: React.ReactNode }) {
  return <h3 className="text-lg font-semibold text-gray-900">{children}</h3>;
};

Card.Body = function CardBody({ children }: { children: React.ReactNode }) {
  return <div className="space-y-4">{children}</div>;
};

Card.Footer = function CardFooter({ children }: { children: React.ReactNode }) {
  return <div className="mt-4 pt-4 border-t border-gray-200">{children}</div>;
};

// Usage Example:
/*
<Card variant="elevated">
  <Card.Header>
    <Card.Title>User Profile</Card.Title>
  </Card.Header>
  <Card.Body>
    <p>Profile content goes here</p>
  </Card.Body>
  <Card.Footer>
    <Button>Edit Profile</Button>
  </Card.Footer>
</Card>
*/

Input Component with Variants

/**
 * Input - Text input with validation states
 */

interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  variant?: 'default' | 'error' | 'success';
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
}

const inputStyles = {
  base: 'w-full rounded-md px-3 py-2 text-sm border transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2',

  variants: {
    default: 'border-gray-300 focus:border-blue-500 focus:ring-blue-500',
    error: 'border-red-500 focus:border-red-500 focus:ring-red-500',
    success: 'border-green-500 focus:border-green-500 focus:ring-green-500',
  },
};

export function Input({
  variant = 'default',
  leftIcon,
  rightIcon,
  className,
  ...props
}: InputProps) {
  return (
    <div className="relative">
      {leftIcon && (
        <div className="absolute left-3 top-1/2 -translate-y-1/2 text-gray-400">
          {leftIcon}
        </div>
      )}

      <input
        className={cn(
          inputStyles.base,
          inputStyles.variants[variant],
          { 'pl-10': leftIcon },
          { 'pr-10': rightIcon },
          className
        )}
        {...props}
      />

      {rightIcon && (
        <div className="absolute right-3 top-1/2 -translate-y-1/2 text-gray-400">
          {rightIcon}
        </div>
      )}
    </div>
  );
}

Modal Component (Organism)

/**
 * Modal - Dialog with focus trap and overlay
 */

import { useEffect, useRef } from 'react';

interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
  size?: 'sm' | 'md' | 'lg' | 'full';
}

const modalSizes = {
  sm: 'max-w-md',
  md: 'max-w-lg',
  lg: 'max-w-2xl',
  full: 'max-w-full',
};

export function Modal({
  isOpen,
  onClose,
  title,
  children,
  size = 'md'
}: ModalProps) {
  const modalRef = useRef<HTMLDivElement>(null);

  // Focus trap
  useEffect(() => {
    if (isOpen) {
      modalRef.current?.focus();
    }
  }, [isOpen]);

  // ESC key handler
  useEffect(() => {
    const handleEsc = (e: KeyboardEvent) => {
      if (e.key === 'Escape') onClose();
    };

    if (isOpen) {
      document.addEventListener('keydown', handleEsc);
      document.body.style.overflow = 'hidden'; // Prevent background scroll
    }

    return () => {
      document.removeEventListener('keydown', handleEsc);
      document.body.style.overflow = '';
    };
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  return (
    <div
      className="fixed inset-0 z-50 flex items-center justify-center"
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
    >
      {/* Overlay */}
      <div
        className="absolute inset-0 bg-black bg-opacity-50"
        onClick={onClose}
      />

      {/* Modal */}
      <div
        ref={modalRef}
        className={cn(
          'relative bg-white rounded-lg shadow-xl w-full mx-4',
          modalSizes[size]
        )}
        tabIndex={-1}
      >
        {/* Header */}
        <div className="flex items-center justify-between px-6 py-4 border-b">
          <h2 id="modal-title" className="text-xl font-semibold">
            {title}
          </h2>
          <button
            onClick={onClose}
            className="text-gray-400 hover:text-gray-600"
            aria-label="Close"
          >
            ✕
          </button>
        </div>

        {/* Body */}
        <div className="px-6 py-4">
          {children}
        </div>
      </div>
    </div>
  );
}

Polymorphic Component Example

/**
 * Polymorphic Button - Can render as button, link, etc.
 */

type AsProp<C extends React.ElementType> = {
  as?: C;
};

type PropsToOmit<C extends React.ElementType, P> = keyof (AsProp<C> & P);

type PolymorphicComponentProp<
  C extends React.ElementType,
  Props = {}
> = React.PropsWithChildren<Props & AsProp<C>> &
  Omit<React.ComponentPropsWithoutRef<C>, PropsToOmit<C, Props>>;

type PolymorphicRef<C extends React.ElementType> =
  React.ComponentPropsWithRef<C>['ref'];

type PolymorphicComponentPropWithRef<
  C extends React.ElementType,
  Props = {}
> = PolymorphicComponentProp<C, Props> & { ref?: PolymorphicRef<C> };

interface ButtonBaseProps {
  variant?: 'primary' | 'secondary';
}

export type ButtonProps<C extends React.ElementType = 'button'> =
  PolymorphicComponentPropWithRef<C, ButtonBaseProps>;

export const PolymorphicButton = <C extends React.ElementType = 'button'>({
  as,
  variant = 'primary',
  children,
  ...props
}: ButtonProps<C>) => {
  const Component = as || 'button';

  return (
    <Component
      className={cn('px-4 py-2 rounded', {
        'bg-blue-600 text-white': variant === 'primary',
        'bg-gray-600 text-white': variant === 'secondary',
      })}
      {...props}
    >
      {children}
    </Component>
  );
};

// Usage:
// <PolymorphicButton>Button</PolymorphicButton>
// <PolymorphicButton as="a" href="/login">Link</PolymorphicButton>

Accessibility Example - Skip Link

/**
 * Skip Link - Keyboard accessibility helper
 */

export function SkipLink() {
  return (
    <a
      href="#main-content"
      className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-blue-600 focus:text-white focus:rounded"
    >
      Skip to main content
    </a>
  );
}

// CSS for sr-only (screen reader only):
/*
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

.focus\:not-sr-only:focus {
  position: static;
  width: auto;
  height: auto;
  padding: revert;
  margin: revert;
  overflow: visible;
  clip: auto;
  white-space: normal;
}
*/

Theme Switching Example

/**
 * Theme Toggle - Dark mode switcher
 */

import { useEffect, useState } from 'react';

export function ThemeToggle() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  useEffect(() => {
    // Check system preference on mount
    const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    const savedTheme = localStorage.getItem('theme') as 'light' | 'dark' || (isDark ? 'dark' : 'light');
    setTheme(savedTheme);
    document.documentElement.setAttribute('data-theme', savedTheme);
  }, []);

  const toggleTheme = () => {
    const newTheme = theme === 'light' ? 'dark' : 'light';
    setTheme(newTheme);
    document.documentElement.setAttribute('data-theme', newTheme);
    localStorage.setItem('theme', newTheme);
  };

  return (
    <button
      onClick={toggleTheme}
      aria-label={`Switch to ${theme === 'light' ? 'dark' : 'light'} mode`}
      className="p-2 rounded-md hover:bg-gray-100 dark:hover:bg-gray-800"
    >
      {theme === 'light' ? '🌙' : '☀️'}
    </button>
  );
}

Responsive Navigation Example

/**
 * Navigation Bar - Responsive with mobile menu
 */

import { useState } from 'react';

export function Navigation() {
  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);

  return (
    <nav className="bg-white border-b border-gray-200" aria-label="Main navigation">
      <div className="container mx-auto px-4">
        <div className="flex items-center justify-between h-16">
          {/* Logo */}
          <div className="flex-shrink-0">
            <a href="/" className="text-xl font-bold">
              Logo
            </a>
          </div>

          {/* Desktop Navigation */}
          <div className="hidden md:flex space-x-8">
            <a href="/features" className="text-gray-700 hover:text-gray-900">
              Features
            </a>
            <a href="/pricing" className="text-gray-700 hover:text-gray-900">
              Pricing
            </a>
            <a href="/about" className="text-gray-700 hover:text-gray-900">
              About
            </a>
          </div>

          {/* Mobile Menu Button */}
          <button
            className="md:hidden p-2"
            onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
            aria-label="Toggle mobile menu"
            aria-expanded={mobileMenuOpen}
          >
            <span className="block w-6 h-0.5 bg-gray-900 mb-1"></span>
            <span className="block w-6 h-0.5 bg-gray-900 mb-1"></span>
            <span className="block w-6 h-0.5 bg-gray-900"></span>
          </button>
        </div>

        {/* Mobile Menu */}
        {mobileMenuOpen && (
          <div className="md:hidden py-4">
            <a
              href="/features"
              className="block py-2 text-gray-700 hover:bg-gray-100"
            >
              Features
            </a>
            <a
              href="/pricing"
              className="block py-2 text-gray-700 hover:bg-gray-100"
            >
              Pricing
            </a>
            <a
              href="/about"
              className="block py-2 text-gray-700 hover:bg-gray-100"
            >
              About
            </a>
          </div>
        )}
      </div>
    </nav>
  );
}