# UX writing

> The micro-copy handbook. How Kwark words buttons, labels, errors, empty states, confirmations, toasts, notifications, first runs, settings and machine suggestions, with before and after tables from real Kwark strings and a word list.

Source: https://kwark.space/designSystem/foundations/ux-writing

## How to use this page

[Content](https://kwark.space/designSystem/foundations/content.md) sets the voice. This page is the working handbook: what to write in each kind of slot, with the strings Kwark already has. Every *Now* in the tables below is a real string from the app's source, found by searching `showToast(`, button labels and empty states. Where a string already works, it is listed as the model. Where it does not, the *Write* column is the fix, and the next person to touch that file should make it.

Three tests for any string, in this order:

1. **Is it true?** Does it claim only what happened? *Saved on this device*, not *Saved*, when the cloud has not answered.
2. **Can the person act on it?** If something went wrong, does it say what to do next?
3. **Would we say it out loud to a nervous writer?**

## Buttons

A button says what will happen, as a verb and its object, in sentence case.

- **Verb first, object named**: *Issue call sheet*, *Retry saving*, *Copy invite*, *Make a restore point*.
- **The same word through the flow.** The button that says *Issue* produces a toast that says *issued*. *Invite* leads to *Invited*.
- **Bare verbs only where the object is obvious and universal**: *Cancel*, *Done*, *Close*, *Undo*. Kwark uses *Cancel* 58 times and *Done* 17; keep them.
- **Never** *Submit*, *OK*, *Yes*, *No*, *Confirm* or *Click here*. They make the person reread the question.
- **A destructive button names what it destroys**: *Delete draft*, *Remove Mira*. Never a bare *Delete* in a dialog.
- **Opens something?** Add a chevron (*Menu ▾*) or an ellipsis in a menu item (*Room…*).

| Now | Write | Why |
|---|---|---|
| *Let in* | Keep | Plain, specific, human |
| *Retry saving* | Keep | Says exactly what it does |
| *Sign in with Google* | Keep | Names the account it uses |
| *Got it* (Reader guide) | *Hide this guide* | Says what happens; *Got it* asks the person to have understood |
| *No* (day planner prompt) | *Keep my layout* | A bare *No* cannot be understood without rereading the question |
| *Save* (generic, in a dialog) | *Save scene*, *Save location* | Names the object |

## Labels and fields

- **A label is a noun phrase** above the field: *Crew call*, *Contingency %*, *What kind of thing*.
- **Placeholders are examples, not labels**: `writer@studio.com`, *e.g. Police procedure*. If the field is empty and the label is missing, the person has nothing.
- **Hints say what the field feeds**: the artefact it ends up in (Decision 0004), never a lesson. *Shown on the call sheet.* is a hint. *Think about what drives your character.* is coaching.
- **Accessible names include the object**: *More for day 3*, *Add Zippo*, *Language for MIRA*, *Not a prop*. A screen reader user hears the name without the row around it.
- **Units in the label**, not the field: *Contingency %*, *Length (min)*.

## Errors

The structure, from Decision 0013: **what happened · that the work is safe, if true · what to do**. One or two sentences. No blame, no apology theatre, no exclamation marks, no codes.

These are already right, and are the models:

| String | What makes it work |
|---|---|
| *We could not reach the internet. Your work is safe on this device; try again when you are back online.* | State, safety, action |
| *This change has not saved yet, so the page stays open. A copy is kept on this device.* | Explains why the page is still open |
| *Could not switch drafts. Your current text is still open.* | Tells the writer nothing was lost |
| *Could not keep a snapshot of your version, so nothing was replaced.* | Explains the safe outcome |
| *Kept here, but it could not be saved yet.* | State first |
| *The sign-in window was closed. Nothing changed; you can try again.* | No blame for closing it |
| *You do not have access to this. Your work is safe; ask the project owner if you need it.* | Neutral, gives a route |
| *Could not finish adding sub-acts. Retry to finish the same set without duplicates.* | Reassures about the retry |

These need fixing:

| Now | Write | Why |
|---|---|---|
| *Firebase is not configured.* | *This copy of Kwark cannot reach the cloud. Your work is safe on this device.* | Never name a vendor or a setup step |
| *Invalid or expired reset link.* | *That link has expired or was already used. Ask for a new one.* | *Invalid* blames; give the action |
| *Could not save that colour.* | *That colour was not saved. Your script is safe; try again.* | Add safety and the action |
| *Could not prepare the pack.* | *The pack could not be made. Nothing in the project changed; try again.* | Say what was not affected |
| *Could not save right now. Check the status banner.* | *Not saved yet. Your change is kept on this device and will go up when the cloud answers.* | Do not send the person looking elsewhere |
| *Your change could not be saved. Please try again.* | *Your change was not saved yet. It is kept on this page; try again.* | Say where the work is |
| *Could not import that CSV. Check the file structure and try again.* | *That file could not be read as a shot list. Check that the first row has column names, then try again.* | Say what *structure* means |
| `Characters not in database: Mira, Selvi` | *Mira and Selvi are not in Characters yet. Add them?* | *Database* is not a place the writer knows |

## Empty states

What goes here, how it gets here, and one way to begin. No jokes, no illustrations, no guilt.

| String | Verdict |
|---|---|
| *No props yet. Tag them on the screenplay or in the Breakdown, or add one here.* | Model: names every route in |
| *No scenes yet. The estimated runtime appears here as the script grows.* | Model: says what will appear |
| *No cues yet, so nobody has spoken.* | Good: explains the cause |
| *Nothing covered yet. Tick lines on the page to make a shot.* | Good: one action |
| *Nothing by that name. Type a little more and you can add it yourself.* | Good: search that offers creation |
| *No saved changes recorded here yet* (Your work) | Model: never says the person has not worked (Decision 0036) |
| *No beats yet* (bare) | Add the route: *No beats yet. Open Writing to begin the story.*, as Kwark already says elsewhere |
| *Add words…* (empty outline card) | Model: replaced coaching prompts (Decision 0004) |

- **Never** write an empty state that implies failure (*You haven't written anything yet*).
- **Never** put a question or a writing prompt in an empty field.

## Confirmations

Prefer Undo to a question. Ask only when the action cannot be undone, or reaches other people.

- **Title is the question with the object**: *Delete Draft 3?*
- **Body says what is lost and what is kept**: *Its pages go. Your other drafts and the outline stay.*
- **Buttons are the answer**: *Delete draft* and *Cancel*. Never *Yes* and *No*.

| Now | Write | Why |
|---|---|---|
| *Are you sure you want to delete this draft?* | *Delete Draft 3?* · body: what goes · *Delete draft* | *Are you sure* doubts the person and tells them nothing |
| *Are you sure you want to merge 4 rows? This action cannot be undone.* | *Merge 4 shots into one? This cannot be undone.* · *Merge shots* | Shorter, names the object |
| *Are you sure you want to permanently delete this scene row?* | Move to trash with Undo instead; confirm only *Empty trash* | Recoverable actions do not need a question |
| Delete shots with a confirm | *Deleted 3 shots.* with Undo | Undo is kinder and faster |

## Toasts

A toast confirms what just happened, in the past tense, in one line, with an action only if the action is Undo or the obvious next step.

| Now | Write | Why |
|---|---|---|
| *Rev 2 issued. Save it as PDF to send it to the crew.* | Keep | Says what happened and the next step |
| *Mira is in, as Co-writer.* | Keep | Human, exact |
| *12 dates added. Each can be changed or removed.* | Keep | Reassures that a machine-made batch is editable |
| *Cover removed* with Undo | *Cover removed.* | Add the full stop; all toasts end with one |
| *Entry moved successfully* | *Entry moved.* | *Successfully* adds nothing |
| *Zoom optimized for sharing!* | *Zoom set for sharing.* | No exclamation marks |
| *Auto-generated 12 shots* | *12 shots added, one for each scene without a shot. Each can be changed or removed.* | Says what was made and that the person is in control |
| *Auto-linked Mira, Selvi* | *Linked Mira and Selvi to their cast.* | Name the result, not the mechanism |
| *Dedicated mode applied: Coverage* | *Now using the Coverage layout.* | Plain words |
| *Deleted property: Lens* | *Lens column removed.* with Undo | Name the thing as the person sees it |
| `New Location "Kitchen" added to database` | *Kitchen added to Locations.* | No *database*; sentence case |

- **Never** a toast for something the person can see happen.
- **Never** a toast that disappears while it holds an Undo the person has focused.

## Notifications

Kwark has no notifications that exist to bring people back, and it sends no email (Decision 0042). After inviting someone, the sharing panel offers *Copy invite* and *Email*, which opens the owner's own mail app.

- A rule for anything built: a notification must be about something another person did that the recipient needs to act on (*Selvi asked to join Blank Pages*), never about the recipient's own activity, streaks or absence.
- **Never** *We miss you*, *Keep your streak*, *You haven't written today*.

## First runs and onboarding

No tours, no coaching, no quizzes (Decision 0004). The first run is the work itself, with the way to begin one step away.

- **Say where the person is and what to do**: a heading and one primary action.
- **Ask a question only if the answer changes something**, and make it skippable. Dailies asks *What do you do on a film?* once, multi-select, skippable, editable later, and the answer never changes anyone's access.
- **Sign-in happens in place** and keeps any work made as a guest (Decision 0010).
- **Sharing explains itself in one line**: *Sharing works through Google accounts, so only the people you add can open it.*

## Settings

From the desktop-grade menus rule: anything chosen once and kept lives in Settings, labelled *This project* or *All your scripts*. Add only settings that change something.

- **A setting is a label and a one-line effect.** *Stronger contrast. Fuller ink and firmer lines, in whichever room.*
- **Say the privacy cost in the setting itself.** *Smart phonetic suggestions. Opt-in online dictionary suggestions while typing non-Latin words. Off by default: nothing you type leaves your device unless you enable this.*
- **Name the scope**: this project, all your scripts, this device.
- **Switches for things that stay on; radio items for one-of-several**, never a pile of checkboxes.

## Machine suggestions

When Kwark offers something it worked out, the words must say where it came from, why, and that nothing happens until the person says yes. See [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md).

The breakdown is the model:

- Heading: *The script mentions*
- Line under it: *Read off the page, never assumed. Nothing here counts until you say so.*
- Each suggestion: the words from the page (*Zippo*), its category, and the reason in words a person can disagree with: *Anything an actor handles has to be there on the day.* or *Set in capitals, the way an element is introduced.*
- Actions: *Add to the breakdown* (named *Add Zippo* for screen readers) and *Not needed* (named *Not a prop*).
- Count: *Suggestions waiting*, never *Suggestions missed*.

- **Never** *AI-powered*, *Smart* as a selling word, *magic*, sparkles, or a confidence percentage.
- **Never** a suggestion about the quality of the writing.

## Word list

| Use | Avoid | Why |
|---|---|---|
| Safe · Saved on this device | Synced, backed up (unless true) | Only what is true (0013) |
| Not saved yet | Failed, error | Never *failed* (0013) |
| Restore point | Snapshot, version, checkpoint | Decision 0015 |
| Room | Theme, skin, mode | Decision 0015 |
| Write · Prepare to shoot | Understanding, pre-production (as a label) | Decision 0009 |
| Move to trash · Remove | Delete (when it can be recovered) | Say what really happens |
| Delete | Remove (when it cannot be undone) | Say what really happens |
| Issue (a call sheet) · Rev 2 | Publish, send, v2 | Kwark sends nothing; film's own word |
| Reader · Co-writer · Director | Viewer, editor, admin | Film roles (0042) |
| Person · writer · crew | User, member | Name the person |
| Scene heading | Slug (in the interface) | Plain label; *slugline* is fine in docs |
| Characters · Locations · Breakdown | Database, records, table | Places the person knows |
| Add · Make | Create new, generate | Plain verbs |
| Could not · do not | Unable to, invalid, illegal | Calm, clear for second-language readers |
| Suggested · The script mentions | AI, smart, magic, auto- | Say the source, not the mechanism |
| About 1 h 42 min | Exactly, precisely (for estimates) | Estimates are estimates |
| Talk · Action | Talky, slow, weak | Measures, never judgement (0002) |
| Ask the project owner | Contact your administrator | Kwark has owners, not admins |

**Do:** *Scene moved to trash.* with Undo.

**Don't:** A dialog asking *Are you sure you want to permanently delete this scene?* with *Yes* and *No*.

**Do:** *That link has expired or was already used. Ask for a new one.*

**Don't:** *Invalid or expired reset link.*

**Do:** *The script mentions* · *Zippo* · *Anything an actor handles has to be there on the day.* · Add · Not needed

**Don't:** *AI found 14 props* with a sparkle, already added to the breakdown.

> **For agents:** - **Must** write buttons as verb plus object, in sentence case, and keep the same verb through the flow.
> - **Must** write errors as what happened, that the work is safe if true, and what to do.
> - **Must** write empty states as what goes here, how it arrives, and one way to begin.
> - **Must** prefer Undo to a confirmation; confirm only what cannot be undone or reaches other people.
> - **Must** give every machine suggestion its source, its reason and a way to say no.
> - **Never** write *Submit*, *OK*, *Yes/No*, *failed*, *invalid*, *successfully*, *database*, *Firebase*, or an exclamation mark.
> - **Always** check the word list before naming a new thing.

## AI readiness test

**Task:** Write every string for a new "Merge two scenes" action in the scene navigator for Scene 12 and Scene 13.

**Give the agent:** This page, Content, the Toast and Dialog components, the destructive actions pattern.

**Constraint:** Merging can be undone from the script's history but changes scene numbers on an issued call sheet.

**A reliable answer:**
- Menu item "Merge with next scene"
- Uses Undo for the merge, and a confirmation only because it reaches an issued call sheet
- Dialog names both scenes and says Rev 2 will be out of date
- Buttons "Merge scenes" and "Cancel"
- Toast in the past tense with Undo, no exclamation mark
