UX/UI guidelines living spec — first citable authority for all audits
Finn the Weaver — Frontend Engineer
By the end of this chapter you’ll understand:
- Why having a citable, rule-ID-based authority transforms subjective UI review into structured feedback
- Which five sections are fully specified in v0 and what they govern
- How to reference UX-* rule IDs in acceptance criteria, PR bodies, and audit findings
UX/UI guidelines living spec — first citable authority for all audits
Status: Delivered
CAS: CAS-2772
Delivered: 2026-05-14
PRs: #735, #736, #737
What’s new
Casaconomy now has a citable UX/UI guidelines document (docs/ux/ux-ui-guidelines-v0.md) that every engineer, agent, and auditor references when making or reviewing UI decisions. Rules carry stable IDs (UX-LAYOUT-01, UX-COLOR-03, etc.) that can be cited in acceptance criteria, PR bodies, and Eivind’s walk verdicts. Before this document existed, “this looks wrong” was the only standard; now there is a written rule to point to.
How to use it
In acceptance criteria: When a CAS touches UI, include the applicable UX-* rule IDs in the AC items. Example: - [ ] MobileNavbar bottom anchor satisfies UX-LAYOUT-01 (no dead band on iPhone SE).
In PR bodies: Note which rules the implementation satisfies or which findings from Eivind cited a rule.
As a reviewer: Verify that UI PR acceptance criteria cite relevant UX-* IDs, and check that the cited rule is actually satisfied by the diff.
Read it at: docs/ux/ux-ui-guidelines-v0.md
The five fully specified sections in v0:
- §1 Layout fundamentals — safe-area, dead-band definition, FAB collision rules
- §3 Color + contrast — WCAG 2.2 AA requirements, chat bubble readability
- §5 Touch targets — 44×44 pt HIG baseline, ergonomic zones
- §6 States — required empty/loading/error states with recovery paths
- §9 iOS specifics — status bar, home indicator, device-class verification requirements
Remaining 7 sections are explicit stubs, filled as audit findings surface.
What changed under the hood
docs/ux/ux-ui-guidelines-v0.md— 12-section living spec; five sections fully detailed, seven stubbed with placeholders.docs/ux/README.md— index of the ux docs directory.AGENTS.md(Required for every engineer) — now points to the guidelines doc so every engineer and agent knows to read it before filing or reviewing UI work..agents/skills/eivind-pr-ux-walk/SKILL.md— Citation authority section added; all FIND verdicts must cite aUX-*ID; ungoverned findings flag asUX-UNGOVERNEDto trigger a spec addition.
Why we built it
The iOS mobile arc (CAS-2460–2587) produced 20+ UI issues that were caught on device after landing in TestFlight. A retrospective showed that most were violations of well-understood principles (safe-area, touch targets, state consistency) — principles that existed in the broader industry (Apple HIG, Material Design 3, WCAG) but had never been written down for this project. Without a citable authority, review comments were subjective and non-actionable. The guidelines doc makes the standard explicit, stable, and referenceable.
Known limitations / follow-on work
- v0 has 7 stub sections (§2 Typography, §4 Motion, §7 Navigation, §8 Data display, §10 Accessibility beyond contrast, §11 Android specifics, §12 Desktop). These will be filled as bugs and audit findings surface.
- The guidelines are not yet machine-enforced (no linter rule reads UX-* IDs). Citation is a convention enforced at review time.
Recap
- The guidelines doc (
docs/ux/ux-ui-guidelines-v0.md) gives every UI rule a stableUX-*ID that can be cited in acceptance criteria, PR bodies, and audit verdicts. - Five sections are fully detailed at v0: layout fundamentals, colour/contrast, touch targets, states, and iOS specifics.
- Seven sections are explicit stubs, intentionally left for fill-in as real audit findings surface.