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 |
1---2name: design-system3description: 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.4---56# Design System — UI Design System Full Pipeline78An agent team collaborates to build design tokens, components, Storybook, accessibility verification, and documentation.910## Execution Mode1112**Agent Team** — Five agents communicate directly via SendMessage and perform cross-validation.1314## Agent Composition1516| Agent | File | Role | Type |17|-------|------|------|------|18| token-designer | `.claude/agents/token-designer.md` | Design token design | general-purpose |19| component-developer | `.claude/agents/component-developer.md` | Component development | general-purpose |20| a11y-auditor | `.claude/agents/a11y-auditor.md` | Accessibility verification | general-purpose |21| storybook-builder | `.claude/agents/storybook-builder.md` | Storybook setup | general-purpose |22| doc-writer | `.claude/agents/doc-writer.md` | Documentation | general-purpose |2324## Workflow2526### Phase 1: Preparation (performed directly by the orchestrator)27281. Extract the following from user input:29 - **Brand information**: Brand colors, logo, tone and manner30 - **Framework**: React/Vue/Angular/Web Components31 - **Component scope**: Required component list (or "all")32 - **Accessibility level**: WCAG AA (default) / AAA33 - **Existing system** (optional): Existing design system to migrate from342. Create the `_workspace/` directory and subdirectories353. Organize the input and save it to `_workspace/00_input.md`364. If pre-existing files are available, copy them to `_workspace/` and skip the corresponding phase375. **Determine the execution mode** based on the scope of the request3839### Phase 2: Team Assembly and Execution4041| Order | Task | Owner | Dependencies | Deliverable |42|-------|------|-------|-------------|-------------|43| 1 | Token design | token-designer | None | `01_design_tokens/` |44| 2 | Component development | component-developer | Task 1 | `02_components/` |45| 3a | Storybook setup | storybook-builder | Tasks 1, 2 | `03_storybook/` |46| 3b | Accessibility verification | a11y-auditor | Tasks 1, 2 | `04_a11y_report.md` |47| 4 | Documentation | doc-writer | Tasks 1, 2, 3a, 3b | `05_docs/` |4849Tasks 3a (Storybook) and 3b (accessibility) run **in parallel**.5051**Inter-agent communication flow:**52- token-designer completes > passes token import methods to component-developer, contrast verification to a11y-auditor53- component-developer completes > passes props types to storybook-builder, ARIA status to a11y-auditor54- a11y-auditor > requests fixes from component-developer for P0/P1 issues (up to 2 rounds)55- storybook-builder completes > passes Storybook structure to doc-writer56- a11y-auditor completes > passes accessibility guide to doc-writer57- doc-writer performs final consistency verification across all deliverables5859### Phase 3: Integration and Final Deliverables60611. Verify all files in `_workspace/`622. Confirm all accessibility P0 issues are resolved633. Present the final summary to the user:64 - Token system — `01_design_tokens/`65 - Components — `02_components/`66 - Storybook — `03_storybook/`67 - Accessibility report — `04_a11y_report.md`68 - Documentation — `05_docs/`6970## Execution Modes by Request Scope7172| User Request Pattern | Execution Mode | Agents Deployed |73|---------------------|---------------|----------------|74| "Build a complete design system" | **Full pipeline** | All 5 agents |75| "Just design tokens" | **Token mode** | token-designer only |76| "Build components from these tokens" | **Component mode** | component-developer + storybook-builder |77| "Accessibility verification only" | **Verification mode** | a11y-auditor only |78| "Just add Storybook" | **Storybook mode** | storybook-builder only |79| "Just write documentation" | **Doc mode** | doc-writer only |80| "Add just a Button component" | **Single component** | component-developer + a11y-auditor + storybook-builder |8182**Reusing existing systems**: If existing tokens are available, skip token-designer. If only adding Storybook to existing components, deploy storybook-builder only.8384## Data Transfer Protocol8586| Strategy | Method | Purpose |87|----------|--------|---------|88| File-based | `_workspace/` directory | Code, configuration, documentation |89| Message-based | SendMessage | Key information, fix requests, verification results |9091## Error Handling9293| Error Type | Strategy |94|-----------|----------|95| Brand color not provided | Start with neutral palette (slate); request colors from user |96| Framework unspecified | Default to React + TypeScript; change after user confirmation |97| Contrast ratio not met | Auto-adjust and report both original and adjusted values |98| Accessibility P0 unresolved | Block release; request re-fix from component-developer |99| Agent failure | Retry once; if still failing, proceed without that deliverable |100101## Test Scenarios102103### Normal Flow104**Prompt**: "Build a React design system with blue brand colors. I need Button, Input, Card, and Modal"105**Expected result**:106- Tokens: Blue-based color scale, semantic colors, typography, spacing, dark mode107- Components: Button (4 variants, 3 sizes), Input (text/password/search), Card, Modal + shared hooks108- Storybook: Token visualization, Default/AllVariants/Playground stories per component109- Accessibility: WCAG AA compliance verification, keyboard tests, contrast matrix110- Documentation: Design principles, getting started guide, per-component Do/Don't, contribution guide111112### Existing File Reuse Flow113**Prompt**: "Add a DatePicker component to the existing design system"114**Expected result**:115- component-developer implements DatePicker using existing tokens116- a11y-auditor verifies date picker accessibility (keyboard, screen reader)117- storybook-builder adds DatePicker stories118- token-designer and doc-writer have minimal involvement119120### Error Flow121**Prompt**: "Build a design system" (no colors or framework specified)122**Expected result**:123- token-designer starts with a neutral palette while requesting brand colors from user124- component-developer defaults to React + TypeScript125- a11y-auditor verifies contrast ratios of the default palette126- doc-writer emphasizes the customization guide (how to change colors)127128## Agent Extension Skills129130Skills that enhance each agent's domain expertise:131132| Skill | File | Target Agent | Role |133|-------|------|-------------|------|134| wcag-checker | `.claude/skills/wcag-checker/skill.md` | a11y-auditor, component-developer | WCAG 2.1 accessibility checklist, contrast calculation, ARIA patterns, keyboard matrix |135| token-generator | `.claude/skills/token-generator/skill.md` | token-designer, component-developer | Design token 3-tier structure, color scale algorithm, typography/spacing/motion system |
revfactory