# Design System Steward

> Use when creating, editing, improving, migrating, documenting, or auditing a design system, UI kit, component library, design tokens, Figma variables, accessibility standards, contribution model, or design-system governance.

- Skill: `mangmax/design-system-steward` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mangmax/design-system-steward`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mangmax/design-system-steward/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: mangmax (https://skillmd.com/u/mangmax)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mangmax/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:

| Mode | Use when the user asks to... | Primary output |
| --- | --- | --- |
| Create | start a design system, define foundations, create tokens/components | blueprint and starter backlog |
| Edit | update tokens, component specs, docs, or governance | concrete changes and rationale |
| Improve | mature an existing system, reduce inconsistency, migrate themes | prioritized roadmap |
| Audit | review quality, accessibility, consistency, adoption, docs | scored report with evidence |

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.