Add Design Intent Governance#1
Merged
Merged
Conversation
Fill the previously empty `spec/features/design-intent-governance/` slot with `REQ-DESIGN-GOV-001..007`. The spec defines: - story-class classification (user/system/mixed/method) at file-level default and per-REQ override. - intent-to-UI design translation as the bridge between accepted intent and concrete UI properties (region → element → variant → property). - `governingSpec:` frontmatter on translations as the coupling authority. - trail vs authority separation for external design references (design systems, code-path catalogs, mockup indexes) — trails follow spec. - `design_translation_gap` and `design_trail_authority_drift` review labels. Add `templates/user-design-translation.md` with the 9-section structure projects fill per surface. Add a small worked example under `examples/design-intent-translation/` (coupon-checkout review surface) that demonstrates file-level storyClass, per-REQ override, paired translation with governingSpec, and property fit matrix with drift-source classification. Index the new feature in `spec/README.md`. Field-validated by a real-world adoption in 2026-05 (multi-role consumer mobile app, 22 feature specs classified, 14 translations written, coupling check in CI).
Add `guide/intent-to-ui-translation.md` — the conceptual companion to the design-intent-governance spec. It explains: - Where design translation sits in the ILS layer model (after L0/L1/L2/L3, before code+evidence). - Story-class classification with file-default + per-REQ override. - The UI object tree shape (surface/story → region → element → variant → property) and why measurement happens at the property leaf. - Property fit judgments (fit / weak / drift / violation / not_applicable). - Drift source classification (wrong_intent / missing_intent / weak_translation / wrong_implementation / missing_evidence / decision_gap) aligned with the existing implementation gap taxonomy from `guide/spec-as-product-standard.md`. - Authority vs trail distinction for external design references. - The pairing rule: design translation changes must be paired with a governingSpec change OR a `noIntentChange: true` commit marker. - Adoption order — story-class metadata first, then highest-risk surface translation, then coupling check in CI. Index it in `AGENTS.md` load order (item 9, for tasks touching user-facing surfaces) and in `README.md` resource list. Record the addition in `ROADMAP.md` 0.3 milestone and `CHANGELOG.md` Unreleased section.
Enforce `REQ-DESIGN-GOV-004` and `REQ-DESIGN-GOV-005` programmatically:
when a hand-authored design translation under the configured translations
directory changes, the diff must include either (a) a change in at least one
of its declared `governingSpec:` files, or (b) a commit message in the same
PR carrying `noIntentChange: true`. Otherwise the check fails with a
`design_translation_gap` report naming the missing pairing.
Translation directory resolution (in order of precedence):
1. `--dir=<path>` CLI flag
2. `DESIGN_TRANSLATIONS_DIR` environment variable
3. Auto-detect from four conventional paths
(`docs/design/translations`, `docs/design/v3/governance/translations`,
`docs/translations`, `design/translations`)
4. No-op exit when no translations directory exists (REQ-DESIGN-GOV-005
does not apply to projects without user-facing design translations)
The check also honors `BASE_REF` and `GITHUB_BASE_REF` so it integrates
cleanly with GitHub Actions PR workflows without configuration.
Wire it into the project `check` aggregate. Regenerate requirement test
stubs and verification report so design-intent-governance REQs appear in
generated artifacts.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Land Design Intent Governance — the previously empty
spec/features/design-intent-governance/slot — as a complete additioncovering spec, guide, template, example, and enforcement script.
Three commits, one PR:
REQ-DESIGN-GOV-001..007,templates/user-design-translation.md,examples/design-intent-translation/.guide/intent-to-ui-translation.md, AGENTS.md / README.md /ROADMAP.md / CHANGELOG.md updates.
scripts/check-design-spec-coupling.mjswired intonpm run check.What this addresses
ILS previously stopped at backend-style governance (L0/L1/L2/L3 + evidence
boundary). It had no story for how accepted intent connects to concrete UI
properties on user-facing surfaces, and the
spec/features/design-intent-governance/slot was reserved but empty.This PR fills that gap with method-level guidance and an enforceable
guardrail, validated by a real-world adoption in 2026-05 (a multi-role
consumer mobile app: 22 feature specs classified by story class, 14
hand-authored design translations, the coupling check enforced in CI).
Concepts introduced
user/system/mixed/method) at file-leveldefault with per-REQ override, so a single feature file can mix user and
system REQs without misclassifying the file.
behavior and rendered UI properties — copy, color token, icon, position,
shape, motion, semantic label.
governingSpec:frontmatter on each translation as the couplingauthority for the lint.
code-path catalogs are trails that follow
spec/authority, notauthorities themselves.
REQ-DESIGN-GOV-007recordsdesign_trail_authority_driftwhen a trail unilaterally declares productbehavior.
wrong_intent/missing_intent/weak_translation/wrong_implementation/missing_evidence/decision_gap) alignedwith the existing implementation gap taxonomy.
noIntentChange: truecommit marker for pure-expression designchanges (copy / color / icon / spacing) that don't change governing
intent.
Test plan
npm run checkpasses locally — 21 project tests, 15 example tests,49 generated REQ stubs all green.
node scripts/check-design-spec-coupling.mjsno-ops in the upstreamrepo (no translations directory present, the configured behavior).
node scripts/check-design-spec-coupling.mjs --dir=examples/design-intent-translation/translationscorrectly reports no changes against
main.Flutter): fails when only translation changes, passes when paired
with governing spec or
noIntentChange: truecommit marker.Out of scope
(the validating adopter does), but the method does not mandate one.
project-specific evidence mechanisms downstream of this governance.
ROADMAP / CHANGELOG
ROADMAP.md 0.3 milestone updated; CHANGELOG.md Unreleased section records
the addition.