# Content

> Kwark's voice and tone: calm, plain and film-literate. How Kwark talks about saving and errors, the film words it uses and how, capitalisation, numbers, dates and times for crews, and names and roles.

Source: https://kwark.space/designSystem/foundations/content

## The voice

Kwark sounds like a calm, experienced colleague in the production office: someone who knows the craft, says what is true in as few words as it takes, and never makes you feel stupid or watched.

The test, from principle 9 (*Honest and quiet*): **would we say this out loud to a nervous writer?** If a sentence would sound odd spoken across a table, it is wrong on screen.

| Kwark is | So it | And never |
|---|---|---|
| Calm | States the state first, then what to do | Alarms, shouts, uses red for anything that does not block work |
| Plain | Uses short, common words and full sentences | Uses jargon, internal names or library text |
| Honest | Says only what is true, including *on this device* when the cloud is not involved | Claims something is saved, synced, sent or safe when it is not |
| Film-literate | Uses the industry's words, correctly | Invents cute names for things crews already have names for |
| Respectful | Treats every person as a filmmaker | Coaches, praises, jokes or judges the writing |
| Private | Talks to the person alone | Compares them with anyone, or tells others what they did |

> Kwark's people include students from 13 and producers with twenty films. Write for both at once: a bright 14-year-old and a working line producer should each read the sentence as written for them. Short, correct and kind does that. Slang, jokes and simplifications do not.

## Tone changes with the moment

The voice stays the same. The tone follows what the person is doing.

| Moment | Tone | Kwark says |
|---|---|---|
| Writing | Silent. The page is the only thing talking | Nothing, unless asked |
| Pressing ⌘S out of habit | Reassuring, one line | *Saved. Your script saves as you write.* (Decision 0014) |
| Waiting for the network | Matter of fact | *Safe here, waiting to reach the cloud* |
| Something could not be stored | Steady, specific, one action | *This change has not saved yet, so the page stays open. A copy is kept on this device.* |
| Letting someone in | Warm, plain | *Mira is in, as Co-writer.* |
| Production paperwork | Exact, crew-ready | *Rev 2 issued. Save it as PDF to send it to the crew.* |
| Removing something | Clear about what goes and what stays | *Scene moved to trash.* with Undo |
| No access | Neutral, never accusing | *You do not have access to this. Your work is safe; ask the project owner if you need it.* |

## The voice of saving and sync

Decision 0013 sets the order for every message about a person's work: **the state first**; then what happened; then that the work is safe, if it is true; then what to do. Never *failed*.

| State | Words | Notes |
|---|---|---|
| Everything is up to date | *Safe* | The corner sync word |
| Changes are waiting | *Safe here, waiting to reach the cloud* | Not an error. No red |
| Offline by choice | *Safe on this device (offline by choice)* | After *Work offline* |
| Local write succeeded | *Saved on this device* | Makes no cloud claim (Decision 0013, 4 November) |
| In progress | *Saving…* | One ellipsis character |
| A write did not land | *Not saved yet*, with *Retry saving* | The page stays open; Back waits |
| Read-only because nothing is loaded | *The screenplay has not finished loading on this device.* | Never let a half-loaded script save |

Every error from Firebase passes through `friendlyError()`, which turns codes into one calm sentence and replaces anything it does not recognise with *Something went wrong. Your work is safe; please try again.* Raw library text never reaches a person.

> **For agents:** - **Must** say the state before the problem, and say *safe* only when the work really is safe.
> - **Must** say *on this device* when nothing has reached the cloud.
> - **Never** show the words *failed*, *error occurred*, *sync error*, *Firebase* or a code to a person.

## Film words, used correctly

Kwark's people work in film; its words should be the words on a real set. Use the industry term where one exists, and use it exactly. Where the screen label is plainer than the trade word, the table says so.

| Term | Means | In Kwark |
|---|---|---|
| Scene heading (slugline) | The line that opens a scene: *INT. EDIT SUITE – NIGHT* | Labelled *Scene heading* in the element menu; "slugline" is fine in help and docs |
| Action | What we see and hear | *Action* |
| Character cue (cue) | The speaker's name above dialogue | *Character* in the element menu; *cue* in docs |
| Parenthetical | Direction in brackets under a cue | *Parenthetical* |
| Transition | *CUT TO:*, *DISSOLVE TO:* | *Transition* |
| Dual dialogue | Two characters speaking at once, side by side | *Dual dialogue* (⌘⇧D) |
| Act, sequence, beat | Structure, from largest to smallest | Optional (Decision 0003). Never "plot point" scoring |
| Eighths | Page length in eighths of a page, the way schedules count | *1 4/8* pages |
| Breakdown | Tagging what each scene needs: props, wardrobe, vehicles | *Breakdown*; suggestions under *The script mentions* |
| Stripboard, strip | The schedule as coloured strips, one per scene | Strips coloured by INT/EXT and DAY/NIGHT |
| Shooting day | A day of the shoot | *Shoot day 3*; *Shooting days* on the planner |
| Call sheet | The day's sheet for cast and crew | Issued as numbered revisions (Decision 0020) |
| Call time, crew call | When people must arrive | *Crew call*, per person *call* |
| Wrap | End of the day's shoot | *Wrap* |
| Recce | Visiting a location before the shoot | *Recce*, a calendar category (Decision 0043) |
| Table read | Reading the script aloud with the cast | *Table read* |
| Dailies | The day's footage; in Kwark, the private record of a person's work days | *Dailies* (Decision 0043) |
| Top sheet | A budget's one-page summary | *Top sheet* |
| Revision | A changed, reissued version | *Rev 2*; *Changed since Rev 2* |

Two Kwark names to keep exactly:

- **Write** and **Prepare to shoot**, the two halves of a project (Decision 0009). *Understanding* is a code name only; never show it.
- **Room**, for the editor's look (Decision 0015). Not *theme*, *skin* or *mode*.

**Words that mean judgement in film are not Kwark words.** *Coverage*, *notes* in the sense of a reader's verdict, *pass*, *consider* and *recommend* describe someone grading a script. Kwark never does that (Decision 0002), so its interface never uses them about the writer's work. *Coverage* in the camera sense (the shots that cover a scene) is fine in the shot list.

## Capitalisation

- **Sentence case everywhere** in the interface: buttons, titles, menus, labels, tabs. *Prepare to shoot*, not *Prepare To Shoot*.
- **Screenplay elements are capitalised by convention** and only on the page: scene headings, cues, transitions, and a new element introduced in action (*he flicks a chipped ZIPPO*). The interface never borrows this.
- **No all-caps labels** in the interface, and no small-caps eyebrows.
- **Proper nouns**: Kwark, Bekwarky, Blank Pages (the demo project), Final Draft, Highland.
- **Role names** are capitalised when they are the role in the sharing panel (*Reader*, *Actor*, *Co-writer*, *Director*, *Producer*, *Camera*, *Crew*, *Custom*) and lower case in a sentence about the job (*ask the director*).
- **Keys** as the keyboard shows them: ⌘S on a Mac, Ctrl+S elsewhere; Esc, Tab, Enter.

## Numbers

- **Numerals for every count**: *3 scenes*, *12 shots*, *1 character*. Spell out nothing for the sake of style.
- **Scene numbers as written**: *Scene 12*, *Scene 12A*. Never *Scene #12* or *Sc. twelve*.
- **Revisions**: *Rev 2*, never *Revision #2* or *v2*.
- **Page length in eighths**: *1 4/8 pages*.
- **Runtime as a person says it**: *about 1 h 42 min*, *2 min 40 sec*; on the timeline, a clock: *2:40*. Always *about* for an estimate.
- **Percentages only for measures**: *Talk 62%*. Never a percentage of how "good" or "done" something is.
- **Money as its own people write it**: *₹12,50,000* in India (lakh grouping), *$125,000* in the US. Show the currency symbol; budgets default to rupees and offer eight currencies.
- **Plurals by count**: *1 row*, *2 rows*. Never *row(s)*.

## Dates and times for crews

A call sheet is read at 5am by someone who has just woken up. Times and dates must be impossible to misread.

- **Always the weekday with the date** on anything a crew acts on: *Tue 18 Nov*. The weekday catches the wrong-date mistake.
- **Never all-numeric dates** in the interface (*11/12* is November or December depending on the reader).
- **Times as the device shows them** (24-hour or 12-hour by the person's locale), with *am* and *pm* when 12-hour. The calendar's examples use 24-hour (*19:30–21:00*), which is the default on Indian and European sets.
- **Name the time zone** when the shoot is somewhere else from the person reading.
- **Days of the shoot**: *Shoot day 3*. When the schedule knows the total, say it: *Shoot day 3 of 18*.
- **Relative words only when they cannot be misread**: *today* and *tomorrow* in a toast are fine; *next Tuesday* on a call sheet is not.
- **Sunrise and sunset** on a call sheet are times for that location and date, labelled *Sunrise* and *Sunset*.

## Names and roles

- **The character, not the actor.** In Write, *Mira* is the character. The actor who plays her is named in casting and on the call sheet. Never mix the two in one label.
- **People's names as they give them.** Do not split names into first and last, do not assume a family name, and do not abbreviate. Some people have one name.
- **Display name and legal name** are separate where the paperwork needs a legal name (contracts, crew lists). Show the display name everywhere else.
- **Never assume gender.** Write *they* when you do not know, or use the name again.
- **Name people only where it was chosen.** Whether someone's name appears on the project page is set per person in the sharing panel (Decision 0042); never add names to a surface that did not ask.
- **Roles are about access, not identity.** *Reader* is what someone can do in this project, not who they are.

## Writing for every reader

- **Short sentences.** One idea each. A second-language reader and a tired reader both thank you.
- **Full forms in errors.** *Could not* and *do not* read more calmly than *couldn't* and *don't*, and translate more safely. Contractions are fine in friendly, low-stakes lines.
- **No idioms or metaphors** a translator or a 13-year-old would trip on.
- **No exclamation marks.** Calm has none.
- **No emoji** in the interface.
- **British or American spelling**: the app's strings are mixed today (*colour* in Kwark's own words, *Localised* in Settings). Keep one spelling within a screen, and match the screen you are editing.

**Do:** *We could not reach the cloud just now. Your work is safe on this device and will go up when we can.*

**Don't:** *Cloud sync failed (unavailable). Please try again!*

**Do:** *Crew call 06:30, Tue 18 Nov. Shoot day 3.*

**Don't:** *Call: 6:30 on 11/18 (Day 3)*

**Do:** *Talk 62% · Action 38%*, nothing more.

**Don't:** *62% dialogue: a little talky for a thriller.*

> **For agents:** - **Must** write in sentence case, short sentences, no exclamation marks and no emoji.
> - **Must** use the film terms in the table above exactly, and *Write*, *Prepare to shoot* and *Room* as Kwark's names.
> - **Must** put the weekday with any date a crew acts on, and never write an all-numeric date.
> - **Must** keep the character's name and the actor's name apart.
> - **Never** use judgement words (*coverage* of a script, *pass*, *weak*, *strong*, *good*, *score*) about a person's writing.
> - **Never** praise, coach or joke.

## AI readiness test

**Task:** Write the messages for issuing a revised call sheet for Shoot day 3 of Blank Pages after the crew call moves from 06:30 to 07:00.

**Give the agent:** This page, UX writing, decision 0020, the Toast component.

**Constraint:** The crew may read it on a phone at 5am; Kwark sends no email.

**A reliable answer:**
- Names the revision (Rev 3) and what changed (crew call 07:00) with weekday and date
- Tells the person how to send it (Save it as PDF) without claiming Kwark sent anything
- Sentence case, no exclamation marks, no blame
- Uses Shoot day 3 and Crew call exactly
