The problem
It is 1 a.m. A writer has just finished the scene she has been avoiding for a week. The screen says “Cloud sync failed”. She does not know what the cloud is doing, whether the scene exists, or whether to close the laptop. The word “failed” lands on her, not on the network.
Before October 2026 this was real. Raw Firebase text such as “auth/network-request-failed”, “Cloud sync failed” and “An error occurred” reached writers, and a refused write was dropped without a word. The 17 October audit ranked plain sync words and friendly errors in its top ten for the producer meeting.
An error in a writing tool is not a technical event. It is a moment when the writer fears for their work. The message has one job: answer that fear truthfully, then help.
Kwark’s answer
Decision 0013, a calm voice for sync and errors: tell the state first. Errors say what happened, that the work is safe if that is true, and what to do. Never “failed”.
Every error a person might see goes through one function, friendlyError() in utils/friendlyError.ts. It maps known codes to a calm sentence, lets Kwark’s own sentences pass through, and replaces any library text (anything mentioning Firebase, a stack frame, TypeError, undefined) with the fallback: “Something went wrong. Your work is safe; please try again.”
The order of a Kwark error sentence
- The state of the work, when it is at stake: “Your work is safe on this device.” “Nothing was changed in your script.” “It is still in the trash.”
- What happened, in the person’s terms: “We could not reach the internet.” “The sign-in window was closed.”
- What to do, if anything: “Try again when you are back online.” “Ask the project owner if you need it.”
Sometimes the state goes first, sometimes what happened does; both must be there when the work is involved. Never say the work is safe when Kwark does not know it is.
Choosing where the error appears
| Situation | Where | Example |
|---|---|---|
| One field cannot be accepted | Under the field, linked to it | “Choose a date after today, or choose No end date.” |
| An action did not complete, nothing lost | A toast with the reason and, if useful, the retry | “That change was not saved. Try again.” |
| The page cannot do its job until something changes | A banner under the header that stays until resolved | “This screenplay has not downloaded to this device. Nothing will be saved until it does.” |
| The person must choose between two outcomes | A banner with both choices | “This screenplay was changed in another session.” with Load the newer version and Keep mine |
| Access is missing | The page itself, with who to ask | “{Owner} hasn’t shared {module} with you.” |
| A whole screen crashed | The error boundary, with a way back to the library | A plain sentence and a route home, never a stack trace |
Anatomy
| Part | Means | Rule |
|---|---|---|
| Sentence | What happened and the state of the work | One or two short sentences, no code |
| Action | The one thing that helps | A verb and an object: Try again, Retry saving, Open project |
| Tone | How much this blocks | Warn (amber) when the work is safe but waiting; danger only when work is blocked or would be lost; always with words |
| Persistence | How long it stays | Toasts for things that are over; banners for things that are not |
Real copy from the app
These are the sentences friendlyError() returns today. Use them; do not write new variants of the same situation.
| Code | Sentence |
|---|---|
| Wrong email or password | That email and password do not match. Please check them and try again. |
| Bad email | That email address does not look right. Please check it and try again. |
| Email in use | This email already has an account. Try signing in instead. |
| Too many tries | Too many tries just now. Wait a few minutes and try again. Your work is safe. |
| No network | We could not reach the internet. Your work is safe on this device; try again when you are back online. |
| Pop-up closed | The sign-in window was closed. Nothing changed; you can try again. |
| Pop-up blocked | Your browser blocked the sign-in window. Allow pop-ups for this site and try again. |
| Link expired | That link has expired. Ask for a new one and try again. |
| Permission denied | You do not have access to this. Your work is safe; ask the project owner if you need it. |
| Cloud unavailable | We could not reach the cloud just now. Your work is safe on this device and will go up when we can. |
| Storage full | There is no room left to store this. Your work is safe; try a smaller file. |
| Cloud busy | The cloud is busy right now. Your work is safe; try again in a little while. |
| Signed out | Please sign in again. Your work is safe on this device. |
And from the screens:
- “Could not save. Your words are kept on this device.”
- “That copy could not be made. Nothing was changed in your script. Try again, or use a different format.”
- “The trash could not be emptied just now. Nothing was lost.”
- “This project could not be restored. It is still in the trash.”
- “That request was not answered. Open the project and try from Share.”
- “Your browser blocked copying. Select the text and copy it yourself.”
- “The download could not start. You can copy or select the prompt instead.”
A character edit that cannot be stored stays open and offers Retry saving, and the on-screen Back waits for the local save (Decision 0013 history, 4 November 2026).
Rules
- Must route every error a person can see through
friendlyError()or a sentence written for that screen. - Must say the state of the work whenever the work could be at stake, and only when it is true.
- Must keep everything the person typed when validation fails or a retry is needed.
- Must say what to do next, or say that nothing is needed (“Nothing changed; you can try again”).
- Never use “failed”, “error occurred”, “invalid”, “denied” or “fatal” in a message a writer reads. The audit also flagged “Access Denied” and “Active Editing Session” as words to replace.
- Never show raw Firebase, browser or stack text, even in a tooltip.
- Never apologise at length, blame the person, or use an exclamation mark.
- Never use red for something that does not block or destroy work. Offline is amber, with words.
- Always put the reason for a disabled control on the page, not only in a tooltip (Decision 0020 review).
- Always name a quota for what it is. A project-wide daily ceiling is not a fault in the person’s change, and saying so saves them looking for a problem in their own work.
Edge cases
- Refused because view-only. The edit stays on the device and is not published; nobody is told their work failed to save when it was never theirs to save. The page itself shows they are reading.
- Private research refused by the server. It is kept in the queue and retried, not dropped, so it cannot later be mistaken for something deleted elsewhere.
- The same error twice in a minute. Show it once; update the sentence if the state changes.
- An error behind a dialog. The dialog stays open with the error inside it, next to the action that caused it.
- Unknown error. The fallback sentence, and the detail goes to the console for whoever is debugging, never to the screen.
Phone and desktop
The same words on every device. On a phone a banner is one line of what went wrong and how to fix it, with its action wrapping below; long detail moves into the account panel. Toasts sit above the floating button, never under it. A field error sits directly under its field so the on-screen keyboard does not hide it.
Accessibility
- An error toast uses
role="alert"; a status that does not need interrupting usesrole="status". - A field error is linked with
aria-describedby, and the field hasaria-invalid="true". Focus moves to the first invalid field on submit. - The tone is never the only signal: every error has its sentence, and icons are hidden from screen readers when the sentence says the same.
- Do not auto-dismiss an error that asks for action. Toasts with an action stay 8 seconds and pause on hover or focus; banners stay until resolved.
“We could not reach the internet. Your work is safe on this device; try again when you are back online.”
“auth/network-request-failed” or “Cloud sync failed”.
“This project could not be restored. It is still in the trash.” with Try again.
“Restore failed. Please contact support.” in red with a warning triangle.
Keep the email the person typed, outline the field, and say “That email address does not look right. Please check it and try again.”
Clear the form and show “Invalid input” at the top of the page.
Demo
<label class="kw-field" style="width:100%;max-width:360px"><span class="kw-label">Access until</span><input class="kw-input" value="12 Nov 2026" aria-invalid="true" aria-describedby="err-until"><span class="kw-error" id="err-until">Choose a date after today, or choose No end date.</span></label>
<div class="kw-toast kw-toast--error" role="alert"><span class="kw-toast__icon" aria-hidden="true">!</span><span>That change was not saved. Try again.</span><button class="kw-text-button" type="button">Try again</button></div>
<div class="kw-banner kw-banner--warn" role="status" style="width:100%;flex-wrap:wrap"><span style="flex:1;min-width:220px"><strong>This screenplay has not downloaded to this device.</strong> Nothing will be saved until it does, so the copy elsewhere stays exactly as it is.</span><button class="kw-button kw-button--sm" type="button">Try again</button></div>
<div class="kw-card" style="display:grid;gap:8px;max-width:420px"><strong style="font:600 var(--k-fs-title)/1.3 var(--k-font-display)">Mira hasn't shared Characters with you.</strong><span class="kw-row__meta">Ask Mira if you need it.</span><span><button class="kw-button kw-button--sm" type="button">Back to the project</button></span></div>
Related
Saving and sync, Forms, Toast, Banner, Text input, UX writing.
AI readiness test
Task. The budget’s CSV download throws a quota error from the cloud. Write what the person sees.
Give the agent. This page, utils/friendlyError.ts, Saving and sync.
Constraint. Use an existing sentence if one fits.
A reliable answer
- Uses friendlyError’s "The cloud is busy right now. Your work is safe
- try again in a little while." or a quota sentence that says it is a daily ceiling, not their fault
- No raw code or “failed”
- A toast, because the budget itself is unharmed
- Offers Try again and keeps the budget open