Bootstrap a design system

.design/ is the project's living design source. Bootstrapping it produces four artifacts every subsequent command depends on. Tokens, philosophy, specimens, and config.json.

Two paths to the same result:

1. Inside Claude Code (recommended). Interactive discovery, project-flavored output, full specimen library.
2. From the terminal (CI / scripted). maude design init --no-discovery scaffolds a neutral skeleton you finish by hand later.

Path 1. Inside Claude Code

> /design:setup-ds project "team scouting + match-day pro tool for amateur clubs"

What happens:

1. Onboard runs first (if .design/config.json is missing). /design:init does dependency pre-flight (Node 20+, git), writes a skeleton config with empty designSystems: [], and prints install hints for soft deps (agent-browser, maude, CLAUDE.md / .ai/ recommendations).
2. Skill design-system loads in bootstrap mode. It detects first-bootstrap (no DS yet) and runs 3-stage discovery (DDR-033): Stage 1 — Vision (free-text prose prompts about product, audience, mood, and voice — no brand-name option ladders to bias you), Stage 2 — Research (the ux-research-agent builds a domain reference pool from the web and returns per-decision recommendations with confidence), Stage 3 — Refinement (a short AskUserQuestion round, but only where research is uncertain).
3. Direction confirmation. The skill echoes a two-sentence proposed direction. You say yes or correct it.
4. Mapping to file set. The skill consults _MAPPING.md to compute which specimens to scaffold based on the discovery answers. A consumer marketing site gets ~12 specimens, a pro-tool with multiplayer gets ~22.
5. Generation. Tokens are derived from the brand color (OKLCH-converted, with hover / active / fg auto-computed). The README, SKILL.md, INDEX, and config are generated from .tpl templates. Each specimen is generated fresh using the inspiration library as reference, not copied verbatim, never with placeholder copy.
6. Post-scaffold critic panel runs. The design-system-completeness-critic checks 3-tier rules (Core blocker / Conventional warning / Free-form acknowledged) calibrated by completenessProfile, alongside a11y and signature-moment critics. The scaffold completes when there are no blockers and the aspiration score clears the silent-pass bar (≥ 4.0, DDR-057); a 3.0–4.0 "nice but not wow" score still completes but surfaces the signature-moment-critic's top-2 lifts.
7. Next steps printed.

Alternative entries (all triggered transparently):

• /design:edit "<feedback>" against a fresh repo. Skill design-system auto-loads in bootstrap mode with the feedback as the Q1 product one-liner.
• /design:new "<Name>" "<brief>" against a fresh repo. Same auto-bootstrap with $BRIEF as Q1, then the canvas creation proceeds with the freshly-scaffolded tokens.

Path 2. From the terminal

For CI, scripted setup, or "just give me a starting point I'll edit by hand":

cd /path/to/repo
maude design init --no-discovery --name acme

Produces the Core file set (~19 files) as a neutral skeleton:

.design/
├── README.md
├── INDEX.md
├── config.json
└── system/project/
    ├── README.md
    ├── SKILL.md
    ├── colors_and_type.css
    └── preview/
        ├── _layout.css
        ├── _components.css
        ├── colors-text.html
        ├── colors-surfaces.html
        ├── colors-accent.html
        ├── type-scale.html
        ├── spacing-scale.html
        ├── motion.tsx          # + motion.css + _motion-readme.md
        ├── components-buttons.html
        ├── components-cards.html
        └── components-inputs.html

After the Core scaffold, open Claude Code and run /design:setup-ds project "<one-line product brief>" --force to re-run with the full 3-stage discovery. You'll get a richer, project-flavored result.

Adding a second design system

Multi-DS opt-in (e.g., a marketing DS sibling to your admin DS):

> /design:setup-ds marketing "consumer-facing marketing site for product launch"

The skill detects additional-ds mode (config exists, marketing not in designSystems[]), runs the same 3-stage discovery plus a Q_purpose prompt up front and an inheritance picker between research and refinement, and scaffolds system/marketing/ alongside the existing DS. Subsequent /design:new --ds=marketing "<Name>" "<brief>" creates canvases scoped to that DS.

See Multi-DS for the full multi-DS workflow.

Re-bootstrapping

To rerun discovery on an existing DS (after a product pivot, brand refresh, etc.):

> /design:setup-ds project --force

The skill detects re-bootstrap mode, lossy-infers Stage 1 (Vision) from the existing DS (README + tokens + layout), and you confirm or correct it in one pass; Stage 2 (Research) always re-runs. Changed answers re-generate the affected files. Without --force, the command refuses with a list of safer alternatives (/design:edit for incremental, /design:setup-ds <new-name> for a sibling DS).

What the bootstrap produces

Browse them: maude design serve, then http://localhost:4399.