BRIEF.mobile-v40.md — The native app as the third density#
Project: relay-creative / mobile surface direction under Experience 4.0 Status: direction proposal — nothing here binds app work until EC ratifies D1 and D3 Live concept: /concepts/mobile-v40 · bundle entry /concepts/v40 Scope of record: relay-board/docs/product/PRD.mobile-v3.md (RELAY-MOB-PRD-003) · mirrored read-only at /concepts/v40/prd.html Supersedes: BRIEF.mobile-v1.md (2026-06-10, v3.4-era five-screen companion) Interface law: ../guidelines/GUIDE.mobile-composition.md · ../guidelines/GUIDE.interface-principles.md · ../guidelines/GUIDE.voice.md Date: 2026-08-17 · v3.5 material, v4.0 composition
Why#
The app and console concepts argue that one shell serves both surfaces. The native app is the case that argument has to survive, because it is the surface where the claim is currently false: relay-app mobile/lib/theme.ts is GitHub-Primer dark, accent #00D9C8 used as a static fill, system fonts, documented against v3.4. It is not a density of the shell. It is a third design system that happens to ship next to one.
Two things changed at once, and together they make this the moment to draw it.
The build outgrew its own scope statement. PRD v2 drew a boundary — companion, not a port — excluding the composer, search, series management and anything admin-shaped. Three of those ship today, and the largest file in the app, at 449 lines, is the governance surface. The boundary stopped describing the product and nobody retired it.
EC widened the scope deliberately (2026-08-17): governance, account, workspace, library, people and support are mobile jobs, not web-only ones. That is not a reversal of the companion posture — it is the recognition that a phone is where you are when the account needs attending to, and that DEC-023 already assigns those screens to the app rather than the console.
What the concept has to prove#
A concept in this estate earns its place by carrying a mechanic that would visibly break if its claim were false — positions never move on the hats page, the material never changes on the surfaces page, a destination exists for every removed rail item on the app page.
The mobile mechanic is reachability. Fifteen destinations from the PRD's scope list, counted live against whichever shell is switched on. The v4.0 side must reach every one; if a composition strands a destination, the counter says so on screen rather than in a footnote.
Measured, not asserted: the drawer reaches 15 of 15. The shipped five-tab bar reaches 8 — four in tabs, four nested behind the Menu sheet — and strands 7 with no route at all: Files, Explore, Network, Workspace, Support, Connect, Loop.
The v3.5 side is drawn from the shipped scaffold (mobile/app/(app)/_layout.tsx) plus the Menu sheet added 2026-07-25, not from a caricature. That bar was already full at three jobs; the July fix — demoting You into a sheet — was the shell running out of room in public.
The four jobs#
Three carried intact from PRD v2. The fourth is what the code already does.
| Job | Posture | What it means |
|---|---|---|
| Act | Ambient | Approve or deny what is waiting, from the notification where the OS allows |
| Aware | Ambient | A five-second read on where things are |
| Capture | Ambient | Speak or share on the move — the phone is the sticky note |
| Attend | Deliberate | Profile, hats, library, people, plan, support |
Posture is the distinction, not depth. The first three arrive from outside and must resolve in seconds. The fourth is what you opened the app to do. A user who taps into workspace management has declared intent, and serving them a deliberately thin screen because they are holding a phone is the failure the composition law exists to prevent.
The amendment this forces#
The 4.0 bar reads taste (MCP) → excerpt (mobile) → full (web app). As written, every Attend screen is off-canon.
Depth is a property of the view, not of the surface. A card is an excerpt everywhere. A screen you navigated to on purpose is full depth everywhere. What differs by device is composition — the 390px budget, sheets over modals, one view mode — never capability.
That is D3, and it is a one-paragraph ratification the rest of the mobile line waits on.
Direction per surface#
Three of these have no implementation on any platform. For those, "port from web" is not the safer path — it is the more expensive one, because composing at desktop width and reducing is precisely what GUIDE.mobile-composition.md forbids.
| Surface | Direction | Why |
|---|---|---|
| Files · Library · Shelf | Mobile-first | No surface on web either; shelves-mobile-v1.html already draws it at 390px |
| Workspace — the hat | Mobile-first | switchWorkspace() exists as a function on the Orgs screen; no shell-level switcher anywhere |
| Support | Mobile-first | The phone is where you are when it breaks, and it can attach device, build and object unasked |
| Capture | Mobile leads, web follows | The share sheet only exists on a phone |
| Governance | Parity | Already the strongest thing the app has |
| Profile · Network | Port | Well-specified, no decisions outstanding |
| Relay quick-info | Hold | Blocked on RCTX-1259, document-vs-handoff. Do not draw it yet |
Composition rules this surface adds#
Everything in GUIDE.mobile-composition.md applies unchanged. Three things are specific to the native shell and belong here:
- The drawer is the nav at every density. Shell law 5 — mobile folds, never forks — and a drawer scales where five tabs do not. Twelve-plus destinations is not a tab-bar problem to solve; it is a tab bar being the wrong object.
- Menu stays a sheet, never a screen. Carried from
app-mobile-v2.htmland the reason the drawer works: nothing underneath is lost, and you are never more than one tap from where you were. A sheet that opens must close from the keyboard as well as the scrim — the scrim only exposes the strip beside the drawer, so tap-outside is not a complete escape on its own. - Activity is one feed. Notifications and history in a single space, the bell a shortcut into it rather than a second inbox. Mobile answered the two-inbox question correctly before the web surfaces did; do not let the port undo it.
Copy the concept corrects#
Code length. app-mobile-v2.html reads "Codes are 6–8 characters and not case-sensitive." Canon is 4–16 accepted, 10 minted under wide_mint, legacy 6 valid forever — and never a fixed length in copy. That string already produced a shipped bug (relay-app a43470a, #707, claim submit rejecting sub-6 Codes the button had accepted). The v4.0 page does not repeat it; the v3.5 page still needs the fix.
Connect names three products. The connector handshake (connect-wizard.ts), the Loop founding-member programme (native connect.tsx), and people (connections.ts, network.ts). The phone currently shows the least common of the three under the most contested name.
Proposed split, folding into the lens-glossary ratification and enforced by
check_vocab.py: Connect is the handshake. Network is people. Loop is the programme.
What is not in scope here#
- Material. No token, no palette, no type change. A composition that needs a new token is the wrong composition —
v40.cssresolves everything from/brand/relay-tokens-v35.css. - The wearable.
app-wearable-v1.htmlopts out of the shared component matrix on purpose and stays a companion to the phone, unscheduled. - Build sequencing. Phases and gates live in the PRD, not in a creative brief.
Gates#
| Decision | Blocks | |
|---|---|---|
| D1 | Mobile nav — DEC-022 exception, or drawer adoption | The native shell. Everything else is drawable without it; this is not |
| D3 | Depth per view, not per surface | Whether any Attend screen is canon-compliant |
D1 has a landing rule. DEC-022 is Active and says no bottom tabs; the PRD and the shipped app carry five. Three artefacts disagree. Whichever way it rules, it lands in DEC-022, the PRD and app-mobile-v2.html in the same change — fixing two of three reproduces the problem.
Full decision list, D1–D8: relay-board/docs/product/PRD.mobile-v3.md §8.