# Design-to-code handoff

> How Kwark hands a design to whoever builds it, a person or an agent - a spec that names components and tokens, covers phone and desktop, every state, every word, accessibility and edge cases, with a template to download.

Source: https://kwark.space/designSystem/agents/handoff

## What a handoff is for

A handoff spec lets someone build a screen without asking a question and without making a decision the designer did not make. In Kwark it comes after the journey and the wireframe have been agreed ([UX before build](https://kwark.space/designSystem/method/ux-before-build.md)), and it is the same document whether the builder is an engineer or an agent.

The difference from a typical handoff is that a Kwark spec rarely contains pixels. It names parts and roles: "Button, primary", "`--k-space-4`", "`--k-fs-title`". The component pages already hold the geometry. A spec that repeats it can only disagree with it.

**[Download the template (markdown)](https://kwark.space/designSystem/skills/kwark-handoff/template.md)**

## What goes in it

### The person and the problem

One sentence: who, in what situation, what gets in their way. Then the decision record it follows, or the draft of a new one. A builder who knows why makes better calls on the details the spec missed.

### The journey

Where the person comes from, each step, what they see, what they do, how they get back to the work. A spec without the journey produces a screen that works alone and breaks the flow it sits in.

### Layout, phone and desktop separately

- **Desktop at 1440** (and 1024): regions and the component for each.
- **Phone at 375** (and 320): the one header line (back, a one-word title, at most two labelled actions, Menu ▾), what fills the first 200px, the one floating control if any, rows without buttons.

A phone layout is not the desktop squeezed. It is a different arrangement of the same content: see [Phones](https://kwark.space/designSystem/patterns/phones.md) and Decision 0016.

### Parts and tokens

A table of each part, its component and variant, and the tokens it uses. If no component fits, write "new component" and describe it with tokens, then propose it ([Contributing](https://kwark.space/designSystem/contributing.md)).

### Every state

This is where specs most often stop short, and where agents most often invent. List them all: default, hover, focus, pressed, disabled (and why), loading, empty, error, offline, read-only for a shared viewer, long text, a script in an Indian language.

Kwark's own save word is a good example of how complete this has to be. The screenplay's corner pill has nine states, each with a fixed word, and the spec says which ones fade:

| State | Word | Stays or fades |
|---|---|---|
| Opening | Loading… | stays |
| Not on this device yet | Not downloaded | stays |
| In step with the cloud | Up to date | fades after 2.6 seconds |
| Typing | Edited | stays |
| Writing to storage | Saving… | stays |
| Stored | Saved | fades after 2.6 seconds |
| Stored here, not yet in the cloud | Saved on this device | stays |
| Not stored | Not saved | stays |
| Another session changed it | Changed elsewhere | stays |

Good news is worth a glance; anything the writer must act on stays visible (element register, Decision 0013).

### Copy

Every string exactly as it will ship, in Kwark's voice. No lorem ipsum and no "TBD": the words decide the layout as much as the boxes do. See [UX writing](https://kwark.space/designSystem/foundations/ux-writing.md).

### Saving, data and offline

What is saved, when, where (device, cloud), the word the person sees, and what happens if it fails halfway. Kwark runs on a free database tier, so the spec also says how many reads and writes an action costs and flags any list or listener with no limit.

### Accessibility

Keyboard path and shortcuts (⌘ on Mac, Ctrl elsewhere), the accessible name of every control without a visible word, focus order, where focus returns when a dialog or sheet closes, contrast in light, dark and the writing rooms, and what happens under reduced motion.

### Edge cases and out of scope

The cases with their expected behaviour, and what this deliberately does not do, so nobody builds it by accident.

### Open questions

Anything undecided, with the options and a recommendation, and who decides. A builder never fills a gap silently.

**Do:** "Empty: 'No scenes yet. Scenes appear here as you write headings.' One action: Write the first scene (Button, primary). Phone: same words, button full width."

**Don't:** "Empty state: TBD." or "Show a nice illustration and a call to action."

## Handing off to an agent

Everything above, plus three things agents need more than people do:

- **The files to load.** Name the `.md` twins of every component and pattern the spec uses, and `AGENTS.md`. See [AI context files](https://kwark.space/designSystem/agents/ai-context.md).
- **The limits, before the task.** "Only --k-* tokens. Only components in components.json. Do not change the desktop layout." An agent reads constraints given after the task as afterthoughts.
- **The checks it must run.** `audit_code` on each file if the [MCP server](https://kwark.space/designSystem/agents/mcp.md) is installed, screenshots at the four widths, and a list of what the system did not cover.

The [kwark-handoff skill](https://kwark.space/designSystem/agents/skills.md) writes a spec in this shape from a design description.

> **For agents:** When you receive a Kwark handoff spec: build exactly the states and strings listed; if one is missing, stop and ask rather than inventing it. Use the components named. If a part says "new component", build it with --k-* tokens only and say that it needs a component page.

## Acceptance checks

The spec ends with the checks a reviewer will run, so the builder can run them first:

- Tokens only: no hex, rgb, px font sizes or font names.
- Shared components; every control has a word or a named icon; chevrons on things that open.
- Screenshots at 1440, 768, 375 and 320, looked at.
- Every listed state exists, with the listed words.
- Keyboard and screen reader pass.
- Decision record and element register updated.

## AI readiness test

**Task:** Write the handoff spec for the "Issue call sheet" action, which locks a call sheet and gives it a revision number.

**Give the agent:** This page, the template, Patterns: destructive actions, Patterns: phones.

**Constraint:** Name components and tokens, no pixel values. Fill every section of the template.

**A reliable answer:**
- Starts with the person (the 1st AD) and the problem in one sentence
- Gives phone and desktop separately
- Lists states including offline and read-only
- Writes the real copy (Issue call sheet, Issued, revision numbers)
- Says what is saved and what happens if it fails halfway
- Lists open questions instead of deciding them silently
