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 a UX-* ID; ungoverned findings flag as UX-UNGOVERNED to 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.