/design-system
If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.
Manage your design system — audit for consistency, document components, or design new patterns.
Usage
/design-system audit # Full system audit
/design-system document [component] # Document a component
/design-system extend [pattern] # Design a new component or pattern
Components of a Design System
Design Tokens
Atomic values that define the visual language:
- Colors (brand, semantic, neutral)
- Typography (scale, weights, line heights)
- Spacing (scale, component padding)
- Borders (radius, width)
- Shadows (elevation levels)
- Motion (durations, easings)
Components
Reusable UI elements with defined:
- Variants (primary, secondary, ghost)
- States (default, hover, active, disabled, loading, error)
- Sizes (sm, md, lg)
- Behavior (interactions, animations)
- Accessibility (ARIA, keyboard)
Patterns
Common UI solutions combining components:
- Forms (input groups, validation, submission)
- Navigation (sidebar, tabs, breadcrumbs)
- Data display (tables, cards, lists)
- Feedback (toasts, modals, inline messages)
Principles
- Consistency over creativity — The system exists so teams don't reinvent the wheel
- Flexibility within constraints — Components should be composable, not rigid
- Document everything — If it's not documented, it doesn't exist
- Version and migrate — Breaking changes need migration paths
Output — Audit
## Design System Audit
### Summary
**Components reviewed:** [X] | **Issues found:** [X] | **Score:** [X/100]
### Naming Consistency
| Issue | Components | Recommendation |
|-------|------------|----------------|
| [Inconsistent naming] | [List] | [Standard to adopt] |
### Token Coverage
| Category | Defined | Hardcoded Values Found |
|----------|---------|----------------------|
| Colors | [X] | [X] instances of hardcoded hex |
| Spacing | [X] | [X] instances of arbitrary values |
| Typography | [X] | [X] instances of custom fonts/sizes |
### Component Completeness
| Component | States | Variants | Docs | Score |
|-----------|--------|----------|------|-------|
| Button | ✅ | ✅ | ⚠️ | 8/10 |
| Input | ✅ | ⚠️ | ❌ | 5/10 |
### Priority Actions
1. [Most impactful improvement]
2. [Second priority]
3. [Third priority]
Output — Document
## Component: [Name]
### Description
[What this component is and when to use it]
### Variants
| Variant | Use When |
|---------|----------|
| [Primary] | [Main actions] |
| [Secondary] | [Supporting actions] |
### Props / Properties
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| [prop] | [type] | [default] | [description] |
### States
| State | Visual | Behavior |
|-------|--------|----------|
| Default | [description] | — |
| Hover | [description] | [interaction] |
| Active | [description] | [interaction] |
| Disabled | [description] | Non-interactive |
| Loading | [description] | [animation] |
### Accessibility
- **Role**: [ARIA role]
- **Keyboard**: [Tab, Enter, Escape behavior]
- **Screen reader**: [Announced as...]
### Do's and Don'ts
| ✅ Do | ❌ Don't |
|------|---------|
| [Best practice] | [Anti-pattern] |
### Code Example
[Framework-appropriate code snippet]
Output — Extend
## New Component: [Name]
### Problem
[What user need or gap this component addresses]
### Existing Patterns
| Related Component | Similarity | Why It's Not Enough |
|-------------------|-----------|---------------------|
| [Component] | [What's shared] | [What's missing] |
### Proposed Design
#### API / Props
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| [prop] | [type] | [default] | [description] |
#### Variants
| Variant | Use When | Visual |
|---------|----------|--------|
| [Variant] | [Scenario] | [Description] |
#### States
| State | Behavior | Notes |
|-------|----------|-------|
| Default | [Description] | — |
| Hover | [Description] | [Interaction] |
| Disabled | [Description] | Non-interactive |
| Loading | [Description] | [Animation] |
#### Tokens Used
- Colors: [Which tokens]
- Spacing: [Which tokens]
- Typography: [Which tokens]
### Accessibility
- **Role**: [ARIA role]
- **Keyboard**: [Expected interactions]
- **Screen reader**: [Announced as...]
### Open Questions
- [Decision that needs design review]
- [Edge case to resolve]
If Connectors Available
If ~~design tool is connected:
- Audit components directly in Figma — check naming, variants, and token usage
- Pull component properties and layer structure for documentation
If ~~knowledge base is connected:
- Search for existing component documentation and usage guidelines
- Publish updated documentation to your wiki
Tips
- Start with an audit — Know where you are before deciding where to go.
- Document as you build — It's easier to document a component while designing it.
- Prioritize coverage over perfection — 80% of components documented beats 100% of 10 components.
1---2name: design-system3description: Audit, document, or extend your design system. Use when checking for naming inconsistencies or hardcoded values across components, writing documentation for a component's variants, states, and accessibility notes, or designing a new pattern that fits the existing system.4---5
6# /design-system
7
8> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
9
10Manage your design system — audit for consistency, document components, or design new patterns.
11
12## Usage
13
14```
15/design-system audit # Full system audit
16/design-system document [component] # Document a component
17/design-system extend [pattern] # Design a new component or pattern
18```
19
20## Components of a Design System
21
22### Design Tokens
23Atomic values that define the visual language:
24- Colors (brand, semantic, neutral)
25- Typography (scale, weights, line heights)
26- Spacing (scale, component padding)
27- Borders (radius, width)
28- Shadows (elevation levels)
29- Motion (durations, easings)
30
31### Components
32Reusable UI elements with defined:
33- Variants (primary, secondary, ghost)
34- States (default, hover, active, disabled, loading, error)
35- Sizes (sm, md, lg)
36- Behavior (interactions, animations)
37- Accessibility (ARIA, keyboard)
38
39### Patterns
40Common UI solutions combining components:
41- Forms (input groups, validation, submission)
42- Navigation (sidebar, tabs, breadcrumbs)
43- Data display (tables, cards, lists)
44- Feedback (toasts, modals, inline messages)
45
46## Principles
47
481. **Consistency over creativity** — The system exists so teams don't reinvent the wheel
492. **Flexibility within constraints** — Components should be composable, not rigid
503. **Document everything** — If it's not documented, it doesn't exist
514. **Version and migrate** — Breaking changes need migration paths
52
53## Output — Audit
54
55```markdown
56## Design System Audit
57
58### Summary
59**Components reviewed:** [X] | **Issues found:** [X] | **Score:** [X/100]
60
61### Naming Consistency
62| Issue | Components | Recommendation |
63|-------|------------|----------------|
64| [Inconsistent naming] | [List] | [Standard to adopt] |
65
66### Token Coverage
67| Category | Defined | Hardcoded Values Found |
68|----------|---------|----------------------|
69| Colors | [X] | [X] instances of hardcoded hex |
70| Spacing | [X] | [X] instances of arbitrary values |
71| Typography | [X] | [X] instances of custom fonts/sizes |
72
73### Component Completeness
74| Component | States | Variants | Docs | Score |
75|-----------|--------|----------|------|-------|
76| Button | ✅ | ✅ | ⚠️ | 8/10 |
77| Input | ✅ | ⚠️ | ❌ | 5/10 |
78
79### Priority Actions
801. [Most impactful improvement]
812. [Second priority]
823. [Third priority]
83```
84
85## Output — Document
86
87```markdown
88## Component: [Name]
89
90### Description
91[What this component is and when to use it]
92
93### Variants
94| Variant | Use When |
95|---------|----------|
96| [Primary] | [Main actions] |
97| [Secondary] | [Supporting actions] |
98
99### Props / Properties
100| Property | Type | Default | Description |
101|----------|------|---------|-------------|
102| [prop] | [type] | [default] | [description] |
103
104### States
105| State | Visual | Behavior |
106|-------|--------|----------|
107| Default | [description] | — |
108| Hover | [description] | [interaction] |
109| Active | [description] | [interaction] |
110| Disabled | [description] | Non-interactive |
111| Loading | [description] | [animation] |
112
113### Accessibility
114- **Role**: [ARIA role]
115- **Keyboard**: [Tab, Enter, Escape behavior]
116- **Screen reader**: [Announced as...]
117
118### Do's and Don'ts
119| ✅ Do | ❌ Don't |
120|------|---------|
121| [Best practice] | [Anti-pattern] |
122
123### Code Example
124[Framework-appropriate code snippet]
125```
126
127## Output — Extend
128
129```markdown
130## New Component: [Name]
131
132### Problem
133[What user need or gap this component addresses]
134
135### Existing Patterns
136| Related Component | Similarity | Why It's Not Enough |
137|-------------------|-----------|---------------------|
138| [Component] | [What's shared] | [What's missing] |
139
140### Proposed Design
141
142#### API / Props
143| Property | Type | Default | Description |
144|----------|------|---------|-------------|
145| [prop] | [type] | [default] | [description] |
146
147#### Variants
148| Variant | Use When | Visual |
149|---------|----------|--------|
150| [Variant] | [Scenario] | [Description] |
151
152#### States
153| State | Behavior | Notes |
154|-------|----------|-------|
155| Default | [Description] | — |
156| Hover | [Description] | [Interaction] |
157| Disabled | [Description] | Non-interactive |
158| Loading | [Description] | [Animation] |
159
160#### Tokens Used
161- Colors: [Which tokens]
162- Spacing: [Which tokens]
163- Typography: [Which tokens]
164
165### Accessibility
166- **Role**: [ARIA role]
167- **Keyboard**: [Expected interactions]
168- **Screen reader**: [Announced as...]
169
170### Open Questions
171- [Decision that needs design review]
172- [Edge case to resolve]
173```
174
175## If Connectors Available
176
177If **~~design tool** is connected:
178- Audit components directly in Figma — check naming, variants, and token usage
179- Pull component properties and layer structure for documentation
180
181If **~~knowledge base** is connected:
182- Search for existing component documentation and usage guidelines
183- Publish updated documentation to your wiki
184
185## Tips
186
1871. **Start with an audit** — Know where you are before deciding where to go.
1882. **Document as you build** — It's easier to document a component while designing it.
1893. **Prioritize coverage over perfection** — 80% of components documented beats 100% of 10 components.
ahang1598