koroqe/claude-code-sdlc/design-foundation

Command: Design Foundation

Generate .claude/rules/design.md — the project's design declaration. The harness ships the frame; this skill derives the project's own taste from its subject and writes it down, so every later UI slice extends one declared system instead of improvising a new one.

Arguments

$focus (also available as $ARGUMENTS) optionally names a surface, route, or area to prioritize during grounding. When absent, ground the whole product.

Invocation Context (determine FIRST)

Two paths reach this skill, and they differ in exactly one behavior:

• Standalone / interactive — the developer invoked /design-foundation directly. AskUserQuestion is available for grounding gaps.
• Unattended — triggered from `/bootstrap-feature` — the pipeline reached this skill mid-run with nobody watching. Never call `AskUserQuestion` here, and never stall waiting for an answer. Degrade to best-effort inference from the repository, and for anything that cannot be inferred write an explicitly labeled placeholder into the generated file — e.g. TODO(design-foundation): confirm the primary audience. An unattended run always completes.

If the invocation path cannot be positively determined, treat the run as unattended — ambiguity resolves to the path that cannot stall.

Process

1. Subject Grounding

Read the repository before asking anyone anything:

• the package/app manifest and README — what the product is and claims to do
• routes, page/screen files, navigation — the key surfaces
• user-facing copy — who the audience is and what register the product speaks in

From these, state: the concrete product, its audience, and, for each key surface, the single job that surface does. The subject's own world — its materials, instruments, vernacular — is where distinctive design choices come from; a generic template is where they go to die.

Ask via AskUserQuestion ONLY what cannot be inferred from the repository, and ONLY on the standalone path (see Invocation Context). Never ask a question the repository already answers.

2. Token Derivation

Derive a compact system, every token named and justified by the grounding:

• Colors: 4-6 named colors. A dominant color plus one sharp accent beats a timid, evenly-spread palette.
• Typography: at least 2 font roles (e.g. heading/body, or sans/mono), each with a real fallback stack ending in a generic family — never a bare single font name.
• Motion: duration and easing tokens — a small named scale, not ad hoc per-animation values.
• Spacing: one spacing basis (a base unit or scale) that layouts multiply.
• Signature: one signature element — the single recognizable move that belongs to this product and no other.

Existing tokens are the source of truth. When the project already declares tokens — a globals.css, a Tailwind theme/config, a design-tokens file — document THOSE as the system and extend only where a genuine gap exists; inventing a parallel system beside them is a defect, not a contribution. Where existing UI is generic, record that as a finding in the report; do not touch application code — the only file this skill writes is .claude/rules/design.md.

3. Self-Check Pass

For every derived choice, ask: would this choice fit any similar product equally well? If yes, it is a default, not a decision — revise it until it could only belong to this subject, and state in the report what this pass changed and why. This is a judgment test, not a ban-list: no specific color or font is forbidden; interchangeability is the defect.

4. Write the Declaration

Write .claude/rules/design.md respecting the template's section shape (mirrored from the harness's templates/rules/design.md): Design System Source of Truth, Component Library, Typography, Motion Tokens, Aesthetic Direction, the optional project-authored Ban-List, Preview, and the optional AI Interface Patterns section (pattern vocabulary only, never code). Fill what grounding and derivation produced; leave what only the project can supply — the ## Preview launch command above all — as a labeled TODO scaffold rather than a guess.

Re-run on an existing `design.md`: read the existing file first, then write the complete revised file — carrying forward every retained section — and report the delta: what was added, what changed, what was kept. Never silently overwrite an existing declaration.

Close with a short report: the grounding (product, audience, surface jobs), the derived tokens with one-line justifications, what the self-check changed, and any findings (generic existing UI, gaps left as TODO).

Rules

• Every example in the generated file is generic or invented — never name a real product, brand, or company as a reference.
• Everything derives from the repository and, on the interactive path, the developer's answers; fetch nothing from any external service.
• The single write target is .claude/rules/design.md. Application code, docs, and configs are read, never modified.