What these are for
Kwark’s mission is short: help people who want to write feel calm, begin writing and keep writing, then help the same people take that work into production. Every principle below protects one half of that sentence. They are not values to put on a wall. Each one has already decided a real argument in the app, and each one is recorded in a decision (docs/ux/decisions) that says what evidence would make us change it.
Read a principle as a test you can run on a screen. If a screen fails it, the screen changes, not the principle.
The specimen above is what the principles sound like in practice. Cmd+S says Saved. Your script saves as you write. (Decision 0014). The sync word says Safe before it says anything else (Decision 0013). The app never says failed to a writer.
The writer first
The rule. Empathy for the person using Kwark outranks every other consideration: ours, a competitor’s, a producer’s, the tidiness of the code.
Why. A writer sitting down to write is often unsure and sometimes afraid. The product’s first job is not to add to that. Calm is a measurable property of a screen, not a mood.
What it changes. Every review starts with the empathy checklist from How we decide: who is this for and what were they doing a minute ago; what are they afraid of right now; what is the smallest thing that helps; what are we making them look at that is not their work; what can they not undo.
In the app. Writers press Cmd+S out of habit. It used to make a snapshot, which cluttered the history and reassured nobody. Now it shows Saved. Your script saves as you write., and restore points moved to Cmd+Shift+S (Decision 0014). The habit is honoured instead of corrected.
The trade-off it settles. Habit against model purity. The “correct” model says autosave makes Cmd+S meaningless. The writer’s hands say otherwise. The writer wins.
A safe, private place
The rule. Nothing public, ranked or compared inside Kwark. No competitions, leaderboards, public counts, badges that compare people or marketplaces (Decision 0001). Anything social belongs on Bekwarky, a separate site.
Why. A writer who feels watched writes less, or not at all. People bring dream projects here.
What it changes. Private by default. New collaborators join as Readers, and the request link is off until the owner turns it on (Decision 0042). Personal features may exist only when they face inward: a rhythm only the writer can see is allowed; a public word count is not.
In the app. The Home writing-rhythm widget had a flame and Goal reached. It was a streak in disguise, counting a nervous writer the moment they arrived. It was turned off by default and moved to Settings with no flame, no streak and no resets (Decision 0008), then replaced by Your work: a private list of recently saved work with a link back, hidden until opened, with no totals, rings, targets or congratulations (Decision 0036).
The trade-off it settles. Engagement against safety. Streaks bring people back; they also make missing a day feel like failing. Kwark gives up the retention trick.
Measure the work, never judge it
The rule. Kwark never scores, grades, critiques or rewrites a person’s story, by machine or by metric (Decision 0002). It may help them see the work: runtime, pages, talk against action. It never says the work is good or bad.
Why. We would be grading people’s stories with a machine we cannot defend to a producer or to the writer. Competitors sell AI coverage; that is not a reason.
What it changes. A number must describe, not evaluate. Runs about 1 h 42 min is a measurement. A green tick beside a “healthy” runtime is a verdict. The question to ask of any figure: does it measure the work, or rate it?
In the app. The timeline shows each scene’s estimated length and whether it is mostly dialogue or mostly action, and the balance card says Talk 62% · Action 38%, with no target range and no colour for good or bad. The idea module’s Conviction % and the outline’s trophies were recorded as deviations to remove.
The trade-off it settles. Helpfulness against authorship. Some writers would like a verdict. Kwark refuses to give one, and gives them a clear look at their own work instead. See AI and authorship.
Nothing compulsory
The rule. Every structure-aware feature (beat sync, the outline rail, act assignment, breakdown tags, targets, rhythm) is opt-in and can be switched fully off at any time (Decision 0003). A switch that cannot turn a feature fully off is a bug.
Why. Some writers want an outline wired to the page. Some want an empty page. Forcing the outline degrades the writer who just wants to write.
What it changes. Features are designed off first, then given a switch. Turning a feature off must leave nothing behind on the page: no empty rail, no faded markers, no “you turned this off” banner.
In the app. The ⟷ after an act name means this act is linked to the outline. It sits beside the act name, takes no line and never prints (Decision 0041). With linking off it is not there at all.
The trade-off it settles. Discoverability against freedom. An off-by-default feature is found by fewer people. Kwark accepts that, because a feature that is forced on loses the writer it was not built for.
Structure, not teaching
The rule. Every field feeds a real artefact: a list, a sheet, a date, a cost. No coaching prompts, theory engines, quizzes or “meanings” (Decision 0004).
Why. Kwark’s people are part-time filmmakers. They need working structure, not film school. Teaching patronises and clutters.
What it changes. Before adding a field, name the artefact it ends up in. If the answer is “it helps them think”, the field does not ship.
In the app. Empty outline cards used to ask questions by story position (“What does an ordinary day look like before anything changes?”). They were coaching inside a field. An empty card now says Add words… (Decision 0004, history, 4 November 2026). The Enneagram quiz, tension sliders and camera “meaning” engines are listed as deviations.
The trade-off it settles. Guidance against respect. A beginner might like prompts. The page treats them as a filmmaker anyway, and the help they get is a structure that works.
Paper and digital as one act
The rule. Where film already has a paper artefact (the marked-up script, the breakdown sheet, the stripboard, the call sheet), the digital version is that artefact, built in the same act, not a table beside it (Decision 0005).
Why. A crew already works from paper. A table alone is not something a crew will accept on set.
What it changes. Print and PDF are first-class, designed with the screen, not exported as an afterthought. Every script-bound module answers “what paper thing does this replace, and can it print?”
In the app. The screenplay page on screen is the printed page, measured: dialogue wraps at 33 characters as Highland’s printed pages do, cues sit where the PDF puts them, and nothing appears on screen that the PDF does not have (Decision 0041). Issuing a call sheet makes a numbered revision and says Rev 2 issued. Save it as PDF to send it to the crew. (Decision 0020).
The trade-off it settles. Freedom of screen design against trust. A screen-only layout could be prettier. If the screen and the PDF disagree, the writer stops trusting the page count, so the screen gives way.
Competitors are the floor
The rule. Parity with Final Draft, Highland, Celtx or Arc Studio is the minimum, never the reason. Every plan leads with what no competitor does: one script feeds everything (Decision 0006).
Why. Chasing parity makes Kwark a worse copy of someone else.
What it changes. A feature request that starts “X has it” is sent back to step one: name the person, the situation and the problem. Competitors set the quality bar for what Kwark already does; menus must feel at least as professional as Final Draft’s (five menus, Decision 0015).
In the app. The breakdown is read off the script, the schedule from the breakdown, the call sheet from the schedule and the budget from the cast and locations (Decision 0022). Nobody retypes a scene.
The trade-off it settles. Familiarity against direction. Kwark matches the conventions writers know (Tab cycles elements, scene numbers, revision colours) and spends its invention where competitors stop.
Honest and quiet
The rule. Say what is true, in plain words, calmly. Tell the state first; then what happened; then that the work is safe, if it is; then what to do (Decision 0013). Never failed.
Why. When something goes wrong, the writer’s first fear is for their work. Raw errors and An error occurred make that fear worse and give them nothing to do.
What it changes. Library text never reaches a person. friendlyError() turns every Firebase code into one calm sentence and replaces anything it does not recognise with Something went wrong. Your work is safe; please try again. Words are checked against the test: would we say this out loud to a nervous writer?
In the app. The corner sync word reads Safe, Safe here, waiting to reach the cloud or Safe on this device (offline by choice). Characters and Story locations say Saved on this device after a local write, which makes no cloud claim, and offer Retry saving if a write could not be stored (Decision 0013, history).
The trade-off it settles. Precision against calm. Engineers want the real error text. Writers need the state. The real text goes to the console; the writer gets the truth in their own words. See Content.
Their work is never at risk
The rule. Autosave, undo, recoverable trash, honest sync state and tested backups. A feature that can lose work does not ship.
Why. A phone that opened a light project card once saved a placeholder over ten real pages. Data loss became priority one.
What it changes. Every feature answers the work-is-safe test: if this fails, loses connection or is interrupted halfway, what happens to the writing? Prefer Undo to “Are you sure?”. Deleting moves to trash. Every screenplay save carries a revision stamp, and a save that would overwrite a newer copy from another device is refused and kept for recovery.
In the app. A character edit that cannot be stored keeps the page open: This change has not saved yet, so the page stays open. A copy is kept on this device. Back waits for the local save.
The trade-off it settles. Speed against safety. A save that waits, a page that stays open, a conflict banner: each costs a moment. None is negotiable.
Everything has a meaning
The rule. Every small thing on screen that carries meaning (a dot, a badge, a count, a colour, an edge, an icon with no label) has a row in the element register: what it means, when it appears, what the person should do about it, and why it earns its place. A dot with no reason is removed.
Why. Unexplained marks make people wonder whether they did something wrong. One mark meaning two things is worse.
What it changes. A new mark needs a register row before it ships. One mark, one meaning: on the story spine a dot is a beat, nothing else (Decision 0031). On the timeline, the 2px ring in the project’s colour means the scene the caret is in, and so does the pointer above it (Decision 0041).
The trade-off it settles. Richness against clarity. Designers like to add signals. Each one costs attention, so each one has to justify itself in writing.
One job, one look
The rule. From docs/design-system.md:
- If two things look different but do the same job, one of them is wrong.
- If it is clickable, it is a button (the shared
ButtonorIconButton). - A component does not choose its own colour, font, size or spacing; it takes them from the tokens.
- Content a writer chooses (fonts in the reader, rooms in the editor) is not interface and may differ; everything else is the system.
Why. Inconsistency is a tax on every screen: people relearn the same control in each module. It also makes the product look unfinished, which costs trust.
What it changes. Before building, check the shared components. The build counts hard-coded colours, fonts and sizes per file and fails when a file gets worse. Old code moves to the system when someone touches it.
In the app. The unified breadcrumb and dropdowns replaced several look-alike versions across modules (Decision 0044). Rooms are allowed to differ because a writer chose them; a module that invents its own grey is not.
The trade-off it settles. Local polish against coherence. A module may break the pattern where the craft asks for it (Research may feel like research), but the exception is recorded, never accidental.
Content first, especially on a phone
The rule. On a phone, one 44px header line, content by about y = 200, rows without buttons, one floating control (Decision 0016).
Why. A phone screen is small and the work is the point. Breadcrumbs, subtitles and rows of chips above the fold push the work out of sight.
What it changes. Above the fold: the header and at most one 40 to 48px band. Secondary actions go into the row’s ⋯ sheet. Comments, Quick note and Account are items of the one floating dial. See Phones.
In the app. The phone timeline rests as a 22px strip under the menu; slide a thumb to scrub, tap to open, turn the phone sideways for a full-screen bay (Decision 0007).
The trade-off it settles. Reach against room. Fewer controls are visible at once; everything is still one tap away.
Flat and legible
The rule. No glows, gradients, blurred blobs, sparkles or decorative light. Depth is a line and a step in tone. Shadows only for things that float.
Why. Writers spend hours in the editor. Their reference points (Final Draft, Highland, WriterSolo, Fade In) use flat desks. Glow pulls the eye from the words and costs contrast.
What it changes. The editor’s rooms lost their light layer; the timeline’s current scene lost an 18px glow, a brightness filter and six rising particles (Decision 0041). The founder removed the modal’s accent glow and asked for no lighting glow anywhere in the app.
In the app. Each room keeps its desk, paper, ink and pencil and nothing else. See Writing rooms.
The trade-off it settles. Atmosphere against seriousness. If writers ask for the atmosphere back, it returns as an opt-in room, never the default.
Works for everyone, everywhere
The rule. Phones as well as laptops; keyboard and screen reader; slow or no network; Indian scripts; unions and paperwork that differ by country.
Why. Kwark’s people include students from 13 up, indie crews on short shoots, and writers whose characters speak Tamil or Hindi. A product tested only on a fast laptop in English fails most of them.
What it changes. The everyone test runs on every screen: phone, tablet, laptop; keyboard only; screen reader; offline; a script in Tamil; a user in another country. See Accessibility, Inclusive design and Writing systems.
In the app. Typing a character’s lines in their own script on an English keyboard happens on the device, with nothing sent anywhere. Money is written the way its own people write it: ₹12,50,000 in India.
The trade-off it settles. Speed of shipping against reach. Some features ship later because they must work on a phone and offline first.
A problem before a feature
The rule. Nothing a person will see is built until the need, the journey and a phone-first wireframe are agreed. “A competitor has it” is not a need.
Why. Features built from a guess add surface without helping anyone, and every surface costs calm.
What it changes. The order of work in UX before build. Every decision record ends with What would make us remove it; a feature that cannot be removed is a liability.
In the app. The AI storyboard pack was agreed as an idea on 29 September 2026, but it is not built: its journey still needs the founder’s agreement.
When principles pull apart
The decisions so far show how conflicts have been settled. Use them as precedent.
| Conflict | How it was settled | Record |
|---|---|---|
| A private rhythm helps some writers; any count can feel like judgement | Off by default with no flame or streak, then replaced by a private record of saved work that counts nothing | 0008, 0036 |
| Room atmosphere against a flat, serious page | Flat by default; atmosphere only as an opt-in | 0041 |
| Real error text (precision) against calm | Calm sentence for the person; detail in the console | 0013 |
| Teaching beginners against respecting filmmakers | No coaching in fields; any teaching would be a separate opt-in place | 0004 |
| Feature parity against direction | Parity is required, never the lead | 0006 |
| Speed of a save against certainty | The page waits for the local save | 0013 history |
When a new conflict is not covered, do not guess. Write down two or three options with their costs, recommend one, and let the founder decide.
Measure and show: Scene 12 · INT. EDIT SUITE – NIGHT · 2:40 · mostly dialogue. The writer decides what it means.
Judge: a red bar on Scene 12 because it is “too long”, a pacing score, or a tip on how to fix Act 2.
Hidden until the person opens it, private, counting nothing: Your work, with No saved changes recorded here yet when it is empty.
On for everyone, a flame on Home, Goal reached after 500 words and a streak that resets.
- Must run the calm test on anything you add: does it count, grade, warn, nag or ask for attention it has not earned?
- Must name the real artefact (a sheet, a list, a date, a cost) every new field feeds.
- Must make every structure-aware feature switchable fully off.
- Never score, grade, rank or judge a person’s writing, or show a “good range” beside a measurement.
- Never add social, public or comparative features inside Kwark.
- Never justify a change with “a competitor has it”.
- Always cite the decision record a rule comes from, and propose a new record when you change a rule.
AI readiness test
Task. Propose a “progress” panel for the project overview of Blank Pages, the demo project.
Give the agent. This page, decisions 0001, 0002, 0003, 0008 and 0036, the element register.
Constraint. Show the writer where the work stands without counting, grading or comparing them.
A reliable answer
- Measures only (pages, scenes, estimated runtime) with no target colours or verdicts
- No streaks, goals, flames or percentages of “done”
- Off or quiet by default, and switchable off
- Every number has a register row saying what it means
- Cites the decisions it follows