Skip to main content
skill CX Codex

Design System Architect — Claude Code skill: guide and install

Design System Architect guides the creation of scalable design systems, covering multi-tiered tokens, dark mode, Style Dictionary transforms, and atomic component structure.

MIT 227 installs ★ 39 updated 2025-12-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daffy0208/ai-dev-standards --skill design-system-architect -a claude-code
Open on GitHub

What Design System Architect does

The skill organizes UI libraries following atomic design principles, moving from basic atoms and molecules up to templates and full pages. It structures design decisions across three token layers: raw primitives, semantic tokens mapped to theme contexts, and component-specific variables.

Token compilation relies on style-dictionary to generate CSS custom properties and JavaScript exports from JSON files. You must install style-dictionary locally via npm for token builds to run. The skill also enforces consistent component folders with TypeScript definitions, scoped styling, and Storybook stories.

What it helps with

  • organize design tokens into primitive, semantic, and component tiers
  • configure Style Dictionary to build CSS variables from JSON
  • set up light and dark theme switching using semantic tokens
  • structure React components following atomic design hierarchy

Example prompts for the agent

  • Structure our color and spacing tokens into primitive and semantic JSON files
  • Set up a Style Dictionary config to export CSS variables for light and dark themes
  • Create an atomic Button component folder with TypeScript types and Storybook stories

How to install Design System Architect

1Skills CLI (Vercel)

npx skills add daffy0208/ai-dev-standards --skill design-system-architect -a claude-code

2Manually: put the files in place

~/.claude/skills/design-system-architect/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/design-system-architect/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about Design System Architect

How do I install Design System Architect in Claude Code?

Run npx skills add daffy0208/ai-dev-standards --skill design-system-architect -a claude-code. The skill file will be placed in ~/.claude/skills/design-system-architect/SKILL.md.

What does Design System Architect do?

It provides guidelines for building frontend design systems. The skill covers token architecture, token compilation, theme tokens, and component breakdown.

What dependencies are needed for token compilation?

Transforming JSON tokens into variables requires installing style-dictionary with npm install --save-dev style-dictionary.

Source text

SKILL.md · MIT
---
name: Design System Architect
description: Build scalable, maintainable design systems that unify product experiences. Use when creating component libraries, design tokens, or establishing design standards. Covers atomic design, Storybook, theming, and design system governance.
version: 1.0.0
---

# Design System Architect

**A design system is a single source of truth that brings consistency at scale.**

## Core Principle

Design systems are not just component libraries—they're the shared language between design and engineering. A good design system:

- Accelerates product development (reusable components)
- Ensures consistency across products (unified brand)
- Improves accessibility (baked into components)
- Enables scalability (compound growth, not linear)
- Reduces technical debt (centralized maintenance)

**Goal:** Build once, use everywhere. Maintain once, improve everywhere.

---

## Phase 1: Design Tokens

### What Are Design Tokens?

**Design tokens are the atomic values of your design system.** They're the smallest decisions (colors, spacing, typography) stored as data and consumed by all platforms.

**Why Tokens Matter:**

- Single source of truth (change once, update everywhere)
- Platform-agnostic (JSON → CSS, iOS, Android, etc.)
- Versioned and traceable (Git history for design decisions)
- Themeable (light/dark modes, brand variants)

### Token Structure

```typescript
// tokens/colors.json
{
  "color": {
    "brand": {
      "primary": {
        "50": { "value": "#eff6ff" },
        "100": { "value": "#dbeafe" },
        "200": { "value": "#bfdbfe" },
        "300": { "value": "#93c5fd" },
        "400": { "value": "#60a5fa" },
        "500": { "value": "#3b82f6" },
        "600": { "value": "#2563eb" },
        "700": { "value": "#1d4ed8" },
        "800": { "value": "#1e40af" },
        "900": { "value": "#1e3a8a" },
        "950": { "value": "#172554" }
      }
    },
    "semantic": {
      "background": {
        "primary": { "value": "{color.neutral.50}" },
        "secondary": { "value": "{color.neutral.100}" }
      },
      "text": {
        "primary": { "value": "{color.neutral.900}" },
        "secondary": { "value": "{color.neutral.600}" }
      },
      "feedback": {
        "success": { "value": "#10b981" },
        "warning": { "value": "#f59e0b" },
        "error": { "value": "#ef4444" },
        "info": { "value": "#3b82f6" }
      }
    }
  }
}
```

### Token Categories

**Primitive Tokens** (Raw values):

```json
{
  "color-blue-500": "#3b82f6",
  "space-4": "16px",
  "font-size-base": "16px"
}
```

**Semantic Tokens** (Named by purpose):

```json
{
  "color-primary": "{color-blue-500}",
  "spacing-default": "{space-4}",
  "text-body": "{font-size-base}"
}
```

**Component Tokens** (Component-specific):

```json
{
  "button-padding-x": "{spacing-default}",
  "button-background": "{color-primary}",
  "button-text": "{color-white}"
}
```

### Token Architecture

```
tokens/
├── primitives/
│   ├── colors.json       # Raw color values
│   ├── spacing.json      # 4px, 8px, 16px...
│   ├── typography.json   # Font sizes, weights
│   ├── shadows.json      # Elevation system
│   └── radii.json        # Border radius values
├── semantic/
│   ├── colors.json       # background-primary, text-secondary
│   ├── spacing.json      # spacing-tight, spacing-comfortable
│   └── typography.json   # heading-xl, body-md
└── components/
    ├── button.json       # Button-specific tokens
    ├── input.json        # Input-specific tokens
    └── card.json         # Card-specific tokens
```

### Token Transformation with Style Dictionary

**Install Style Dictionary:**

```bash
npm install --save-dev style-dictionary
```

**config.json:**

```json
{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "dist/css/",
      "files": [
        {
          "destination": "variables.css",
          "format": "css/variables"
        }
      ]
    },
    "js": {
      "transformGroup": "js",
      "buildPath": "dist/js/",
      "files": [
        {
          "destination": "tokens.js",
          "format": "javascript/es6"
        }
      ]
    }
  }
}
```

**Build tokens:**

```bash
npx style-dictionary build
```

**Output (variables.css):**

```css
:root {
  --color-brand-primary-500: #3b82f6;
  --color-semantic-background-primary: #fafafa;
  --space-4: 16px;
  --font-size-base: 16px;
  --button-padding-x: 16px;
}
```

### Dark Mode with Tokens

```json
// tokens/semantic/colors-light.json
{
  "background": {
    "primary": { "value": "#ffffff" },
    "secondary": { "value": "#f9fafb" }
  },
  "text": {
    "primary": { "value": "#111827" },
    "secondary": { "value": "#6b7280" }
  }
}

// tokens/semantic/colors-dark.json
{
  "background": {
    "primary": { "value": "#111827" },
    "secondary": { "value": "#1f2937" }
  },
  "text": {
    "primary": { "value": "#f9fafb" },
    "secondary": { "value": "#d1d5db" }
  }
}
```

**CSS Output:**

```css
:root {
  --background-primary: #ffffff;
  --text-primary: #111827;
}

[data-theme='dark'] {
  --background-primary: #111827;
  --text-primary: #f9fafb;
}
```

---

## Phase 2: Component Architecture

### Atomic Design Methodology

**Atoms** → **Molecules** → **Organisms** → **Templates** → **Pages**

```
atoms/
├── Button/
├── Input/
├── Label/
├── Icon/
└── Text/

molecules/
├── FormField/         # Label + Input + Error
├── SearchBar/         # Input + Icon + Button
└── Card/              # Container + Text + Button

organisms/
├── Header/            # Logo + Nav + SearchBar
├── LoginForm/         # FormFields + Button
└── ProductCard/       # Card + Image + Price + CTA

templates/
├── DashboardLayout/   # Header + Sidebar + Content
└── MarketingLayout/   # Header + Hero + Features + Footer

pages/
├── HomePage/          # MarketingLayout + specific content
└── DashboardPage/     # DashboardLayout + widgets
```

### Component Structure

```
components/
└── Button/
    ├── Button.tsx           # Component implementation
    ├── Button.module.css    # Scoped styles
    ├── Button.stories.tsx   # Storybook stories
    ├── Button.test.tsx      # Unit tests
    ├── Button.types.ts      # TypeScript types
    ├── index.ts             # Public exports
    └── README.md            # Component docs
```

### Button Component (Atomic Example)

**Button.types.ts:**

```typescript
export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'danger'
export type ButtonSize = 'sm' | 'md' | 'lg'

export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: ButtonVariant
  size?: ButtonSize
  isLoading?: boolean
  leftIcon?: React.ReactNode
  rightIcon?: React.ReactNode
  fullWidth?: boolean
  children: React.ReactNode
}
```

**Button.tsx:**

```typescript
import React from 'react'
import styles from './Button.module.css'
import { ButtonProps } from './Button.types'

export function Button({
  variant = 'primary',
  size = 'md',
  isLoading = false,
  leftIcon,
  rightIcon,
  fullWidth = false,
  disabled,
  children,
  className,
  ...props
}: ButtonProps) {
  const classes = [
    styles.button,
    styles[variant],
    styles[size],
    fullWidth && styles.fullWidth,
    isLoading && styles.loading,
    className
  ].filter(Boolean).join(' ')

  return (
    <button
      className={classes}
      disabled={disabled || isLoading}
      aria-busy={isLoading}
      {...props}
    >
      {leftIcon && <span className={styles.iconLeft}>{leftIcon}</span>}
      <span className={styles.content}>{children}</span>
      {rightIcon && <span className={styles.iconRight}>{rightIcon}</span>}
      {isLoading && (
        <span className={styles.spinner} aria-label="Loading">
          <svg className={styles.spinnerIcon} viewBox="0 0 24 24">
            <circle cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" opacity="0.25" />
            <path d="M12 2a10 10 0 0 1 10 10" stroke="currentColor" strokeWidth="4" fill="none" strokeLinecap="round" />
          </svg>
        </span>
      )}
    </button>
  )
}
```

**Button.module.css:**

```css
.button {
  /* Base */
  position: relative;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: var(--space-2);
  font-family: var(--font-base);
  font-weight: 500;
  border: none;
  border-radius: var(--radius-md);
  cursor: pointer;
  transition: all 150ms ease;
  user-select: none;

  /* Accessibility */
  outline-offset: 2px;
}

.button:focus-visible {
  outline: 2px solid var(--color-focus);
}

.button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
  pointer-events: none;
}

/* Variants */
.primary {
  background: var(--button-primary-background);
  color: var(--button-primary-text);
}

.primary:hover:not(:disabled) {
  background: var(--button-primary-background-hover);
}

.secondary {
  background: transparent;
  color: var(--button-secondary-text);
  border: 1px solid var(--button-secondary-border);
}

.secondary:hover:not(:disabled) {
  background: var(--button-secondary-background-hover);
}

.tertiary {
  background: transparent;
  color: var(--button-tertiary-text);
}

.tertiary:hover:not(:disabled) {
  background: var(--button-tertiary-background-hover);
}

.danger {
  background: var(--color-error);
  color: var(--color-white);
}

.danger:hover:not(:disabled) {
  background: var(--color-error-dark);
}

/* Sizes */
.sm {
  padding: var(--space-1) var(--space-3);
  font-size: var(--text-sm);
  height: 32px;
}

.md {
  padding: var(--space-2) var(--space-4);
  font-size: var(--text-base);
  height: 40px;
}

.lg {
  padding: var(--space-3) var(--space-6);
  font-size: var(--text-lg);
  height: 48px;
}

/* Modifiers */
.fullWidth {
  width: 100%;
}

.loading {
  color: transparent;
}

.spinner {
  position: absolute;
  display: flex;
  align-items: center;
  justify-content: center;
  inset: 0;
}

.spinnerIcon {
  width: 20px;
  height: 20px;
  animation: spin 1s linear infinite;
}

@keyframes spin {
  to {
    transform: rotate(360deg);
  }
}

.iconLeft,
.iconRight {
  display: flex;
  align-items: center;
}

.content {
  display: flex;
  align-items: center;
}
```

### FormField Component (Molecule Example)

**FormField.tsx:**

```typescript
import React from 'react'
import styles from './FormField.module.css'

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

export function FormField({
  label,
  error,
  hint,
  required = false,
  children
}: FormFieldProps) {
  const inputId = React.useId()
  const errorId = `${inputId}-error`
  const hintId = `${inputId}-hint`

  // Clone child to pass accessibility props
  const childWithProps = React.cloneElement(
    children as React.ReactElement,
    {
      id: inputId,
      'aria-invalid': !!error,
      'aria-describedby': [
        hint ? hintId : null,
        error ? errorId : null
      ].filter(Boolean).join(' ') || undefined
    }
  )

  return (
    <div className={styles.field}>
      <label htmlFor={inputId} className={styles.label}>
        {label}
        {required && (
          <span className={styles.required} aria-label="required">
            *
          </span>
        )}
      </label>

      {hint && (
        <div id={hintId} className={styles.hint}>
          {hint}
        </div>
      )}

      {childWithProps}

      {error && (
        <div id={errorId} className={styles.error} role="alert">
          {error}
        </div>
      )}
    </div>
  )
}
```

### Component API Design Principles

**1. Sensible Defaults:**

```typescript
// ✅ Good: Works with minimal props
<Button>Click me</Button>

// ✅ Good: Customizable when needed
<Button variant="secondary" size="lg" fullWidth>
  Click me
</Button>
```

**2. Composition Over Configuration:**

```typescript
// ❌ Bad: Too many props
<Modal
  title="Delete Account"
  body="Are you sure?"
  confirmText="Delete"
  cancelText="Cancel"
  onConfirm={handleDelete}
  onCancel={handleCancel}
/>

// ✅ Good: Composable
<Modal>
  <Modal.Header>Delete Account</Modal.Header>
  <Modal.Body>Are you sure?</Modal.Body>
  <Modal.Footer>
    <Button variant="danger" onClick={handleDelete}>Delete</Button>
    <Button variant="secondary" onClick={handleCancel}>Cancel</Button>
  </Modal.Footer>
</Modal>
```

**3. Controlled & Uncontrolled Modes:**

```typescript
// Uncontrolled (internal state)
<Input defaultValue="hello" />

// Controlled (external state)
<Input value={value} onChange={setValue} />
```

**4. Polymorphic Components:**

```typescript
interface ButtonProps<T extends React.ElementType = 'button'> {
  as?: T
  // ... other props
}

// Render as button (default)
<Button onClick={handleClick}>Click</Button>

// Render as link
<Button as="a" href="/dashboard">Dashboard</Button>

// Render as Next.js Link
<Button as={Link} href="/about">About</Button>
```

---

## Phase 3: Storybook Documentation

### Storybook Setup

**Install Storybook:**

```bash
npx storybook@latest init
```

**Button.stories.tsx:**

```typescript
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './Button'

const meta: Meta<typeof Button> = {
  title: 'Atoms/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'tertiary', 'danger'],
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg'],
    },
    isLoading: { control: 'boolean' },
    fullWidth: { control: 'boolean' },
    disabled: { control: 'boolean' },
  },
}

export default meta
type Story = StoryObj<typeof Button>

// Primary story
export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Button',
  },
}

// All variants
export const AllVariants: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '1rem' }}>
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="tertiary">Tertiary</Button>
      <Button variant="danger">Danger</Button>
    </div>
  ),
}

// All sizes
export const AllSizes: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </div>
  ),
}

// With icons
export const WithIcons: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '1rem' }}>
      <Button leftIcon={<Icon name="plus" />}>Add Item</Button>
      <Button rightIcon={<Icon name="arrow-right" />}>Next</Button>
    </div>
  ),
}

// Loading state
export const Loading: Story = {
  args: {
    isLoading: true,
    children: 'Loading...',
  },
}

// Disabled state
export const Disabled: Story = {
  args: {
    disabled: true,
    children: 'Disabled',
  },
}

// Full width
export const FullWidth: Story = {
  args: {
    fullWidth: true,
    children: 'Full Width Button',
  },
}
```

### MDX Documentation

**Button.mdx:**

````mdx
import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
import * as ButtonStories from './Button.stories'

<Meta of={ButtonStories} />

# Button

Buttons allow users to trigger actions and make choices with a single tap.

## When to Use

- Primary actions (submit forms, complete workflows)
- Secondary actions (cancel, go back)
- Tertiary actions (view details, learn more)
- Dangerous actions (delete, remove)

## Variants

<Canvas of={ButtonStories.AllVariants} />

### Primary

Use for the main action on a page. Limit to one per screen.

### Secondary

Use for less important actions. Can have multiple per screen.

### Tertiary

Use for the least important actions, like "Learn more" links.

### Danger

Use for destructive actions like deleting data.

## Sizes

<Canvas of={ButtonStories.AllSizes} />

- **Small**: Dense UIs, table actions
- **Medium**: Default for most use cases
- **Large**: Hero CTAs, mobile-first designs

## With Icons

<Canvas of={ButtonStories.WithIcons} />

Icons can clarify the button's purpose or indicate direction.

## States

### Loading

<Canvas of={ButtonStories.Loading} />

Show a loading spinner when an async action is in progress.

### Disabled

<Canvas of={ButtonStories.Disabled} />

Disable buttons when an action is not currently available.

## Accessibility

- ✅ Keyboard accessible (Tab, Enter/Space)
- ✅ Focus visible indicator
- ✅ ARIA attributes (aria-busy, aria-disabled)
- ✅ Loading state announced to screen readers

## Props

<Controls />

## Usage

```tsx
import { Button } from '@/components/Button'

function MyComponent() {
  return (
    <Button variant="primary" onClick={handleClick}>
      Click me
    </Button>
  )
}
```
````

````

### Storybook Addons

```bash
# Accessibility testing
npm install --save-dev @storybook/addon-a11y

# Component interactions
npm install --save-dev @storybook/addon-interactions

# Design tokens addon
npm install --save-dev storybook-addon-designs
````

**.storybook/main.ts:**

```typescript
import type { StorybookConfig } from '@storybook/react-vite'

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y',
    'storybook-addon-designs'
  ],
  framework: '@storybook/react-vite'
}

export default config
```

---

## Phase 4: Theming & Customization

### CSS Variables Approach

**tokens.css:**

```css
:root {
  /* Primitives */
  --color-blue-500: #3b82f6;
  --color-red-500: #ef4444;
  --space-4: 16px;

  /* Semantic (can be overridden) */
  --color-primary: var(--color-blue-500);
  --color-danger: var(--color-red-500);
  --spacing-default: var(--space-4);

  /* Component tokens */
  --button-primary-background: var(--color-primary);
  --button-primary-text: white;
  --button-padding: var(--spacing-default);
}

/* Theme override */
[data-theme='brand-red'] {
  --color-primary: #dc2626;
}

[data-theme='dark'] {
  --color-primary: #60a5fa;
  --button-primary-background: var(--color-primary);
}
```

### Theme Provider (React)

**ThemeProvider.tsx:**

```typescript
import React, { createContext, useContext, useEffect, useState } from 'react'

type Theme = 'light' | 'dark' | 'auto'

interface ThemeContextValue {
  theme: Theme
  setTheme: (theme: Theme) => void
  resolvedTheme: 'light' | 'dark'
}

const ThemeContext = createContext<ThemeContextValue | undefined>(undefined)

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>('auto')
  const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>('light')

  useEffect(() => {
    // Load saved theme
    const saved = localStorage.getItem('theme') as Theme
    if (saved) setTheme(saved)
  }, [])

  useEffect(() => {
    // Save theme
    localStorage.setItem('theme', theme)

    // Resolve theme
    if (theme === 'auto') {
      const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches
      setResolvedTheme(isDark ? 'dark' : 'light')
    } else {
      setResolvedTheme(theme)
    }
  }, [theme])

  useEffect(() => {
    // Apply theme to DOM
    document.documentElement.setAttribute('data-theme', resolvedTheme)
  }, [resolvedTheme])

  return (
    <ThemeContext.Provider value={{ theme, setTheme, resolvedTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

export function useTheme() {
  const context = useContext(ThemeContext)
  if (!context) {
    throw new Error('useTheme must be used within ThemeProvider')
  }
  return context
}
```

### Multi-Brand Theming

```typescript
// themes/acme.ts
export const acmeTheme = {
  colors: {
    primary: '#3b82f6',
    secondary: '#8b5cf6'
  },
  typography: {
    fontFamily: 'Inter, sans-serif'
  },
  spacing: {
    unit: 8
  }
}

// themes/contoso.ts
export const contosoTheme = {
  colors: {
    primary: '#dc2626',
    secondary: '#f59e0b'
  },
  typography: {
    fontFamily: 'Roboto, sans-serif'
  },
  spacing: {
    unit: 4
  }
}
```

**Theme Application:**

```typescript
function applyTheme(theme: Theme) {
  Object.entries(theme.colors).forEach(([key, value]) => {
    document.documentElement.style.setProperty(`--color-${key}`, value)
  })

  document.documentElement.style.setProperty('--font-base', theme.typography.fontFamily)

  document.documentElement.style.setProperty('--space-unit', `${theme.spacing.unit}px`)
}
```

---

## Phase 5: Versioning & Governance

### Semantic Versioning

**MAJOR.MINOR.PATCH**

- **MAJOR:** Breaking changes (v1.0.0 → v2.0.0)
  - Removed props
  - Changed prop types
  - Changed default behavior

- **MINOR:** New features, backwards-compatible (v1.0.0 → v1.1.0)
  - New props
  - New components
  - New variants

- **PATCH:** Bug fixes (v1.0.0 → v1.0.1)
  - CSS fixes
  - Accessibility improvements
  - TypeScript fixes

### Changelog

**CHANGELOG.md:**

````markdown
# Changelog

## [2.0.0] - 2024-01-15

### Breaking Changes

- **Button:** Renamed `type` prop to `variant`
- **Input:** Removed `error` prop (use FormField wrapper instead)

### Migration Guide

```typescript
// Before
<Button type="primary">Click</Button>

// After
<Button variant="primary">Click</Button>
```
````

## [1.5.0] - 2024-01-10

### Added

- **Button:** New `isLoading` prop
- **Input:** New `leftIcon` and `rightIcon` props
- **Card:** New component

### Fixed

- **Button:** Focus outline now visible on all browsers
- **Input:** Placeholder color now meets WCAG contrast requirements

## [1.4.1] - 2024-01-05

### Fixed

- **Button:** Loading spinner now centered correctly
- **Modal:** Fixed backdrop z-index issue

````

### Component Lifecycle

**P0 (Must Have):**
- Button, Input, Label, Text, Icon
- FormField, Card, Modal

**P1 (Should Have):**
- Select, Checkbox, Radio, Switch, Textarea
- Tabs, Accordion, Dropdown, Tooltip

**P2 (Nice to Have):**
- DatePicker, Combobox, Slider, Toggle
- Toast, Drawer, Popover

**P3 (Future):**
- DataTable, Calendar, FileUpload
- Charts, Timeline, Stepper

### Deprecation Strategy

**1. Announce deprecation:**
```typescript
/**
 * @deprecated Use `variant` prop instead. Will be removed in v3.0.0.
 */
export interface ButtonProps {
  type?: 'primary' | 'secondary' // Deprecated
  variant?: 'primary' | 'secondary' // New
}
````

**2. Support both (with warning):**

```typescript
export function Button({ type, variant, ...props }: ButtonProps) {
  if (type) {
    console.warn('Button: `type` prop is deprecated. Use `variant` instead.')
  }

  const finalVariant = variant || type || 'primary'
  // ...
}
```

**3. Remove in next major version:**

```typescript
// v3.0.0 - type prop removed entirely
export interface ButtonProps {
  variant?: 'primary' | 'secondary'
}
```

### Design System Governance

**Design System Team:**

- **Owner:** Overall vision and roadmap
- **Designers:** Visual design, UX patterns
- **Engineers:** Implementation, tooling
- **Contributors:** Product teams building components

**Contribution Flow:**

```
1. Proposal → GitHub issue
2. Design Review → Figma mockup
3. API Design → TypeScript interface
4. Implementation → PR with tests + stories
5. Documentation → README + Storybook
6. Release → Semantic versioning + changelog
```

**Proposal Template:**

````markdown
## Component Name

**Problem:** What user need does this solve?

**Usage:** When should this be used?

**API Proposal:**

```typescript
interface ComponentProps {
  // ...
}
```
````

**Design Mockup:** [Link to Figma]

**Accessibility:** How will this be accessible?

**Alternatives Considered:** What else did we explore?

````

---

## Testing Design Systems

### Visual Regression Testing

**Chromatic (Storybook integration):**
```bash
npm install --save-dev chromatic

# Run visual tests
npx chromatic --project-token=YOUR_TOKEN
````

**package.json:**

```json
{
  "scripts": {
    "chromatic": "chromatic --exit-zero-on-changes"
  }
}
```

### Component Testing

```typescript
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { Button } from './Button'

describe('Button', () => {
  it('renders children', () => {
    render(<Button>Click me</Button>)
    expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument()
  })

  it('calls onClick when clicked', async () => {
    const user = userEvent.setup()
    const handleClick = jest.fn()

    render(<Button onClick={handleClick}>Click me</Button>)
    await user.click(screen.getByRole('button'))

    expect(handleClick).toHaveBeenCalledTimes(1)
  })

  it('disables button when loading', () => {
    render(<Button isLoading>Click me</Button>)
    expect(screen.getByRole('button')).toBeDisabled()
    expect(screen.getByLabelText('Loading')).toBeInTheDocument()
  })

  it('applies variant classes', () => {
    render(<Button variant="danger">Delete</Button>)
    expect(screen.getByRole('button')).toHaveClass('danger')
  })
})
```

### Accessibility Testing

```typescript
import { axe, toHaveNoViolations } from 'jest-axe'
expect.extend(toHaveNoViolations)

it('has no accessibility violations', async () => {
  const { container } = render(<Button>Click me</Button>)
  const results = await axe(container)
  expect(results).toHaveNoViolations()
})
```

---

## Publishing & Distribution

### NPM Package Setup

**package.json:**

```json
{
  "name": "@company/design-system",
  "version": "1.0.0",
  "description": "Company design system",
  "main": "dist/index.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "files": ["dist", "README.md"],
  "scripts": {
    "build": "rollup -c",
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "publishConfig": {
    "access": "public"
  }
}
```

**rollup.config.js:**

```javascript
import typescript from '@rollup/plugin-typescript'
import postcss from 'rollup-plugin-postcss'

export default {
  input: 'src/index.ts',
  output: [
    {
      file: 'dist/index.js',
      format: 'cjs',
      sourcemap: true
    },
    {
      file: 'dist/index.esm.js',
      format: 'esm',
      sourcemap: true
    }
  ],
  plugins: [
    typescript({ tsconfig: './tsconfig.json' }),
    postcss({
      modules: true,
      extract: 'styles.css'
    })
  ],
  external: ['react', 'react-dom']
}
```

**Publish:**

```bash
npm login
npm version patch  # or minor, major
npm publish
```

### Consumption

```bash
npm install @company/design-system
```

```typescript
import { Button, Input, Card } from '@company/design-system'
import '@company/design-system/dist/styles.css'

function App() {
  return (
    <Card>
      <Input placeholder="Email" />
      <Button variant="primary">Submit</Button>
    </Card>
  )
}
```

---

## Design System Checklist

### Foundation

- [ ] Design tokens (colors, spacing, typography, shadows, radii)
- [ ] Token transformation pipeline (Style Dictionary)
- [ ] Dark mode support
- [ ] Documentation site (Storybook)

### Components

- [ ] Atomic design structure (atoms → organisms)
- [ ] Component API guidelines (sensible defaults, composition)
- [ ] TypeScript types for all components
- [ ] CSS modules or styled-components
- [ ] Accessibility baked in (WCAG 2.1 AA)

### Documentation

- [ ] Storybook stories for all components
- [ ] MDX docs with usage examples
- [ ] Props table (auto-generated)
- [ ] Design guidelines (when to use, when not to use)
- [ ] Code examples

### Testing

- [ ] Unit tests (70%+ coverage)
- [ ] Accessibility tests (jest-axe)
- [ ] Visual regression tests (Chromatic)
- [ ] Manual testing checklist

### Governance

- [ ] Semantic versioning
- [ ] Changelog maintained
- [ ] Contribution guidelines
- [ ] Component lifecycle (P0 → P3)
- [ ] Deprecation strategy

### Distribution

- [ ] NPM package published
- [ ] Storybook deployed
- [ ] Installation guide
- [ ] Migration guides for breaking changes

---

## Tools & Resources

**Token Management:**

- Style Dictionary (token transformation)
- Figma Tokens (sync Figma → code)

**Component Development:**

- Storybook (documentation)
- Chromatic (visual testing)
- React + TypeScript

**Testing:**

- Jest + React Testing Library
- jest-axe (accessibility)
- Playwright (E2E)

**Build & Distribution:**

- Rollup or tsup (bundling)
- NPM (distribution)
- Changesets (versioning)

**Inspiration:**

- [Radix UI](https://www.radix-ui.com/) (accessible primitives)
- [Chakra UI](https://chakra-ui.com/) (themeable components)
- [Material UI](https://mui.com/) (comprehensive system)
- [Ant Design](https://ant.design/) (enterprise-grade)

---

## Related Skills

- `visual-designer` - Design foundations (color, typography, spacing)
- `accessibility-engineer` - WCAG compliance
- `frontend-builder` - React component patterns
- `testing-strategist` - Component testing strategies

---

**A design system is never done—it evolves with your product.** 🎨

© daffy0208 · MIT · daffy0208/ai-dev-standards

Similar skills

All skills for Frontend and UI →

From the same set63

The whole set →
copywriter copywriter generates focused copy for UI elements and marketing pages. It guides the assistant through button labels, error alerts, empty states, and hero blocks. CX Codex +1 257installs api-integration-builder api-integration-builder walks your agent through a third-party API integration: OAuth, retries, rate limits, webhooks. Useful once the other side starts answering 429 or 401. CX Codex +1 244installs product-analytics Lays out product analytics: picking a North Star metric, mapping a signup funnel, comparing cohorts and marking user actions as events. CX Codex +1 244installs Performance Optimizer Performance Optimizer guides coding agents through profiling, database indexing, and caching to meet Web Vitals and backend latency targets. CX Codex +1 228installs Frontend Builder Frontend Builder is a Claude Code skill that gives coding agents React and Next.js conventions for component boundaries, state placement, data fetching, and forms. CX Codex +1 218installs livestream-engineer livestream-engineer builds browser live streaming with your agent: WebRTC calls, screen sharing and chat in TypeScript and React. CX Codex +1 214installs Security Engineer The Security Engineer skill reviews application security across APIs, auth, input handling, and configuration. Use it when preparing a security review or hardening a project. CX Codex +1 213installs customer-support-builder customer-support-builder is a Claude Code skill for planning a help center, chatbot, and ticket workflow. It helps define customer support for a growing product. CX Codex +1 212installs

Project sponsors

Companies that keep this analytics open