What a Kwark spec is
A spec is the agreed journey from UX before build, made exact enough that a different person or agent can build it without asking. It is short. It lives in docs/ux/proposals/ while it is being agreed and becomes the decision record once it is.
The parts of a spec
| Part | What it must say |
|---|---|
| Need | One sentence: the person, the situation, the problem |
| Paper artefact | What the industry already prints for this job, and how the screen becomes it |
| Journey | Each step in order, for each role that meets it |
| Screens | Phone first, then tablet, laptop and wide |
| States | Every state in the table below |
| Words | Every label, button, hint, error, empty state and toast, written out |
| Data | What is stored, where, and the reads and writes per action |
| Access | Who can see and change it; what a read-only person sees |
| Out of scope | What this does not do, named |
| Remove it | The evidence that would make us take it out |
Paper and digital, one act
Decision 0005. A crew already works from stripboards, call sheets and breakdown sheets; a table alone is not something a crew will accept on set. For every module bound to the screenplay, Kwark builds the artefact a crew already makes by hand and the thing software can do, as a single act. The founder: “they can break it down conventionally, and also have more structured view, and print them both out as and when needed”.
| Job | The paper way | Built in Kwark as |
|---|---|---|
| Breakdown | The AD marks the script pages with coloured pencils, then copies onto a sheet | Select words on the real script page; they underline in the department’s colour and the sheet line is written. Either prints. |
| Shot list | A lined script: a vertical line down the margin beside the lines a setup covers | Drag down the margin; that is the shot. The list and the coverage gaps follow from it. |
| Schedule | Paper strips on a board | Strips on a board, already |
| Call sheet | A printed one-page sheet | A paper facsimile that issues numbered revisions with PDF and CSV (Decision 0020) |
- Must name the paper artefact a feature replaces before designing it, and make that the interaction, not a view beside it.
- Must make it print. See Print and export.
- Never ask a director to design a schema before saying where the camera goes. That is what made the old shot list “weird”.
Phone first
Draw at 375 wide first, then check 320. Kwark’s screen spec (docs/ux/screens-and-input-spec.md) names four rooms by situation, not by pixels:
| Room | When | Layout |
|---|---|---|
| Phone | Narrower than 768, or a touch screen shorter than 520 (a phone on its side) | One column, one 44px header, bottom sheets |
| Tablet | 768 to 1023 | Desktop chrome, narrower rail, panels over the page |
| Laptop | 1024 to 1439 | Full chrome, one panel beside the page |
| Wide | 1440 and up | As laptop; the script never stretches past its page width |
Input is separate from size. Ask the pointer, not the width: fingers get 44px targets and nothing hover-only or drag-only; a mouse may get hover tips and 32px targets; the keyboard is always supported. A tablet with a keyboard is both.
- Must use the shared compact query in the screenplay (
useEditorLayout()), never a baremax-width: 767px, so a phone held sideways gets the phone layout. - Must start the person’s content by about y = 200 on a phone, aiming for y≈120 (Decision 0016).
Every state
A spec that shows only the full, happy screen is not finished.
| State | Example from Kwark |
|---|---|
| Empty | “No call sheets yet. A call sheet is made for each shooting day, and the days are built from the screenplay’s scenes.” |
| Loading | “Opening the script…” |
| Saved | “Saved”, then the word steps back after a moment |
| Offline | “Saved on this device” |
| Not downloaded | “This screenplay has not downloaded to this device. Nothing will be saved until it does.” |
| Conflict | “This screenplay was changed in another session. Your edits are kept on this device and have not overwritten it.” |
| Error | One calm sentence from friendlyError(): what happened, that the work is safe, what to do |
| Read-only | What a Reader sees, and why a control is disabled, written on the page |
| No access | “{Owner} hasn’t shared {module} with you.” |
| Too much | 400 scenes, a 90-character location name, a Tamil character name |
Words are part of the spec
- Must write every string in the spec. Copy is designed, not filled in at the end.
- Always use one word for one thing through the flow: Issue, Issued, Rev 3.
- Always read each sentence aloud to a nervous writer (the honest-copy test).
See UX writing for the voice.
Handoff between people and agents
Kwark’s work moves between Claude, Codex, Antigravity and the founder, often mid-task. A handoff is part of the work, not a courtesy.
- Must update the State section at the bottom of
docs/ux/HANDOFF.mdwhenever work stops: what was done, where it stopped, the next step. - Must append an entry to
~/AIContext/log.mdin the form## YYYY-MM-DD HH:MM — tool/account — project. - Must say what was verified and how (“checked at 1440, 768, 375 and 320 in the preview; not on a real phone”), and what was not.
- Always include a prompt the next agent can paste to resume, with the paths it must read first.
- Never leave work only in chat.
See also Handoff for agents.
Rules
- Must include need, paper artefact, journey, screens, states, words, data, access and out-of-scope in every spec.
- Must draw the phone layout first.
- Must specify the empty, loading, offline, error and read-only states.
- Never spec from
DESIGN_SYSTEM.mdin the main checkout: it is stale. The September stylesheets andstyles/tokens.cssare the look. - Always write the reads and writes per action beside the data.
“Breakdown: select words on the page; they underline in Props’ colour and the line appears on the breakdown sheet. Both print.”
“Breakdown: a table with columns for scene, category and item.”
AI readiness test
Task. Write the spec for a costume continuity sheet.
Give the agent. This page, Decision 0005, Print and export, Review and quality.
Constraint. Phone first; every state; every string.
A reliable answer
- Names the paper artefact (the continuity sheet with photos per scene and character) and makes it the interaction
- Lists empty, loading, offline, error and read-only states with real copy
- Draws 375 before desktop
- Gives reads and writes per action and stores photos in Storage, not base64 in a document