# guidelines/

**Interface guidelines — the law for how Relay surfaces are composed and behave.**

> Browsable at **[creative.relayctx.com/guidelines/](https://creative.relayctx.com/guidelines/)** —
> `index.html` is 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](GUIDE.interface-principles.md)** | The governing principle, the seven rules, and the standing rules that hold everywhere. **Start here.** |
| **[GUIDE.mobile-composition.md](GUIDE.mobile-composition.md)** | Phone-width law — the space budget, controls-on-demand, reach, sheets, touch, layout behaviour |
| **[GUIDE.list-surfaces.md](GUIDE.list-surfaces.md)** | Card anatomy, the badge rule, the list shell, filtering, density, selection |
| **[GUIDE.states-and-language.md](GUIDE.states-and-language.md)** | Empty / error / gate / loading states, voice, locked vocabulary, copy budgets |
| **[GUIDE.harness-surface.md](GUIDE.harness-surface.md)** | The agent harness as a designed surface — two readers, context budget, verb clarity, gates |
| **[GUIDE.presentations.md](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](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.

1. Change the guideline, in a PR, with the `EXP-nnn` that prompted it.
2. Add a line to [`CHANGELOG.md`](CHANGELOG.md) — same PR.
3. If it changes what's canonical, update the master `MANIFEST.md` — same PR.
4. 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.