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>
5.3 KiB
UI-Consideration Probe — Spec-Completeness Reference
The third adapter of the shared probe-core resolution model (ADR-550 Decision 7), on
the UI element/state axis. It surfaces the shape-rooted UI state considerations a
UI-SPEC must resolve before a dimension may PASS — the visual analog of the requirement-side
edge-probe, reusing its exact lifecycle, validators, and plan-phase lift
(see edge-probe.md for the shared status×verification model — this doc does not re-argue it).
Axis boundary (this is a MIXED axis). This compiled taxonomy covers ONLY the finite, project-independent shape-rooted content/robustness states. The open, domain/UX-dependent considerations — real-time/offline/optimistic-UI, deep accessibility (WCAG breadth), internationalization / RTL depth, and emerging interaction paradigms — are open-ended and are prose-owned in the companion domain-probes.md technology/UX bank, NOT here. Forcing them into a closed compiled taxonomy is the wrong model.
Inputs
A list of UI elements, each a { id, text, elements? } record where text is the
researcher-authored description and elements is an optional author-supplied override of the
element classification. The six element kinds are: form, list-collection, nav, media,
interactive-control, static-content. When elements is absent, a heuristic classifier
proposes kinds from the prose (propose-then-confirm) — the author may correct the kind.
Taxonomy (8 categories)
Closed and small by design: the finite, project-independent content/robustness states every
UI surface must account for. Growth toward open UX topics happens in domain-probes.md, not by
bloating this closed core.
| id | name | applies to element kinds | consideration question |
|---|---|---|---|
| empty | Empty / no data | form, list-collection, media | What is shown when there is no data — zero items, an unfilled form, or absent media? |
| loading | Loading / in-flight | form, list-collection, media, nav, interactive-control | What is shown while data or content is still loading (skeleton, spinner, progressive reveal)? |
| error | Error / failure | form, list-collection, media, nav, interactive-control | What is shown when the load or submit fails (message, retry affordance, partial fallback)? |
| populated | Populated / happy path | list-collection, media | What does the normal populated (happy-path) state look like at a typical volume of content? |
| partial | Partial / incomplete | form, list-collection | What is shown for partial or incomplete data — some fields or rows present, others missing? |
| overflow | Overflow / truncation | list-collection, nav, static-content | What happens when content exceeds its container — scroll, clip, wrap, or truncate? |
| zero-one-many | Zero / one / many | list-collection | How does the layout read at zero, one, and many items (singular vs plural copy, spacing)? |
| long-text | Long text | form, static-content, interactive-control, nav | What happens with unusually long text — truncation, wrapping, ellipsis, or reflow? |
Relevance filter + resolution states
The probe reuses the edge-probe rails verbatim (ADR-550 Decision 7 — see edge-probe.md for the full model):
- Relevance filter first. Classify each element's kind(s), then raise only the categories
whose
applies to element kindsintersect. A static label is never asked about loading or empty state — that is what makes an unresolved consideration meaningful. - Dismissal requires a reason string. Silence is not a resolution; the reason is the audit trail.
- Zero-classification surfaces one
unclassifiedcandidate (#1110). An element whose prose matched no kind cue yields exactly one softunclassified — review manuallyitem (category: "unclassified",status: "unresolved") — never a silent drop, never a guessed kind.unclassifiedis a review signal, not a ninth taxonomy category; an explicitelements: []opt-out stays silent.
Each raised consideration carries the shared two orthogonal axes — status
(resolved | dismissed | unresolved) and, when resolved, a verification tier
(explicit | backstop). A backstop consideration lifts into must_haves.truths and, at
verify time, is confirmed only by explicit evidence (a wired held-out/property test) or routes
to insufficient_spec → human_needed — never a silent pass (the honest-verifier disposition,
#1154). See honest-verifier.md.
Closed / open boundary
The 8 ids above are the closed, compiled subset — finite and project-independent, so a
compiled taxonomy is legitimate (the same property that makes edge-probe's data-shape taxonomy
closed). The open subset is prose-owned in domain-probes.md:
real-time/offline/optimistic-UI, deep accessibility (WCAG breadth), i18n / RTL depth, and
emerging interaction paradigms (gesture/voice/reduced-motion/print) are open-ended and
cue-triggered — they do not belong in this closed taxonomy. This probe complements the
gsd-ui-checker seven quality dimensions (it adds a state-coverage axis); it does not change the
BLOCK/FLAG/PASS enum or the dimensions themselves.