design-system

Files (4)

• SKILL.md
• governance-playbook.md · references/
• system-architecture.md · references/
• system-audit-template.md · references/

SKILL.md (first lines)

# 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

From rampstackco/claude-skills, MIT.

More from rampstackco/claude-skills