design-system skill
✓ VerifiedBuild, evolve, or audit design systems including component libraries, design tokens, naming conventions, and governance models.
- GitHub stars
- 1,066
- Files
- 5
- Last commit
- Nov 8, 2026
- License
- MIT
- Allowed tools
- —
What does the design-system skill do?
design-system is an agent skill. Build, evolve, or audit design systems including component libraries, design tokens, naming conventions, and governance models.
Summary generated from the skill's SKILL.md.
About the design-system skill
Building, evolving, or auditing design systems is the primary function of this skill. It serves product teams and designers who need to establish a single source of truth for their user interfaces. An agent should load this skill when a user needs to create a component library from scratch, define design tokens, or resolve inconsistencies across different product surfaces. It produces structured outputs such as documented token sets, Figma libraries, component documentation, and governance models.
The skill operates across five layers: foundations, elements, components, patterns, and documentation. It relies on inputs like brand identity, existing components, and specific toolsets such as Figma or Storybook. Unlike tools meant for single-page design or brand identity, this skill focuses on the systemic architecture and long-term maintenance of UI patterns. It can generate a markdown report for audits that includes gap analysis, fragmentation mapping, and prioritized remediation plans.
What an agent can do with it
- 1Create a new design systemDevelop a complete system from the ground up including tokens, elements, and governance.
- 2Audit existing UI fragmentationAnalyze an current system to find gaps, drift, or inconsistencies between design and code.
- 3Define system-level design tokensEstablish the atomic foundations like color, spacing, and typography that drive the entire UI.
- 4Establish design governanceSet up the rules for how teams contribute to and maintain the component library.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the design-system skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the design-system skill in Plugin
/plugin marketplace add rampstackco/claude-skills /plugin install rampstack-skills@rampstack
Install the design-system skill in Claude Code
~/.claude/skills/design-system/SKILL.md
$ npx degit rampstackco/claude-skills/skills/design-system ~/.claude/skills/design-systemInstall the design-system skill in Claude Code (project)
.claude/skills/design-system/SKILL.md
$ npx degit rampstackco/claude-skills/skills/design-system .claude/skills/design-systemInstall the design-system skill in Codex
~/.agents/skills/design-system/SKILL.md
$ npx degit rampstackco/claude-skills/skills/design-system ~/.agents/skills/design-systemInstall the design-system skill in Gemini CLI
~/.gemini/skills/design-system/SKILL.md
$ npx degit rampstackco/claude-skills/skills/design-system ~/.gemini/skills/design-systemInstall the design-system skill in Claude.ai
npx degit rampstackco/claude-skills/skills/design-system design-system && zip -r design-system.zip design-system # claude.ai → Customize → Skills → + → Create skill → Upload a skill → design-system.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablerampstackco/claude-skills/skills/design-system is public and reachablegithub.com/rampstackco/claude-skills/tree/HEAD/skills/design ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-08github.com/rampstackco/claude-skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/rampstackco/claude-skills/blob/HEAD/skills/design ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/rampstackco/claude-skills/blob/HEAD/skills/design ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 209 linesgithub.com/rampstackco/claude-skills/blob/HEAD/skills/design ↗Pass
SKILL.md
View on GitHubDesign 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.
Files in this skill
5design-system skill questions
How do I install the design-system skill in Claude Code?
Run npx degit rampstackco/claude-skills/skills/design-system ~/.claude/skills/design-system. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the design-system skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What should I do if my brand identity is not yet defined?
You should run the brand-identity skill first, as design tokens depend on the brand.
What are the five layers of a complete design system?
A complete system consists of Foundations (tokens), Elements (atoms), Components (molecules + organisms), Patterns (templates), and Documentation and governance.