sddesign

Context: this sub-skill is one lens of the broader

ui-craft

skill. If the

ui-craft

skill is also installed, read its SKILL.md first for Discovery + Anti-Slop + Craft Test, then apply the specific lens below.

Run the spec-driven design pipeline for

$ARGUMENTS

. Load the

ui-craft

skill.

ORCHESTRATE-ONLY RULE

This command sequences existing phase commands. It MUST NOT re-implement or duplicate any logic from them. Every composition rule, wireframe algorithm, craft rule, and convergence engine lives in the phase commands. This command contributes only:

Gate detection (does the artifact exist?)
Offer prompts (run phase X or skip?)
Progress reporting (the checklist)
Degraded-mode honesty (what was skipped and what that costs)

When in doubt: call the phase command, don't inline its steps.

Progress Checklist

Print this at the start and update it after each gate resolves:

[ ] brief   [ ] tokens   [ ] shape (spec)   [ ] craft (build)   [ ] converge   [ ] ship

Use

[✓]

for completed/skipped-with-artifact,

[>]

for the current gate,

[–]

for skipped-without-artifact (degraded).

Pipeline Gates

Gate 1 — Brief

Check: does

.ui-craft/brief.md

exist?

If yes: mark

[✓] brief

. Note that brief §6 learned constraints and the a11y/correctness floor are in effect for all downstream gates — they take precedence over any spec.md composition choice.

If no: offer to run

/brief

now.

User confirms → run
```
/brief
```
. When it completes, mark
```
[✓] brief
```
.
User declines → mark
```
[–] brief
```
. Note downstream impact: "no brief → craft will use skill defaults; composition will not be anchored to project principles."

Gate 2 — Tokens

Check: does a token spine exist? (Look for CSS variables

--color-*

--font-*

--accent-*

, a Tailwind

theme.extend

with tokens, or a token file.)

If yes: mark

[✓] tokens

If no: offer to run

/tokens

now.

User confirms → run
```
/tokens
```
. When it completes, mark
```
[✓] tokens
```
.
User declines → mark
```
[–] tokens
```
. Note downstream impact: "no token spine → craft will establish a minimal inline token set; it won't match an existing system."

Gate 3 — Shape (spec)

Existing-surface guard: Before running

/shape

, check if

.ui-craft/spec.md

already contains a

## Surface: <name>

block for this surface. If it does, do NOT re-run shape and blindly append a duplicate section — offer to update the existing section or skip shape (the spec already exists).

Run

/shape

for the surface described in

$ARGUMENTS

. Shape produces its full five-step output (content inventory, ASCII layout, state list, open questions).

Persist in pipeline (default): Inside the

/sddesign

pipeline, shape's Step 6 spec persist is the default — it is auto-confirmed unless the user explicitly opts out of the spec gate. The persist writes

.ui-craft/spec.md

(or appends the surface section). This is the whole point of the pipeline.

Persist completes →
```
.ui-craft/spec.md
```
is written (or the surface section is appended). Mark
```
[✓] shape (spec)
```
.
User explicitly opts out of persist → mark
```
[–] shape (spec, unsaved)
```
. Note downstream impact: "no spec.md → craft (build) will build against shape's printed output; acceptance bar will not be persisted."

Gate 4 — Craft (build)

Run

/craft <surface>

where

<surface>

matches the description in

$ARGUMENTS

/craft

declares the Craft Read (

references/craft-intent.md

) before building — surface kind, audience, theme/accent, DESIGN_VARIANCE, and the one signature bet. The signature bet is built inside this gate, not deferred to converge or polish. If the spec section names a composition, the Craft Read must be consistent with it.

/craft

loads

.ui-craft/spec.md

before building. If

[✓] shape (spec)

was set, the spec's chosen composition, component inventory, state lattice, and acceptance bar take precedence over recipe defaults — every acceptance bar item from the spec must be green before craft reports done.

[–] shape (spec, unsaved)

, craft builds against the shape output printed to the terminal. Note in the checklist.

Mark

[✓] craft (build)

when the build completes.

Gate 5 — Converge

Run the

visual-anti-slop

preset from

../skills/ui-craft/references/loops.md

. This iterates — evaluate → fix one → re-evaluate — until the zero-critical gate passes or the budget is exhausted (default budget: 3 iterations).

If the loop gate passes (zero critical findings) → mark
```
[✓] converge
```
.
If budget exhausted with open findings → mark
```
[>] converge (open findings)
```
. List unresolved findings from the loop report.

Gate 6 — Ship

Run

/finalize

verdict. Finalize reports READY / NOT READY / BLOCKED based on the 10-pass finish bar and the brief/token gate.

Print the final verdict and the complete resolved checklist:

[✓] brief   [✓] tokens   [✓] shape (spec)   [✓] craft (build)   [✓] converge   [✓] ship

Degraded-mode honesty. If any gate was marked

[–]

, list them in the ship verdict with their downstream impacts:

"Skipped gates: tokens (skipped) → token spine not validated; shape (spec, unsaved) → acceptance bar not persisted. These gaps reduce the ship verdict's confidence."

Precedence

Brief §6 learned constraints and the a11y/correctness floor take precedence over spec.md composition choices at every gate. If a constraint conflicts with a spec.md decision, the constraint wins — update the spec section to reflect the winning choice and note the brief §6 reference.

Next step: Ship. The pipeline already walked rungs 1 to 3;

.ui-craft/spec.md

is the record for the next session.