4918c62d76
* test(#2845): failing-first suite for UI-SPEC inventory provenance Binds two shared formats before either exists, so the suite is RED against next: the gsd-ui-checker dimension roster (asserted independently on twelve surfaces, eight English and four translated) and the provenance-line grammar the UI-SPEC template emits and Dimension 7 consumes. Every parity assertion is paired with a synthetic mutation case, so the guard's failure branch executes rather than only reading a correct tree: limit-1 (a surface still declaring 6), limit (7), limit+1 (8), a dropped dimension, a label that drifts on one surface only, a non-contiguous roster, a duplicated number, and a surface that stops declaring a count at all. A seeded fast-check property renders the roster under formatting noise (CRLF, padding, interleaved sections) and asserts the parse round-trips and is strictly sensitive to a dropped heading. Assertions are on parsed typed records, never raw substrings. * docs: normalize design-a-ui-phase how-to to American English House style for docs/ is American English (CLAUDE.md). This file carried colour/initialisation/initialise/artefact throughout. Spelling only — no content change; kept separate from the #2845 feature commit so the release-notes classifier and the hotfix cherry-pick filter see it for what it is. * feat(#2845): require provenance for UI-SPEC component inventories A UI-SPEC's component inventory was treated downstream as a closed allowlist while the document recorded nothing about whether the list had been enumerated from the installed design system or recalled from memory. A recalled inventory is indistinguishable from an enumerated one, so an executor complying with the spec builds against a fraction of what the package offers, and every gate stays green because they assert semantics rather than composition. The UI-SPEC template gains a Component Inventory slot carrying one of two provenance lines: the command that enumerated the list, the count it returned, the resolved package@version and the date; or a Could not enumerate record with a real reason. gsd-ui-researcher gains an enumeration ladder and must record the line rather than write the list from recall. gsd-ui-checker gains Dimension 7. An inventory with no provenance line, a count with no command, an empty could-not-enumerate reason, or a line still carrying the template's unfilled placeholders BLOCKs; a partial line, a line placed below its table, or an honest negative record FLAGs; a complete line passes, and so does a spec carrying no inventory at all, which keeps every UI-SPEC predating the dimension validating unchanged. Whatever the verdict, an unsourced inventory is reported as a non-exhaustive list of known-good components rather than a closed allowlist, so the executor is never blocked from a component the spec merely failed to mention. The checker never runs the recorded command. The dimension count moved on all thirteen surfaces that assert it, across five languages. Also corrects the claim in the English, Korean and Portuguese how-tos that this checker applies a scored six-pillar rubric — that rubric belongs to /gsd-ui-review's retroactive audit. * chore(#2845): backfill changeset pr number to 3745 --------- Co-authored-by: sim <sim@local>
9.9 KiB
How to design a UI phase
Goal: Produce a locked UI design contract (UI-SPEC.md) that fixes spacing, color, typography, and copywriting decisions before the planner writes tasks, preventing visual inconsistency caused by ad-hoc styling choices during execution.
Prerequisites: .planning/ROADMAP.md exists. The phase must have frontend or UI work. Running /gsd-discuss-phase N first is strongly recommended — the UI researcher reads CONTEXT.md to avoid re-asking decisions you have already made.
Decide whether this phase needs a UI contract
Not all phases need /gsd-ui-phase. Use it when:
- The phase introduces new UI surfaces (pages, flows, layouts)
- Multiple components will be built and visual consistency matters
- You are starting a new project's frontend and need a design system baseline
- You are adding significant UI work to an existing project and want to lock tokens, spacing, and color before execution
Skip it when:
- The phase is purely backend, infrastructure, or data work with no user-facing output
- A UI-SPEC.md already exists for an earlier phase and this phase builds on identical visual patterns without introducing new surfaces
If you are unsure, the safety gate will prompt you: when workflow.ui_safety_gate is enabled (default), /gsd-plan-phase warns when it detects frontend work but no UI-SPEC.md and asks whether to run /gsd-ui-phase first.
Run the UI design contract
/gsd-ui-phase 2
If no phase number is given, GSD Core targets the current phase.
The command runs in two stages:
gsd-ui-researcher— readsCONTEXT.md,RESEARCH.md, andREQUIREMENTS.mdfor existing decisions, detects the design system state (shadcncomponents.json, Tailwind config, existing tokens), and asks only the unanswered design questions across five areas: spacing, color, typography, copywriting, and registry safety.gsd-ui-checker— validates the resultingUI-SPEC.mdacross seven dimensions. If issues are found, a revision loop reruns the researcher (up to two iterations) targeting only the flagged items.
Output: {padded_phase}-UI-SPEC.md in .planning/phases/{phase-dir}/.
What the UI-SPEC covers
The researcher locks decisions across five areas:
| Area | Examples |
|---|---|
| Spacing | Base scale (4px or 8px), grid alignment, component padding |
| Color | Primary, accent, neutral palette; 60/30/10 rule; dark-mode considerations |
| Typography | Font families, size/weight scale constraints, heading hierarchy |
| Copywriting | CTA labels, empty state messages, error state copy, loading indicators |
| Registry safety | shadcn component inspection protocol (see below) |
| Component inventory | What the design system actually provides, plus the command that enumerated it (see below) |
The checker validates the spec against its seven dimensions — Copywriting, Visuals, Color, Typography, Spacing, Registry Safety, and Inventory Provenance — returning PASS, FLAG or BLOCK for each. (The scored 1–4 six-pillar rubric belongs to /gsd-ui-review's retroactive audit, not to this checker.)
shadcn initialization
For React, Next.js, and Vite projects, the researcher offers to initialize shadcn if no components.json is found. The flow:
- Visit
ui.shadcn.com/createand configure your preset (colors, border radius, fonts) - Copy the preset string
- Run:
npx shadcn init --preset <paste>
The preset string becomes a first-class GSD Core planning artifact that is reproducible across phases and milestones.
Registry safety gate
Third-party shadcn registries can inject arbitrary code. When workflow.ui_safety_gate is enabled (default), the spec requires these steps before installing any non-official component:
npx shadcn view <component> # inspect source before installing
npx shadcn diff <component> # compare against the official registry
The checker will flag the spec as BLOCKED if registry safety is not addressed. Disable the gate via /gsd-settings if your project does not use shadcn or you have an alternative vetting process.
Record where the component inventory came from
If your project has a design system, the UI-SPEC lists the components it provides — and the
planner and executor read that list as the design surface they are allowed to build from. A list
written from the model's recall looks identical to one enumerated from the installed package, so
gsd-ui-checker Dimension 7 requires the spec to say which it was.
The section carries one provenance line, directly above its table:
Enumerated by `npx shadcn info --json` — 153 components — @acme/design-system@4.2.1 — 2026-08-21.
Four things are required, and each is there for a reason:
| Part | Why it is required |
|---|---|
| The command | The only re-runnable part. A reader can check the claim without re-deriving it. |
| The count | Makes an under-listed inventory visible at a glance — "13 components" against a package reporting 153 is a difference you can see. |
<package>@<version> |
The resolved installed version, so a spec reused after an upgrade is visibly stale. A caret range from package.json does not do this. |
| The date | Bounds how old the claim is. |
Use whatever the design system provides — a first-party CLI with a JSON mode, an MCP tool, or the installed package's own metadata:
npx shadcn info # shadcn projects
node -p "Object.keys(require('@acme/design-system/package.json').exports).length"
node -p "require('@acme/design-system/package.json').version" # resolved version
If nothing can enumerate it, record that in the same slot instead, with a real reason:
Could not enumerate: package ships no exports map and no CLI.
What the checker does with it
| What the spec carries | Dimension 7 | What it means for the executor |
|---|---|---|
| Command, count, version, date | PASS | Sourced list. |
| Command and count, no version or date | FLAG | Accepted, but staleness is invisible. Add the missing part. |
| A complete line, but below the table instead of above it | FLAG | Accepted. Move it up — a caveat has to be read before the list it qualifies. |
Could not enumerate: <reason> |
FLAG | Honest and accepted. The list is explicitly non-exhaustive. |
| An inventory with no provenance line | BLOCK | Enumerate and re-run /gsd-ui-phase. |
A count with no command, or a bare Could not enumerate: |
BLOCK | Nothing falsifiable was recorded. |
| No inventory section at all | PASS | Not applicable — including every spec written before this dimension existed, and any project with Tool: none. Nothing to enumerate is not a defect. |
A missing provenance line never blocks the executor. The checker reports it against the spec and downgrades the list to a non-exhaustive set of known-good components — so nothing stops you using a component the spec simply failed to mention. Reaching for one outside the table is the expected path, not an exception.
The checker never runs the recorded command. It reads the spec as a document; executing a command string lifted out of one would be a code-execution path through untrusted text.
Use sketch findings as a head start
If you have already run /gsd-sketch --wrap-up, the UI researcher loads .claude/skills/sketch-findings-[project]/ automatically. Pre-validated decisions (layout, palette, typography, spacing) are treated as locked — the researcher does not re-ask them. You see a note at the start of the run:
⚡ Sketch findings detected: .claude/skills/sketch-findings-[project]/SKILL.md
Pre-validated decisions (layout, palette, typography, spacing) should be treated
as locked — not re-asked.
This is the main reason to run /gsd-sketch --wrap-up before /gsd-ui-phase: it turns the conversational design exploration into binding contract input.
Retroactive visual audit with /gsd-ui-review
/gsd-ui-review runs after execution, not before. Use it to audit the implemented frontend against the UI-SPEC (or against abstract 6-pillar standards when no spec exists).
/gsd-ui-review # audit the current phase
/gsd-ui-review 3 # audit phase 3 specifically
It works on any project with frontend code — GSD project initialization is not required.
What it checks (6 pillars, scored 1–4 each):
- Copywriting — CTA labels, empty states, error states
- Visuals — focal points, visual hierarchy, icon accessibility
- Color — accent usage discipline, 60/30/10 compliance
- Typography — font size and weight constraint adherence
- Spacing — grid alignment, token consistency
- Experience Design — loading, error, and empty state coverage
Output: {padded_phase}-UI-REVIEW.md with scores and top three priority fixes. When a browser MCP server such as gsd-browser is configured, the audit also captures screenshots with visual evidence.
Screenshot storage: Screenshots are saved to .planning/ui-reviews/. A .gitignore is created automatically to prevent binary files from reaching git. Screenshots are cleaned up during /gsd-complete-milestone.
Recommended position in the phase lifecycle
/gsd-discuss-phase N ← lock implementation preferences
/gsd-ui-phase N ← lock design contract (frontend phases)
/gsd-plan-phase N ← research + plan (reads UI-SPEC.md as context)
/gsd-execute-phase N ← parallel execution
/gsd-verify-work N ← manual UAT
/gsd-ui-review N ← retroactive visual audit (optional but recommended)
/gsd-ui-phase sits between discuss and plan because the planner reads UI-SPEC.md as design context — tasks in PLAN.md reference spacing tokens, color variables, and copywriting decisions that the spec locked.