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