Kwark. Design System
Open Kwark

Specs and handoff

How a Kwark feature is specified so that anyone can build it, phone first, with every state and every word written, and with the paper artefact and the digital one designed as one act.

Kwark method
PaperThe call sheetDAY 3 OF 12 · CREW CALL 06:30
SC 12 · INT. EDIT SUITE – NIGHT
Draft, not issued
DigitalThe same sheet, structuredMatches Rev 2. PDF and CSV are ready.

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 bare max-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.md whenever work stops: what was done, where it stopped, the next step.
  • Must append an entry to ~/AIContext/log.md in 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.md in the main checkout: it is stale. The September stylesheets and styles/tokens.css are 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.”

Do

“Breakdown: a table with columns for scene, category and item.”

Don’t

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

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

Open .mdllms.txt
Loading…