Writing the product is talking to someone already inside
Say less. Say it.
Direct. No apology. No hedging. This page is the floor for every string we ship.
§A · Buttons · action-first verb · destructive carries the noun
CONTEXT
Don't
Do
PRIMARY
Submit
Run simulation ↗
SECONDARY
Yes / No
Cancel (ghost text, not a button)
DESTRUCTIVE
Delete
Delete run · 38
REMOVAL
Remove
Remove member · avi@
RESET
Reset
Reset audience · "U.S. Pro"
EXTERNAL LINK
Click here to learn more.
Read the methodology ↗
A button is a verb. Cancel is ghost text. “Submit” is banned.
§B · Errors · what · why · what to do
§B.1 · the pattern
Three parts.
WHAT
HEADLINEThe event, as a noun + verb. "Run failed."
WHY
BODY · 1 sentenceCause and cost. "Stopped at agent 412. Model timeout. No charge applied."
WHAT TO DO
LINKS · ink, never buttonsOne or two next moves. "Resume from checkpoint · View incident report."
§B.2 · in place
How it reads.
Run failed
Stopped at agent 412 of 2,047.
Model timeout. No charge applied. The last successful checkpoint was at 50%. We can resume from there.
If we don't know the cause, say so. Never blame the user.
§C · Empty states · name the absence
FLAVOR
Don't
Do
ZERO
No data.
No simulations yet. Your library will fill up here. Start by describing a decision in plain English.
NO RESULTS
No matches found.
Nothing matches "churn risk." Closest match in your library is "Trial cohort · 14d" — different word, similar question.
ERROR
Failed to load.
We couldn't load run · 38. Transient storage issue. The intake spec is intact — duplicate it and re-run.
§D · Loading · be honest about how long
DURATION
Don't
Do
< 1s
Loading…
(silent — no copy)
1–4s
Please wait
Verifying audience ·
2,047 agents matched4–30s
Loading…
Run · 38 ·
62% · 1m 24s left> typical
Almost there!
This is taking longer than usual — about
9 min remaining.§E · Confirmations · destructive only · two buttons
§E.1 · in place
The shape.
Destructive · cannot be undone
Delete run · 38 and 2,047 agent traces?
The result, the cohort breakouts, and every agent's reasoning trace will be removed permanently. The intake spec will stay in your library so you can re-run it.
§E.2 · the rules
What's banned.
"Are you sure?" as the headline.
Yes / No buttons.
"OK" as the destructive button.
"Don't show this again" — every confirmation earns its interruption.
A third button.
Reversible actions never get a confirmation — they get an undo.
§F · Toasts · receipts, not announcements
CHANNEL
Don't
Do
SUCCESS · 4s
Saved! 🎉
Saved — spec saved to your library as "Pro $29 → $49"
INFO · 7s
FYI: simulation started.
Running — 2,047 agents · est. 4 min remaining
WARN · sticky
Heads up — things are slow!
Slow — inference queue is busy; your run is delayed about 9 min.
ERROR · sticky
Oops! Something went wrong.
Failed — run · 38 stopped at agent 412 · model timeout. Retry the simulation.
Don't toast a successful click. ("Saved!" "Copied!" "Done!") The next state is the receipt.
§G · Numbers · tabular always · units attached
§G.1 · currency
EXACT$1,249.00
ROUND$1,499
HERO$1.4M
B$38B
§G.2 · time · count
DELTA+3.4%
PT-DELTA+3.4pt (not "pp")
DURATION4m 12s
DATETIME26.04 14:02 EU sort
COUNT2,047 / 2.1k / 1M
§G.3 · ranges
NUMERIC$39 → $49
DURATION2 – 4 min
QUARTERQ3 2026
UNIT3.4% · 14ms spaces & not
Tabular nums everywhere a number could change. No space before
%, pt, pp. Space before min, s, ms. Currency two decimals when known exactly; round when projecting.§H · Forbidden words · strike on sight
these signal the writer reached for personality, not clarity
just
simply
easily
quickly
effortlessly
please
sorry
oops
whoops
uh-oh
hey there
friend
folks
y'all
let's
amazing
awesome
wonderful
perfect
you've got this
you're all set
Skip the fake-friend opener (“Hey there!”) and the hedge (“Don't worry”). Name the problem or say nothing.
§ The 90-second checklist · before shipping any string
Before you commit.
- Does it say what happened, in noun + verb?
- Did I use any forbidden word? Strike it.
- Is there a "please" or "sorry"? Strike it.
- If destructive: does the verb carry the noun?
- If error: does it say what · why · what to do, in that order?
- Is there a number? Is it tabular? Is the unit attached?
- Could I cut a word and still be understood? Cut it.
Authority the product team · Doc WRITING.md · Companions Voice & Tone · Forms · Feedback · Overlays