| name | design-system |
| description | Full pipeline for systematically building a UI design system. An agent team collaborates to create design tokens, React/Vue component libraries, Storybook, WCAG accessibility verification, and documentation. Use this skill for requests like 'build a design system', 'component library', 'UI kit', 'design tokens', 'Storybook setup', 'accessibility verification', 'WCAG verification', 'UI components', 'create a button component', etc. Note: Figma plugin development, design system SaaS construction, and native app components (SwiftUI/Jetpack Compose) are outside the scope of this skill. |
Design System — UI Design System Full Pipeline
An agent team collaborates to build design tokens, components, Storybook, accessibility verification, and documentation.
Execution Mode
Agent Team — Five agents communicate directly via SendMessage and perform cross-validation.
Agent Composition
| Agent | File | Role | Type |
|---|
| token-designer | .claude/agents/token-designer.md | Design token design | general-purpose |
| component-developer | .claude/agents/component-developer.md | Component development | general-purpose |
| a11y-auditor | .claude/agents/a11y-auditor.md | Accessibility verification | general-purpose |
| storybook-builder | .claude/agents/storybook-builder.md | Storybook setup | general-purpose |
| doc-writer | .claude/agents/doc-writer.md | Documentation | general-purpose |
Workflow
Phase 1: Preparation (performed directly by the orchestrator)
- Extract the following from user input:
- Brand information: Brand colors, logo, tone and manner
- Framework: React/Vue/Angular/Web Components
- Component scope: Required component list (or "all")
- Accessibility level: WCAG AA (default) / AAA
- Existing system (optional): Existing design system to migrate from
- Create the
_workspace/ directory and subdirectories
- Organize the input and save it to
_workspace/00_input.md
- If pre-existing files are available, copy them to
_workspace/ and skip the corresponding phase
- Determine the execution mode based on the scope of the request
Phase 2: Team Assembly and Execution
| Order | Task | Owner | Dependencies | Deliverable |
|---|
| 1 | Token design | token-designer | None | 01_design_tokens/ |
| 2 | Component development | component-developer | Task 1 | 02_components/ |
| 3a | Storybook setup | storybook-builder | Tasks 1, 2 | 03_storybook/ |
| 3b | Accessibility verification | a11y-auditor | Tasks 1, 2 | 04_a11y_report.md |
| 4 | Documentation | doc-writer | Tasks 1, 2, 3a, 3b | 05_docs/ |
Tasks 3a (Storybook) and 3b (accessibility) run in parallel.
Inter-agent communication flow:
- token-designer completes > passes token import methods to component-developer, contrast verification to a11y-auditor
- component-developer completes > passes props types to storybook-builder, ARIA status to a11y-auditor
- a11y-auditor > requests fixes from component-developer for P0/P1 issues (up to 2 rounds)
- storybook-builder completes > passes Storybook structure to doc-writer
- a11y-auditor completes > passes accessibility guide to doc-writer
- doc-writer performs final consistency verification across all deliverables
Phase 3: Integration and Final Deliverables
- Verify all files in
_workspace/
- Confirm all accessibility P0 issues are resolved
- Present the final summary to the user:
- Token system —
01_design_tokens/
- Components —
02_components/
- Storybook —
03_storybook/
- Accessibility report —
04_a11y_report.md
- Documentation —
05_docs/
Execution Modes by Request Scope
| User Request Pattern | Execution Mode | Agents Deployed |
|---|
| "Build a complete design system" | Full pipeline | All 5 agents |
| "Just design tokens" | Token mode | token-designer only |
| "Build components from these tokens" | Component mode | component-developer + storybook-builder |
| "Accessibility verification only" | Verification mode | a11y-auditor only |
| "Just add Storybook" | Storybook mode | storybook-builder only |
| "Just write documentation" | Doc mode | doc-writer only |
| "Add just a Button component" | Single component | component-developer + a11y-auditor + storybook-builder |
Reusing existing systems: If existing tokens are available, skip token-designer. If only adding Storybook to existing components, deploy storybook-builder only.
Data Transfer Protocol
| Strategy | Method | Purpose |
|---|
| File-based | _workspace/ directory | Code, configuration, documentation |
| Message-based | SendMessage | Key information, fix requests, verification results |
Error Handling
| Error Type | Strategy |
|---|
| Brand color not provided | Start with neutral palette (slate); request colors from user |
| Framework unspecified | Default to React + TypeScript; change after user confirmation |
| Contrast ratio not met | Auto-adjust and report both original and adjusted values |
| Accessibility P0 unresolved | Block release; request re-fix from component-developer |
| Agent failure | Retry once; if still failing, proceed without that deliverable |
Test Scenarios
Normal Flow
Prompt: "Build a React design system with blue brand colors. I need Button, Input, Card, and Modal"
Expected result:
- Tokens: Blue-based color scale, semantic colors, typography, spacing, dark mode
- Components: Button (4 variants, 3 sizes), Input (text/password/search), Card, Modal + shared hooks
- Storybook: Token visualization, Default/AllVariants/Playground stories per component
- Accessibility: WCAG AA compliance verification, keyboard tests, contrast matrix
- Documentation: Design principles, getting started guide, per-component Do/Don't, contribution guide
Existing File Reuse Flow
Prompt: "Add a DatePicker component to the existing design system"
Expected result:
- component-developer implements DatePicker using existing tokens
- a11y-auditor verifies date picker accessibility (keyboard, screen reader)
- storybook-builder adds DatePicker stories
- token-designer and doc-writer have minimal involvement
Error Flow
Prompt: "Build a design system" (no colors or framework specified)
Expected result:
- token-designer starts with a neutral palette while requesting brand colors from user
- component-developer defaults to React + TypeScript
- a11y-auditor verifies contrast ratios of the default palette
- doc-writer emphasizes the customization guide (how to change colors)
Agent Extension Skills
Skills that enhance each agent's domain expertise:
| Skill | File | Target Agent | Role |
|---|
| wcag-checker | .claude/skills/wcag-checker/skill.md | a11y-auditor, component-developer | WCAG 2.1 accessibility checklist, contrast calculation, ARIA patterns, keyboard matrix |
| token-generator | .claude/skills/token-generator/skill.md | token-designer, component-developer | Design token 3-tier structure, color scale algorithm, typography/spacing/motion system |
