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 with Recommended defaults.

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 an 8-question discovery split across two AskUserQuestion rounds. Identity (audience, platforms, theme) plus brand (mood references, brand color, typography, content tone).
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. Completeness-critic auto-runs. 3-tier rules (Core blocker / Conventional warning / Free-form acknowledged) calibrated by completenessProfile. The scaffold completes when there are no blockers.
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 ~16 files using Recommended defaults:

.design/
├── README.md
├── INDEX.md
├── config.json
└── system/project/
    ├── README.md
    ├── SKILL.md
    ├── colors_and_type.css
    └── preview/
        ├── _layout.css
        ├── colors-text.html
        ├── colors-surfaces.html
        ├── colors-accent.html
        ├── type-scale.html
        ├── spacing-scale.html
        ├── motion.html
        ├── 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 8-question 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 reduced discovery (7 Qs + Q_purpose + an inheritance picker), 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 and pre-fills all 8 questions with the current values. Hit enter to keep each, or change to 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.