How a Relay screen is built.

Interface law for the estate — the layer between the design system (what surfaces are made of) and the briefs (what we’re building next). Composition and behaviour: the governing principle, the seven rules, mobile at 390px, card and list anatomy, states and language, and the agent harness as a designed surface.

Start here

Interface Principles

The governing principle — display weight is proportional to information value — with its two corollaries: show the exception not the default, and identity is never what gets truncated. The seven rules as design law, plus the standing rules that hold everywhere.

Read Me — how this set works

The three layers and their owners (material / composition / direction), why these are law rather than proposals, how they were derived from recorded findings, and the rule for amending them.

Surfaces

Mobile-first→

Mobile Composition

Design at 390px first. The space budget (rail off-canvas, ≤2 rows of chrome), controls-on-demand behind a filter sheet, reach and the bottom third, sheets over modals, touch targets and input, one column and no horizontal overflow. Ends in a ship checklist.

Lists & cards→

List Surfaces & Card Anatomy

Identity composed first and sacrificed last. The badge rule (render the exception, not the default), the fallback order for untitled objects, mandatory pagination, the combinable filter model, and the 0 / 3 / 500+ volume check.

Agent surface→

The Agent Harness as a Surface

No pixels, still designed. Two readers on every response, the context budget (a response that blows the window is a defect), ids always with names, verb-direction clarity, gates spent only where stakes justify. Companion to the MCP visual reference.

Presentations & documents

A deck's primary form is a page, not a file. The slide type scale in three registers, the light / dark / drenched colour budget (bookends plus one earned moment), archetypes mapped to the Master Copy Deck M-IDs, the send→route→receive motif, and the font-delivery policy that retires tool-default substitutes for good.

Document law→

One-pagers, memos, and living documents. Page chrome and the version line, the maintenance comment every governed page opens with, the per-viewer watermark standard (Access identity, header stamp, tiled diagonal mark, print-safe), and letterhead as PDF with brand fonts embedded.

Language

States & Language

No dead ends. Three distinct empties with a mandatory has-content guard, the error formula (say what to do, not what failed), permission and gate states, honest time, the voice table, the locked vocabulary, and copy budgets at 390px.

The locked words. Code (never PIN), relay user-facing / transfer at the API layer, Stream (never Pulse where a user can see), Series, Session. Claim and handoff are opposite directions and are never described as one another.

Where these come from

Experience Program — charter

The standing loop these guidelines serve: mobile first, agent harness adjacent. The seven-point bar, the screenshot → register → Linear intake, and the seven tracks. Lives in relay-app.

Findings Register (EXP-nnn)

Every non-obvious rule here traces to a row in this register — a real screenshot of a real screen. A rule you can’t trace to a failure is a rule to challenge.

Experience Optimization — brief

The creative half: direction and language for findings that aren’t plain defects. Briefs propose; guidelines decide.

Design System — DESIGN.md

The material layer: colour roles, type registers, elevation, component law. Token values in packages/ui/tokens.css win on any conflict. These guidelines cover arrangement, that one covers substance.