frank-luongt/skills/codex/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.

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" onClick={handleClick}>Submit</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

| 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 (MIT License)
• W3C Design Tokens
• WCAG 2.1 Guidelines
• Atomic Design

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