Skill · Design system
Design system.
Build the system, govern it, and keep the docs from rotting.
Build, evolve, or audit a design system. A complete system has five stacked layers: foundations (tokens), elements, components, patterns, and the documentation and governance that hold it together. Each layer feeds the one above, and tokens are the foundation everything else references.
The structure and governance principles transfer across stacks even though the implementation (Figma, Storybook, a code library) is stack-specific. This skill builds the shared system; applying it to a specific page is a separate job.
Audience: design-system owners and front-end leads building a system from scratch, auditing an existing one for gaps and drift, or migrating from ad-hoc components to a documented library.
The framework
Five layers, stacked. Each feeds the next.
A complete system has five layers. Each one builds on the layer below, starting from the tokens that everything references.
- 01Foundations (tokens): color, type, spacing, radius, shadow, motion, and breakpoints. Often two-tier: base tokens plus semantic tokens that components reference.
- 02Elements (atoms): the smallest functional blocks (buttons, inputs, badges, icons), each with variants, sizes, states, anatomy, and accessibility documented.
- 03Components (molecules and organisms): combinations of elements (cards, modals, navigation, forms, tables), with composition, variants, use cases, and anti-patterns.
- 04Patterns (templates): larger structures that combine components (a sign-in flow, a settings page, a dashboard layout) with the journey each supports.
- 05Documentation and governance: how the system gets used, contributed to, versioned, and owned, including a deprecation path so old components can be retired.
How the skill runs
Nine steps for a new design system.
Building a new system starts from the existing UI and consolidates upward, shipping the components people need before perfecting the ones they do not.
01
Inventory the existing UI
Screenshot every component, button, form, and modal across the product. The distinct patterns are the starting scope.
02
Identify the duplicates
The same component built five different ways is the high-value consolidation target.
03
Define foundations
A token set with both base and semantic layers, each documented.
04
Audit elements
From the inventory, identify the real elements and reduce the variant sprawl to a managed set.
05
Build the element library
In design tool and in code, with per-element documentation for variants, states, and accessibility.
06
Identify priority components
Build the 10 to 15 components that appear most often first, rather than perfecting tokens for six months.
07
Document patterns
Page-level templates that show the system in use, rather than the parts in isolation.
08
Establish governance
An owner, a contribution model, and a review cadence, set early so the system survives its author leaving.
09
Roll out
Migrate existing surfaces to the system progressively, with migration paths for breaking changes.
Pairs with these platforms
Where the system is built and documented.
The structure transfers across stacks, but the system itself is built in real tools. Figma holds the design library and the token variables; the documentation lives in Notion or another docs home; the code library, the decision log, and the changelog live in GitHub.
Reference files
Three references that go alongside the SKILL.md.
references/system-architecture.md
The layered model (tokens, primitives, patterns, templates) and how to decide where new work belongs.
references/system-audit-template.md
A template for auditing an existing system across inventory, gaps, fragmentation, and drift.
references/governance-playbook.md
The contribution model, ownership, and decision process for an active system.
Bridges to other skills
What sits above the system, and what sits inside it.
The design system depends on the brand above it and produces the components the application skills build.
Comes first
brand-identityTokens depend on the brand, so the identity gets set first. Building the system before the brand means rebuilding the foundations later.
Applying the system
design-standardsDesigning a single page or component is a design-standards job. This skill builds the shared, governed library those page-level decisions draw on.
Component implementation
frontend-component-buildImplements a single component well: its API, states, and accessibility. The system decides which components exist and how they relate.
Brand documentation
brand-style-guidePure brand documentation for marketing lives there. A design system is the build reference; the style guide is the brand reference.
Open source under MIT
Read the SKILL.md on GitHub.
The skill source lives in the rampstackco/claude-skills repository alongside dozens of other skills covering the full lifecycle of brand and product work. This page is a structured overview; the SKILL.md is the source. MIT licensed.
Frequently asked questions.
- What are the five layers of a design system?
- Foundations (tokens), elements (atoms), components (molecules and organisms), patterns (templates), and documentation and governance. The layers stack: each one feeds the layer above it, and tokens are the foundation everything references. A system missing the governance layer tends to fragment; a system missing real patterns leaves teams guessing how the parts compose.
- What are two-tier tokens?
- Base tokens hold raw values (for example color-blue-600); semantic tokens hold named uses (for example color-text-link). Components reference the semantic tokens, not the base ones. A theme change then updates the semantic layer while the base palette stays put, which keeps theming from rippling through every component. It also keeps the token count honest: defining 200 color tokens for a brand with 10 colors is the token-explosion failure.
- How do I avoid the atoms-up trap?
- Do not spend six months perfecting tokens and elements before producing a component anyone uses. Ship the 10 to 15 components that appear most often first, and refine the tokens iteratively as real components reveal what they need. Atoms, molecules, and organisms is a useful mental model, not a rigid taxonomy to argue inside of, so do not stall debating whether something is a molecule or an organism.
- Why does a design system need governance?
- Because a one-person system fails the moment the original designer leaves. Establish ownership early (a team or a rotation), a contribution model for proposing and approving new components, a versioning policy reserved for breaking changes rather than every edit, migration paths when breaking changes happen, and an explicit deprecation path so old components can actually be removed instead of lingering forever because no one knows it is safe.
- How is this different from design-standards?
- Design-system builds the shared, governed library: the tokens, elements, components, patterns, and the governance around them. Design-standards applies a system to specific pages and components day to day. Use design-standards when designing a single page or component; use design-system when building the library those decisions draw on, or auditing one that has fragmented.
- What does a design-system audit produce?
- A report covering an inventory of what exists (foundations, elements, components, patterns), a gap analysis of where the system is incomplete, a fragmentation analysis of where implementations diverge (Figma versus code, web versus mobile, team versus team), a drift analysis of components that have wandered from the documented standard, a prioritized remediation plan (foundation gaps first, high-use component drift second, rarely-used cleanup last), and governance recommendations.