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

Source: https://kwark.space/designSystem/method/specs-and-handoff

## What a Kwark spec is

A spec is the agreed journey from [UX before build](https://kwark.space/designSystem/method/ux-before-build.md), 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](https://kwark.space/designSystem/patterns/print-and-export.md).
- **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](https://kwark.space/designSystem/foundations/ux-writing.md) 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](https://kwark.space/designSystem/agents/handoff.md).

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

**Do:** "Breakdown: select words on the page; they underline in Props' colour and the line appears on the breakdown sheet. Both print."

**Don't:** "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
