| name | design-systems |
| description | Design systems architecture - tokens, components, documentation, governance. Use when building or scaling a design system, defining component APIs, establishing token architecture, or creating contribution guidelines. |
Design Systems
A design system is infrastructure, not decoration. It's the foundation that lets you ship fast without shipping broken. But here's the thing: don't build a design system for a product that hasn't found PMF yet. You'll redesign everything in 3 months. Start with tokens and a handful of primitives. Scale the system as the product scales.
When to Use This Skill
Auto-loaded by agents:
- design-systems-lead - For all design system work
Use when you need:
- Token architecture (color, typography, spacing, elevation)
- Component specification and API design
- Documentation standards
- Design system governance and contribution models
Token Architecture
Token Layers
- Global tokens - Raw values (
blue-500: #3B82F6)
- Semantic tokens - Intent-based aliases (
color-primary: blue-500)
- Component tokens - Scoped to components (
button-bg: color-primary)
Core Token Categories
- Color: Brand, semantic (success/warning/error/info), neutral, surface, text
- Typography: Font family, size scale, weight, line height, letter spacing
- Spacing: Base unit (typically 4px or 8px), scale (0, 1, 2, 3, 4, 6, 8, 12, 16...)
- Elevation: Shadow levels (0-5), z-index scale
- Border: Radius scale, width, style
- Motion: Duration (fast/normal/slow), easing curves
- Breakpoints: Viewport widths for responsive design
Component Specification Template
For every component, document:
- Purpose - What problem does this solve?
- Anatomy - Named parts and their relationships
- Variants - Types/styles (primary, secondary, ghost, destructive)
- Sizes - Scale options (sm, md, lg)
- States - Default, hover, active, focus, disabled, loading, error
- Props/API - Configurable properties with types and defaults
- Accessibility - ARIA roles, keyboard behavior, screen reader announcements
- Usage guidelines - When to use, when NOT to use, do/don't examples
- Content guidelines - Label length, tone, capitalization
Governance
Contribution Model
- Centralized: Core team owns all components. Consistent but slow.
- Federated: Product teams contribute, core team reviews. Scalable but needs governance.
- Hybrid: Core team owns primitives and patterns, product teams extend.
Component Lifecycle
- Proposal - Problem statement, use cases, existing alternatives
- Design - Spec, variants, states, accessibility
- Build - Implementation with tests
- Document - Usage guidelines, examples, API reference
- Release - Versioned, changelog, migration guide
- Maintain - Bug fixes, enhancements, deprecation
The Only Metric That Matters
A design system that nobody uses is just a library. Adoption is the only metric that matters. If your adoption rate is under 80%, the system has a product problem, not a documentation problem.
Related Skills
accessibility-wcag - Accessibility requirements per componentinteraction-patterns - Pattern selection for component behavior
