Design System Steward

Design System Steward

Overview

Treat a design system as a product: foundations, tokens, components, patterns, documentation, tooling, governance, and adoption must work together across design and code.

Use this skill to produce practical artifacts: an initial design-system blueprint, a component or token spec, a migration plan, an audit report, or an improvement roadmap.

First Move

Identify the user's mode from the request:

If the user provides artifacts, inspect the actual files before judging: Figma exports, token JSON, Storybook, component source, docs site, screenshots, screenshots of Figma libraries, package APIs, or contribution docs.

Workflow

1. Frame the product context: audience, platforms, brand constraints, tech stack, design tools, release model, and current pain.
2. Inventory the system: foundations, tokens, components, patterns, docs, code APIs, accessibility coverage, governance, and adoption signals.
3. Choose the right reference:
   • For audits, read references/audit-rubric.md.
   • For token work, read references/token-architecture.md.
   • For component specs, read references/component-spec-template.md.
   • For plans or reports, read references/report-templates.md.
4. Produce an artifact that names assumptions, evidence, decisions, risks, and next actions.
5. Prefer small, shippable increments: stabilize foundations before expanding components, and fix high-use/high-risk components before low-traffic polish.

Quality Bar

Require every serious design-system recommendation to connect at least two surfaces:

• Design asset or Figma library behavior
• Code implementation or package API
• Documentation and usage guidance
• Accessibility behavior and testability
• Governance, ownership, contribution, or release process

Do not treat visual consistency as sufficient. A mature system must also be usable by product teams, implementable by engineers, testable, versioned, and governable.

Output Files

Always write artifacts to disk using Write/Edit tools. Never deliver content only as a chat reply.

Where to write

• Single-package project: write under the project root.
• Monorepo: write under the root of the frontend/UI package (e.g. packages/ui/, apps/web/). If unclear, ask the user before writing.

The DESIGN/ directory — three layers

The canonical output is a DESIGN/ directory with three layers. This is what AI coding assistants (Claude Code, Cursor, Codex) will read on every coding task.

DESIGN/
├── index.md                  # System overview + component/pattern quick-reference table
├── foundation.md             # Colors, typography, spacing, motion, iconography, Do's and Don'ts
├── tokens.md                 # Primitive → semantic → component token layers, naming, theming/modes
├── governance.md             # Contribution model, ownership, versioning, release process
├── components/               # One .md per component (see component-spec-template.md)
│   ├── button.md
│   ├── alert.md
│   └── ...
└── patterns/
    ├── index.md              # Pattern quick-reference: scenario → which pattern to use
    ├── flows/                # Multi-step interaction flows (e.g. delete-confirm, multi-step-form)
    ├── blocks/               # Functional sections (e.g. data-table, empty-state, filter-bar)
    └── pages/                # Full page templates (e.g. list-page, detail-page, error-page)

File structure by mode

Create — generate the full DESIGN/ directory. Start with foundation.md and tokens.md, then components, then patterns. Read references/component-spec-template.md before writing any component file. Read references/pattern-spec-template.md before writing any pattern file.

Edit — modify only the affected files. If a file doesn't exist yet, create it in the correct layer.

Improve — write DESIGN/improvement-roadmap.md, then update the affected spec files.

Audit — write DESIGN/audit.md using references/report-templates.md.

foundation.md minimum sections

1. Style intent (one sentence: what feeling/density/brand this UI should have)
2. Colors (name, hex, when to use)
3. Typography (scale, weights, sizes)
4. Spacing and layout (grid, scale)
5. Motion (duration, easing, reduced-motion policy)
6. Iconography (library, size, usage rules)
7. Do's and Don'ts (Don'ts are more important than Do's — they stop AI from guessing wrong)

index.md minimum content

• One-paragraph system summary
• Component quick-reference table: component name | file | use when | do NOT use when
• Pattern quick-reference table: scenario | pattern | file

Common Mistakes

• Starting with components before defining semantic tokens and accessibility constraints.
• Naming tokens by visual value (blue-500) when the real contract is purpose (color-action-primary).
• Documenting only the happy path while omitting anatomy, states, variants, keyboard behavior, responsive behavior, and anti-patterns.
• Auditing screenshots without checking source, token usage, package APIs, or contribution/release process.
• Creating too many severity levels or maturity categories; keep scoring explainable and tied to action.