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.
- 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.
We could not reach the cloud just now. Your work is safe on this device and will go up when we can.
Cloud sync failed (unavailable). Please try again!
Crew call 06:30, Tue 18 Nov. Shoot day 3.
Call: 6:30 on 11/18 (Day 3)
Talk 62% · Action 38%, nothing more.
62% dialogue: a little talky for a thriller.
- 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