Kwark. Design System
Open Kwark

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.

Foundations
Scene moved to trash.

No props yet. Tag them on the screenplay or in the Breakdown, or add one here.

How to use this page

Content 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.

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

Scene moved to trash. with Undo.

Do

A dialog asking Are you sure you want to permanently delete this scene? with Yes and No.

Don’t

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

Do

Invalid or expired reset link.

Don’t

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

Do

AI found 14 props with a sparkle, already added to the breakdown.

Don’t
  • 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

Give this Markdown to your coding agent or share its URL.

Open .mdllms.txt
Loading…