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, the motion register, the component contract table, the forms standard, 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.

Behaviour — motion, components, forms

Motion Register

The feedback-vs-flourish split and the nine register rules: CTAs and inputs never animate, play never gates content, a complete resting frame under reduced motion, one loud piece per page, transform/opacity only. The pulse family’s four hard rules bind by reference; enforcement is the two-width render check — no checker can see motion.

Component law→

Component Contracts

The single per-component table the app and UI teams read — button, form field, card, nav, CTA band: the states each owns, the a11y behaviour it must carry (a card with one destination is clickable everywhere), and the motion it is permitted. Copy the specimen’s markup, never a screenshot of it.

Forms & Lead Capture

The seven pieces every capture form carries — accessible labels, per-field error lifecycle, hints with aria-describedby, autocomplete, bot-check gating that never traps, consent that locks submit without playing dead, a confirmation that moves focus. Held from three sides: this law, the live specimens in concepts/forms-kit-v1.html, and scripts/check_forms.py.

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

How Relay sounds when it has a paragraph to work with. The two-beat headline and the turn that earns it, the six moves, mechanism over benefit, register per surface, the never-list, and the three overclaim traps where every word is legal and the sentence still lies.

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.

Social Accounts

One identity on every platform Relay holds a profile on. The brand line — Context that moves. — and the surfaces it owns, display names and handles, bio copy locked at four lengths, banner and avatar law, the pinned-Code demo pattern, and the posts that never ship.

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.