Build or audit a design system including component library, design tokens, naming conventions, contribution model, and documentation. Use this skill whenever the user wants to build a design system, audit an existing system, define design tokens at the system level, structure a component library, or set up design system governance. Triggers on design system, component library, design tokens, atomic design, atoms, molecules, organisms, design system documentation, Storybook, Figma library, system governance, design contribution model. Also triggers when teams are inconsistent across products and a system is the answer.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Build or audit a design system including component library, design tokens, naming conventions, contribution model, and documentation. Use this skill whenever the user wants to build a design system, audit an existing system, define design tokens at the system level, structure a component library, or set up design system governance. Triggers on design system, component library, design tokens, atomic design, atoms, molecules, organisms, design system documentation, Storybook, Figma library, system governance, design contribution model. Also triggers when teams are inconsistent across products and a system is the answer.
category
design
catalog_summary
Component library, design tokens, design system documentation
display_order
1
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)
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.
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.)
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.
