Design System
Build, evolve, or audit a design system. Stack-agnostic in principle. Implementation is stack-specific (Figma, Storybook, code library, etc.) but the structure and governance principles transfer.
This skill is for building the system. For applying a system to specific pages or components, use design-standards. For brand visual identity, use brand-identity.
When to use
- Building a design system from scratch
- Auditing an existing system for gaps or fragmentation
- Defining design tokens at the system level
- Structuring a component library
- Establishing contribution and governance models
- Migrating from ad-hoc components to a documented system
When NOT to use
- Designing a single page or component (use
design-standards) - Brand identity work (use
brand-identity) - Component-level frontend implementation (use
frontend-component-build) - Pure design documentation for marketing (use
brand-style-guide)
Required inputs
- The brand identity (tokens, voice, imagery direction)
- The product surfaces the system needs to support (web, mobile, marketing, app, internal tools)
- The team and its working tools (Figma, code framework, doc platform)
- Existing components, even if undocumented
- Constraints (accessibility requirements, performance targets, browser support)
If brand identity is undefined, run brand-identity first.
The framework: 5 layers
A complete design system has five layers, stacked. Each layer feeds the layer above.
1. Foundations (tokens)
The atomic decisions. Color, type, spacing, radius, shadow, motion, breakpoints.
Why this layer matters:
- Tokens are the source of truth for everything above
- Token changes propagate everywhere automatically
- Without tokens, the system has no foundation
Output:
- A documented token set (see
design-standards/references/design-tokens-template.md) - Token implementation in code (CSS variables, JS objects, Style Dictionary, etc.)
- Token implementation in Figma (variables and styles)
- A primer doc explaining what tokens to use when
Common patterns:
- Two-tier tokens: base tokens (raw values) + semantic tokens (named uses). Example:
color-blue-600(base) +color-text-link(semantic). Components reference semantic tokens. Theme changes update semantic tokens, not base.
2. Elements (atoms)
The smallest functional building blocks. Buttons, inputs, labels, badges, icons, links, dividers.
Per element, document:
- Visual variants (primary, secondary, ghost, etc.)
- Size variants (small, medium, large)
- States (default, hover, focus, active, disabled, error, loading)
- Anatomy (the parts that make up the element)
- Spacing and proportions
- Accessibility (keyboard support, screen reader behavior, ARIA)
- Code usage (props, examples)
Output:
- Element library in Figma
- Element components in code
- Per-element documentation
3. Components (molecules + organisms)
Combinations of elements that form recognizable UI patterns. Cards, alerts, modals, navigation, forms, data tables, headers, footers.
Per component:
- Composition (which elements it uses)
- Variants and configurations
- Use cases (when to reach for this vs. an alternative)
- Layout behavior (responsive, contained, full-bleed)
- Anti-patterns (when NOT to use it)
Output:
- Component library
- Per-component documentation with usage guidance
4. Patterns (templates)
Larger structures that combine components. Sign-in flow, settings page, dashboard layout, marketing page sections.
Per pattern:
- The structure and components used
- The user journey it supports
- Layout grid and spacing
- Responsive behavior
- Variants (e.g., "with sidebar," "fullscreen," "modal")
Output:
- Pattern library or page templates
- Documentation showing complete examples
5. Documentation and governance
How the system gets used, contributed to, and maintained.
Documentation includes:
- Getting started guide for new team members
- How to use vs. how to extend
- Contribution model
- Versioning policy
- Migration paths when breaking changes happen
- Decision log for major system choices
Governance includes:
- Who owns the system (a team or rotation)
- How new components get proposed and approved
- How conflicts get resolved
- How the system evolves vs. stays stable
- Cadence of review and updates
Workflow
For a new design system
- Inventory the existing UI. Screenshot every component, button, form, modal across the product. The list of distinct UI patterns is your starting scope.
- Identify the duplicates. Same component built 5 different ways across the product. These are your high-value consolidation targets.
- Define foundations. Token set, with both base and semantic layers. Document each.
- Audit elements. From the inventory, identify the actual elements (buttons, inputs, etc.) and reduce variants to a managed set.
- Build the element library. Figma + code. Document each element.
- Identify priority components. The 10 to 15 components that appear most often. Build those first.
- Document patterns. Page-level templates that show the system in use.
- Establish governance. Owner, contribution model, review cadence.
- Roll out. Migrate existing surfaces to the system progressively.
For an existing design system audit
- Inventory what exists. What's documented, what's in Figma, what's in code, what's actually used in production.
- Map gaps. Where the system is incomplete. Where teams build outside the system because the system can't serve their need.
- Map fragmentation. Where the system has divergent implementations (Figma vs. code, web vs. mobile, multiple teams).
- Identify decay. Components that have drifted from the documented standard.
- Prioritize fixes. Foundation gaps first. High-use component drift second. Rarely-used component cleanup last.
- Plan rollout. Major changes need migration paths.
Failure patterns
- Building the system before the brand is set. Tokens depend on brand. Set brand first.
- Atoms-up extreme. Spending 6 months on tokens and elements before producing components anyone uses. Ship components people need; refine tokens iteratively.
- One-person system. A system without governance fails as soon as the original designer leaves. Establish ownership early.
- Stale documentation. A system with code that's diverged from the docs is worse than no system. Synchronize or kill the docs.
- Versioning everything. Treating every component as needing a major version. Most components evolve in place. Reserve versioning for breaking changes.
- Adopting "atomic design" dogmatically. Atoms / molecules / organisms is a useful mental model, not a rigid taxonomy. Don't argue about whether something is a molecule or an organism.
- Building in a vacuum. A system designed without input from the teams using it gets ignored. Co-design with consumers.
- No deprecation path. Old components linger in code forever because no one knows it's safe to remove them. Document deprecation explicitly.
- Token explosion. Defining 200 color tokens for a brand with 10 colors. Discipline. Most products need fewer tokens than they have.
Output format
A design system has multiple deliverables. Typically:
- Documentation site (Notion, dedicated site, GitHub Pages, Storybook addon, etc.)
- Figma library (or equivalent design tool)
- Code library (npm package, monorepo workspace, copy-paste components)
- Decision log (system-level decisions and the reasoning)
- Roadmap and changelog
For a design system audit, output is a markdown report at design-system-audit.md:
- Inventory of what exists (foundations, elements, components, patterns)
- Gap analysis
- Fragmentation analysis
- Drift analysis
- Prioritized remediation plan
- Governance recommendations
If required data is unavailable
This skill's output depends on data, measurements, or tool results it cannot generate on its own. When a required input, tool, or data source is unavailable or unverifiable, the sanctioned output is the deliverable with the gap stated: what was needed, what was actually obtained or verified, and which parts of the output are affected. Fabricating, estimating, or interpolating a required number to complete the deliverable is never sanctioned. A stated gap is a complete answer.
Reference files
references/system-architecture.md- The four-layer model (tokens, primitives, patterns, templates) and how to decide where new work belongs.references/system-audit-template.md- Template for auditing an existing design system.references/governance-playbook.md- Contribution model, ownership, and decision process for an active system.
