design-system

name design-system description 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. argument-hint [audit | document | extend] <component or system> /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.