guidelines/#
Interface guidelines — the law for how Relay surfaces are composed and behave.
Browsable at creative.relayctx.com/guidelines/ —
index.htmlis the card index for the area. This file is the written orientation behind it.
This area answers how a screen is built. It is the missing middle between the design system (what things are made of) and the briefs (what we're building next). Since 2026-08-07 it also covers the non-app surfaces — presentations and documents — where the same three layers hold but the copy layer is governed by the Master Copy Deck and the disclosure gates.
The set#
| Document | Covers |
|---|---|
| GUIDE.interface-principles.md | The governing principle, the seven rules, and the standing rules that hold everywhere. Start here. |
| GUIDE.mobile-composition.md | Phone-width law — the space budget, controls-on-demand, reach, sheets, touch, layout behaviour |
| GUIDE.list-surfaces.md | Card anatomy, the badge rule, the list shell, filtering, density, selection |
| GUIDE.states-and-language.md | Empty / error / gate / loading states, voice, locked vocabulary, copy budgets |
| GUIDE.harness-surface.md | The agent harness as a designed surface — two readers, context budget, verb clarity, gates |
| GUIDE.presentations.md | Deck law — living-page standard, slide type scale, light/dark/drenched colour budget, archetypes mapped to the Master Copy Deck M-IDs, motifs, and the font-delivery policy for exports |
| GUIDE.documents.md | Document law — page chrome, living-document versioning, the per-viewer watermark standard, letterhead-as-PDF |
Where this sits#
Three layers, three owners. Keeping them distinct is what stops the estate accumulating four half-true design documents.
| Layer | Owns | Lives in |
|---|---|---|
| Material | Colour, type, spacing, elevation, token values | relay-app/DESIGN.md + packages/ui/tokens.css — tokens win on any value conflict |
| Composition & behaviour | How surfaces are arranged and how they respond | here |
| Direction | What we're building next, and why | ../briefs/ |
These guidelines are law; briefs are proposals. A brief that contradicts a guideline either changes the guideline in the same PR or doesn't ship.
They are also downstream of the experience program — the standing loop that turns observed friction into tracked work. Charter and findings register: relay-app/docs/PLAN.experience-program.md and docs/AUDIT.experience-findings.md. Execution in Linear (Experience Optimization — App & Agent Harness).
How these were written#
Derived from recorded findings, not imported from a style guide. Every rule that isn't obvious traces to an EXP-nnn row — a real screenshot of a real screen. The governing principle came out of a list where three identical badges took full width while titles truncated to four characters.
That matters for how you use them: a rule you can't trace to a failure is a rule to challenge.
Amending#
Guidelines earn their place by catching real defects. When a finding is clearly legitimate but fits no existing rule, that's the signal to amend.
- Change the guideline, in a PR, with the
EXP-nnnthat prompted it. - Add a line to
CHANGELOG.md— same PR. - If it changes what's canonical, update the master
MANIFEST.md— same PR. - If the rule is generic rather than Relay-specific, say so in the framework note, so Launchpad can take it.
Don't add a rule for a hypothetical. The set stays short enough to hold in your head, or it stops being used.
For agents and contributors#
Reviewing an interface? Name the rule. "Fails rule 3 — the title is truncated to four characters" is actionable. "Feels cluttered" is not. The rule numbers are the shared language between design, build, the findings register, and Linear.