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>
148 lines
4.7 KiB
Markdown
148 lines
4.7 KiB
Markdown
---
|
|
phase: {N}
|
|
slug: {phase-slug}
|
|
status: draft
|
|
shadcn_initialized: false
|
|
preset: none
|
|
created: {date}
|
|
---
|
|
|
|
# Phase {N} — UI Design Contract
|
|
|
|
> Visual and interaction contract for frontend phases. Generated by gsd-ui-researcher, verified by gsd-ui-checker.
|
|
|
|
---
|
|
|
|
## Design System
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| Tool | {shadcn / none} |
|
|
| Preset | {preset string or "not applicable"} |
|
|
| Component library | {radix / base-ui / none} |
|
|
| Icon library | {library} |
|
|
| Font | {font} |
|
|
|
|
---
|
|
|
|
## Component Inventory
|
|
|
|
> What the project's design system actually provides. **Enumerate this from the installed
|
|
> package — never from recall.** Delete whichever provenance line below does not apply.
|
|
|
|
Enumerated by `<command>` — <N> components — <package>@<version> — <YYYY-MM-DD>.
|
|
Could not enumerate: <reason>.
|
|
|
|
Without a provenance line this table is a **non-exhaustive** list of known-good components and
|
|
never a closed allowlist — the executor may use anything the design system exports, and
|
|
`gsd-ui-checker` Dimension 7 reports the missing line as a defect. Checking for a component
|
|
outside the table is the expected path, not an exception.
|
|
|
|
| Component | Import path | Notes |
|
|
|-----------|-------------|-------|
|
|
| {name} | {import path} | {when to reach for it} |
|
|
|
|
Omit this section entirely when the project has no design system (`Tool: none`).
|
|
|
|
---
|
|
|
|
## Spacing Scale
|
|
|
|
Declared values (must be multiples of 4):
|
|
|
|
| Token | Value | Usage |
|
|
|-------|-------|-------|
|
|
| xs | 4px | Icon gaps, inline padding |
|
|
| sm | 8px | Compact element spacing |
|
|
| md | 16px | Default element spacing |
|
|
| lg | 24px | Section padding |
|
|
| xl | 32px | Layout gaps |
|
|
| 2xl | 48px | Major section breaks |
|
|
| 3xl | 64px | Page-level spacing |
|
|
|
|
Exceptions: {list any, or "none"}
|
|
|
|
---
|
|
|
|
## Typography
|
|
|
|
| Role | Size | Weight | Line Height |
|
|
|------|------|--------|-------------|
|
|
| Body | {px} | {weight} | {ratio} |
|
|
| Label | {px} | {weight} | {ratio} |
|
|
| Heading | {px} | {weight} | {ratio} |
|
|
| Display | {px} | {weight} | {ratio} |
|
|
|
|
---
|
|
|
|
## Color
|
|
|
|
| Role | Value | Usage |
|
|
|------|-------|-------|
|
|
| Dominant (60%) | {hex} | Background, surfaces |
|
|
| Secondary (30%) | {hex} | Cards, sidebar, nav |
|
|
| Accent (10%) | {hex} | {list specific elements only} |
|
|
| Destructive | {hex} | Destructive actions only |
|
|
|
|
Accent reserved for: {explicit list — never "all interactive elements"}
|
|
|
|
---
|
|
|
|
## Copywriting Contract
|
|
|
|
| Element | Copy |
|
|
|---------|------|
|
|
| Primary CTA | {specific verb + noun} |
|
|
| Empty state heading | {copy} |
|
|
| Empty state body | {copy + next step} |
|
|
| Error state | {problem + solution path} |
|
|
| Destructive confirmation | {action name}: {confirmation copy} |
|
|
|
|
---
|
|
|
|
## UI Considerations
|
|
|
|
> Populated by the ui-phase UI-consideration probe (Step 9.5) and lifted by plan-phase's
|
|
> `## UI Considerations` lift rule via the identical rule as SPEC `## Edge Coverage`. Shape-rooted UI *state*
|
|
> coverage (empty / loading / error / populated / partial / overflow / zero-one-many / long-text).
|
|
> Empty-state and error-state COPY live in `## Copywriting Contract` above — this section covers
|
|
> state coverage and REFERENCES those rows rather than restating the copy (de-dup).
|
|
|
|
Applicable state considerations resolved: {N covered, M backstop, K unresolved — or "none applicable"}
|
|
|
|
| Category | Element(s) | Status | Resolution / Reason |
|
|
|----------|------------|--------|---------------------|
|
|
| {empty} | {list-collection} | ✅ covered | {concrete truth string — e.g. "Empty results render the documented 'No results' copy"} |
|
|
| {long-text} | {static-content} | 🧪 backstop | {held-out/visual UI-state test — lifts as `{ statement, verification: backstop }`} |
|
|
| {overflow} | {list-collection} | ⚠ unresolved | {planner treats as assumption} |
|
|
|
|
<!-- Status vocabulary (locked by probe-core projectTruths):
|
|
✅ covered → a plain truth string lifted into must_haves.truths
|
|
🧪 backstop → a flat scalar { statement, verification: backstop }; at verify time, no explicit
|
|
evidence → insufficient_spec → human_needed (never a silent pass, #1154)
|
|
⚠ unresolved → an explicit planner assumption (surfaced, never silently dropped)
|
|
Rows are REPLACED (not appended) on a probe re-run — idempotent. -->
|
|
|
|
---
|
|
|
|
## Registry Safety
|
|
|
|
| Registry | Blocks Used | Safety Gate |
|
|
|----------|-------------|-------------|
|
|
| shadcn official | {list} | not required |
|
|
| {third-party name} | {list} | shadcn view + diff required |
|
|
|
|
---
|
|
|
|
## Checker Sign-Off
|
|
|
|
- [ ] Dimension 1 Copywriting: PASS
|
|
- [ ] Dimension 2 Visuals: PASS
|
|
- [ ] Dimension 3 Color: PASS
|
|
- [ ] Dimension 4 Typography: PASS
|
|
- [ ] Dimension 5 Spacing: PASS
|
|
- [ ] Dimension 6 Registry Safety: PASS
|
|
- [ ] Dimension 7 Inventory Provenance: PASS
|
|
|
|
**Approval:** {pending / approved YYYY-MM-DD}
|