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

상세 JSON 예시: references/design-tokens.md — 각 카테고리별 전체 토큰 값 포함

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" 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
 
  => 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