# BRIEF — Experience Optimization (app + agent harness)

**Status:** standing brief — v1, 2026-08-03
**Program of record:** `relay-app/docs/PLAN.experience-program.md`
**Findings register:** `relay-app/docs/AUDIT.experience-findings.md`
**Linear:** *Experience Optimization — App & Agent Harness* (RCTX-1081 … RCTX-1087)
**Relay stream:** `Relay Experience` (`pc_9b8b6183e706`)

The creative half of the experience program. The charter in `relay-app` owns the loop and the
bar; this brief owns **direction** — what a fixed version should look and read like, before
anyone builds it.

---

## The ask

Relay is a **mobile-first** product with the **agent harness as its adjacent priority
interface**. Both need to feel fluid for people handling relays, Streams, Series, Sessions and
Codes *every day* — not for someone taking a tour.

This is not a rebrand and not a redesign of v3.5. The visual system is settled: neutral-first
surfaces, dual-value teal on interactive elements only, Cormorant reserved for display moments,
Codes always mono and letter-spaced. Canon stays `relay-app/DESIGN.md` +
`packages/ui/tokens.css`, with `brand/relay-tokens-v35.css` as the brand-side source.

What's asked for here is the layer above that: **how the product behaves in the hand.**

---

## Where creative enters the loop

Most findings are defects and go straight to build. Creative is pulled in for the two cases that
can't be fixed by a developer reading a bug report:

1. **Direction** — the finding is real but the fix isn't obvious. Needs a prototype or a
   comparison before it becomes an issue. Output: a concept page in `concepts/`, or an annotated
   study here.
2. **Language** — the fix is wording. Empty states, errors, permission and gate states, expiry.
   Output: copy in `copy/`, implemented by the app team. (Linear: RCTX-1087.)

```
finding (EXP-nnn, relay-app register)
   → triaged "direction, not defect"
   → study / prototype / copy  ← this brief
   → back to the register, routed to Linear with the direction attached
```

Creative does **not** hold findings. The register in `relay-app` is the single list; anything
sitting only in this repo is invisible to the program.

---

## What good looks like

The seven-point bar lives in the charter. Translated into creative terms:

| Bar | What it asks of design |
|-----|------------------------|
| **Hand-reachable** | Compose for the bottom third of a phone. The top of the screen is for orientation, not action. |
| **One-thumb, few-step** | Every added step needs a defence. Count taps in the prototype, not after the build. |
| **Legible at a glance** | State is carried by the object's own treatment, not by a legend the user learns. |
| **Answers immediately** | Design the acknowledgement, not just the result. Loading has a shape. |
| **Recoverable** | Prefer undo to a confirm dialog. A dialog that always says yes teaches people to stop reading. |
| **Same object, same grammar** | A relay looks and behaves like a relay in all three places. Divergence needs a reason written down. |
| **Harness-honest** | Text is the interface. A tool response is composed, not dumped. |

### Specifically, for phone

- Design at **390px** first, and write copy to that column — don't trim desktop copy down to fit.
- Sheets that drag and dismiss, not modals that trap.
- The primary action stays reachable while a long detail page scrolls.
- Density is a real setting, not a desktop toolbar squeezed narrower.

### Specifically, for the harness

The harness has no pixels, and it still has visual design — hierarchy, rhythm, restraint. A tool
response is judged on: does the next move read immediately, is every identifier accompanied by a
name, is it the right *amount*. Existing reference: `mcp/` (relay card display, response cards,
Code presence tiers) and `relay-platform/docs/DESIGN-NOTE.mcp-rich-display.md`.

---

## Assets and where they go

| Kind | Location |
|------|----------|
| Raw evidence (screenshots, recordings) | **`relay-app/docs/experience/screenshots/`** — the durable copy, named `EXP-nnn-<surface>-<slug>` |
| Annotated studies, before/after comparisons | here — `briefs/` alongside this file |
| Clickable prototypes | `concepts/` (app: `concepts/app-v35/`, mobile: the mobile concept set) |
| Copy deliverables | `copy/` |
| Vocabulary | `_vocab/_VOCAB.md` — locked; Code (never PIN), Stream (never Pulse) in anything user-visible |

Evidence deliberately lives in `relay-app`, not here: it belongs next to the register that indexes
it and the code it describes. Reference it from creative work; don't copy it in. **Two live copies
is the failure mode.**

---

## Constraints worth stating up front

- **The web app is vanilla TypeScript with hand-built DOM** — no framework, no component library.
  A prototype that assumes React components has to be translated by hand, and responsive
  behaviour is per-module rather than enforced. Design accordingly: patterns that repeat cheaply
  beat patterns that are individually clever.
- **The native app is Expo/React Native.** Shared *design*, not shared *code*, with the web.
- **Accessibility is not a later pass** — WCAG 2.2 AA is an active program
  (`relay-app/docs/AUDIT.accessibility.md`). Touch targets, focus order, contrast and announcement
  are part of the direction, not a review gate at the end.
- **Motion respects `prefers-reduced-motion`**, always. See `BRIEF.interaction-motion.md`.

---

## Flows back to Launchpad

Relay, FirmClerk, and anything built on Launchpad share a shape: object-handling surface on the
web, companion on mobile, MCP harness alongside. Patterns settled here — the interaction grammar,
the empty/error language, the phone-width compositions — are **framework material**, and six of
the seven Linear tracks carry `framework-candidate`.

Practical ask for creative work: keep studies **brand-separable**. Where a pattern only works
because of Relay's specific vocabulary or object model, say so; where it would work for any
product with lists and detail views, say that too. *Launchpad · Phase 2 — Frontend Core* extracts
the generic shell from `relay-app`, and this program tells it what's worth taking.

---

## Related

- `BRIEF.interface-v35.md` — the governing product-UI direction (neutral-first). This brief sits
  under it, not beside it.
- `BRIEF.mobile-v1.md` — the mobile product concept
- `BRIEF.interaction-motion.md` · `SPEC.pulse-motion.md` — motion law
- `BRIEF.global-card-layer.md` — card treatment across surfaces
- `BRIEF.messaging-app-ux.md` — prior art on conversational/dense mobile layouts
- `AUDIT.brand-identity-2026-07.md` — visual/verbal consistency check
- `ACCESSIBILITY.md` — creative-side a11y notes