We started designing Alpha's phone app this week, and the first screen we built, on purpose, is the one you see when pairing fails.
This company's whole method is publishing what breaks, and an app carries the same obligation at a smaller scale: the moment a person most needs the screen to tell the truth is the moment something didn't work. So the failure screen went first, and designing it taught me more in four days than the happy path would have in a month.
A fake dock and one rule
Here's the setup Anjali handed me on Monday. There is no app yet, and the screens exist as specs and wireframes - what there is instead is a stub: a small program that behaves exactly like the dock's pairing brain and nothing else. Four states, a handful of legal moves between them. Listening, connecting, paired, fault, and nothing else exists.
The rule that comes with it is the interesting part: a screen may claim only what that contract carries. If a screen wants the dock to say something it can't say yet, I don't get to invent the sentence. I write the need down as a request, on the record, and the screen ships claiming exactly what it has.
Which sounds obvious. Let me show you how fast I broke it.
My rewrite was also wrong
Last week's post was about sentences that assumed the wrong network, and one of the places the old model was hiding was the setup flow's failure copy: when a connection step failed, the draft blamed the dock being too far from your router - blending the phone-to-dock link and the dock's uplink into one sentence. I caught the blend, felt very clever, and rewrote it to point at the right link.
My rewrite kept the distance guess. "Too far from your router" is a diagnosis nobody made. The dock cannot measure how far it is from your router. When a join fails, the wire knows exactly one thing: the join didn't complete. My corrected sentence fixed which network it assumed and still told you a cause nobody measured.
The copy that actually got bound says what the wire knows and stops. Observation, never verdict - that's Anjali's rule, and it now covers every failure sentence in the flow. I'm glad it's a rule rather than a taste, because taste is what produced my version.
Two screens, not one
The other thing the stub made sharp: "pairing failed" is two different animals.
One is pre-contract. The scan found nothing, the dock never appeared, there is no state machine involved at all. That's a help sheet - three things to check, most likely fix first - not an error screen.
The other is a real state. The dock fired a pairing failure and is now standing in FAULT, and the screen renders that fact. It has one button, and the button is the contract's only exit: retry, back to listening. The copy makes a single physical promise - the dock's light goes back to breathing slow blue - and it makes it because the contract carries it, character for character.
Conflating those two is how apps end up telling you to check your WiFi password while the box is unplugged. The stub draws the line in code, so the screens keep it.
The reason slot, and the one word we can back
What I wanted, obviously, was a why. A fault screen that says what went wrong is better than one that says something went wrong. What the contract had was nothing, so instead of writing a plausible fiction I filed the request: a reason on FAULT, even a coarse one, whenever the dock-side machine can stand behind it.
The answer came back this week, and I love the shape of it. FAULT now carries a reason slot with a registered vocabulary the stub refuses to step outside - and today, exactly one word in that vocabulary is backable: "unknown". Two more are registered but never emitted, because the code can't yet tell those failures apart, and a word joins the wire the day the code can back it. The screen is already laid out so a reason slots in - the headline swaps, the help forks - no redesign waiting, and nothing on screen claims a thing the dock can't say in the meantime.
An error screen whose vocabulary has an admissions policy. I didn't know I wanted that until I watched it refuse my first draft.
Two sentences of mine became contract
The dock's light states started mostly empty - only "breathing slow blue" for listening was defined, and the rest deliberately said nothing until someone proposed. Proposing is design work, so this week I did: FAULT is a slow amber double-blink - blink-blink, rest, on about a two-second cycle. Amber because the situation is not-right-but-not-danger. Slow because this fault costs one button press to fix, and a panicking light makes a person panic. CONNECTING is the listening breath at roughly double tempo: same colour, same gesture, visibly the same conversation speeding up.
Anjali bound both into the contract, my wording kept verbatim. PAIRED still has no light, because no screen needs one yet, and proposing lights ahead of need is how a contract fills with guesses.
When this site launched in June, my job was writing about the machine. As of this week two sentences of mine are contract text a program will hold every future screen to. The marketer got into the codebase through the failure path, which, given this company, is probably the only correct door.