GUIDE — Interface principles#

Status: law — v1, 2026-08-03 Applies to: every Relay surface — web SPA, native app, operator console, agent harness Companion: relay-app/DESIGN.md (tokens, colour, type) — this document covers composition and behaviour, that one covers material. Where they overlap, packages/ui/tokens.css wins on values and this document wins on arrangement.

These are the rules a screen has to pass before it ships. They are deliberately few and deliberately blunt — a guideline nobody can recall while designing is decoration.

The governing principle#

Display weight is proportional to information value.

Nearly every interface failure we've recorded is a violation of this one line. When a field is identical on every row, it carries no information — and giving it prominence steals the space from the field that does. When a control only becomes useful after you understand the content, it cannot sit above the content.

Two corollaries, both load-bearing:

• Show the exception, not the default. If a state is true of almost everything, its presence tells the user nothing; only its absence would. Render the deviation.
• Recall is never truncated to a stub. The field that lets someone find their own work again must stay readable. If something has to be cut, cut metadata — not the field that distinguishes one row from the next. (This is about legibility, not rank: under DEC-025 L3 the title keeps the same rank in every state and is never promoted to hero. Readable and promoted are different claims — see GUIDE.list-surfaces.md.)

The seven rules#

These are the triage test for the experience program (relay-app/docs/PLAN.experience-program.md §2) stated as design law. A screen that fails one is not finished.

1. Hand-reachable#

The primary action sits in the bottom third of a phone screen. The top of the screen is for orientation — titles, context, escape — never for the thing the user came to do.

2. One-thumb, few-step#

Every step in a daily move (claim, send, approve, open, forward, file) needs a defence. Count taps in the prototype, not after the build. "It's only one more tap" is how five-tap flows are built.

3. Legible at a glance#

What is this · is it mine · is it fresh · did it work — all answerable in about two seconds without scrolling. This is the rule the governing principle protects.

4. Answers immediately#

Design the acknowledgement, not just the result. Every input gets a visible response within ~100ms even if the outcome takes a second. Loading has a shape — a skeleton of what's coming, not a spinner that could mean anything.

5. Recoverable#

Prefer undo to a confirmation dialog. A dialog the user always confirms has trained them to stop reading, which makes it worse than nothing on the day it matters. Reserve confirmation for what genuinely cannot be undone, and say plainly what won't come back.

6. Same object, same grammar#

A relay behaves like a relay on web, on mobile, and in the harness — same action set, same order, same words. Divergence is allowed but must be written down with its reason. Corollary: no affordance may be hover-gated without a touch and keyboard equivalent.

7. Harness-honest#

A tool response is composed, not dumped. It tells the agent what happened, gives the reader something legible, and costs less context than it saves. See GUIDE.harness-surface.md.

Standing rules#

Beyond the seven, these hold everywhere and don't need re-deciding per screen.

Vocabulary is locked. Code (never PIN), relay user-facing / transfer at the API layer, Stream (never Pulse in anything user-visible), Series, Session. Canon: _vocab/_VOCAB.md.

Codes are always mono and letter-spaced, everywhere, at every size — they're meant to be read aloud and typed by hand.

Time is honest. Relative and ticking by default, exact on press. Never a bare timestamp where a person has to do arithmetic.

Fail closed on visibility. When permission or scope is uncertain, show less, not more, and say why the user is seeing less.

Motion respects prefers-reduced-motion, without exception. See ../briefs/BRIEF.interaction-motion.md.

Accessibility is composition, not review. Touch targets, focus order, contrast and announcement are decided while designing. WCAG 2.2 AA is the floor — relay-app/docs/AUDIT.accessibility.md.

Cormorant is reserved. Display moments only — a glance, a success, a piece of ceremony. Outfit carries the UI. JetBrains Mono carries Codes and captions.

How to use this#

Designing: compose against the governing principle first, then walk the seven rules before handing anything over.

Reviewing: name the rule. "This fails rule 3 because the title is truncated to four characters" is actionable; "this feels cluttered" is not.

Filing: findings in relay-app/docs/AUDIT.experience-findings.md cite the rule number they fail. That's the shared language between design, build, and the tracker.

Provenance#

These rules are derived from recorded findings, not imported from a style guide. The governing principle and its two corollaries come directly from EXP-005 (a list where ACTIVE/PRIVATE/PERSONAL took full width on every card while titles truncated to four characters). Rule 6's hover corollary comes from EXP-007. Rule 4's acknowledgement budget comes from EXP-002.

When a new finding doesn't fit any rule but is clearly right, that's a signal this document is missing something — amend it here and note it in the area CHANGELOG.md. Rules earn their place by catching real defects.

Framework note#

This document is deliberately brand-neutral in structure. Every rule except the vocabulary and Code specifics applies to any product with objects, lists, and detail views — it is framework-candidate material for Launchpad. Keep it that way: where a rule is Relay-specific, mark it, so extraction is a matter of changing names rather than untangling.