# Handoff: <screen or feature name>

- **Decision record:** NNNN (follows) or new (draft attached)
- **Designer:** <name> · **Builder:** <name or agent> · **Date:** YYYY-MM-DD
- **Status:** Draft | Agreed | Built | Reviewed
- **System version:** Kwark Design System v4.0 (https://kwark.space/designSystem)

## 1. Person and problem
One sentence: who, in what situation, what gets in their way.
What happens to them if we do nothing.

## 2. Journey
Where they come from, each step, what they see, what they do, how they get back to the work.
1. ...
2. ...

## 3. Layout
### Desktop (1440, and 1024)
Regions, top to bottom and left to right. Name the component for each part.

### Phone (375, and 320)
- Header: back · <one-word title> · <at most two labelled actions> · Menu ▾
- First 200px: <what the person came for>
- Floating control: <the one control, or none>
- Rows: whole row is the target; secondary actions in the row's ⋯ sheet

## 4. Parts
| Part | Component | Variant / props | Tokens |
|---|---|---|---|
| Primary action | Button | primary | --k-accent, --k-on-accent |
| ... | | | |

New component needed: <none, or a description using tokens only>

## 5. States
| State | What the person sees | Copy |
|---|---|---|
| Default | | |
| Hover / focus / pressed | | |
| Disabled | Why it is disabled | |
| Loading | | |
| Empty | What goes here, why, one action | |
| Error | What happened, the work is safe, what to do | |
| Offline | | |
| Read-only (shared viewer) | | |
| Long text (INT. EDIT SUITE – NIGHT – CONTINUOUS) | | |
| Indian script (Hindi, Tamil) | | |

## 6. Copy
Every string, exactly as shipped. Buttons verb + object, sentence case, the same word through the flow.

## 7. Saving, data and offline
- What is saved, when, and where (device, cloud).
- The save word the person sees.
- Reads and writes per action (Kwark runs on a free tier: say if a listener or a list is unbounded).
- What happens if this fails halfway.

## 8. Accessibility
- Keyboard path and shortcuts (⌘ on Mac, Ctrl elsewhere).
- Accessible name of every control without a visible word.
- Focus order; where focus goes when a dialog or sheet closes.
- Contrast checked in light, dark and the five writing rooms.
- Reduced motion behaviour.

## 9. Edge cases
| Case | Expected behaviour |
|---|---|
| | |

## 10. Out of scope
What this does not do, so nobody builds it by accident.

## 11. Open questions
| Question | Options | Recommendation | Decided by |
|---|---|---|---|

## 12. Acceptance checks
- [ ] Tokens only (no hex, rgb, px font sizes, font names)
- [ ] Shared components; every control has a word or an accessible name; chevrons on things that open
- [ ] Screenshots at 1440, 768, 375 and 320, looked at
- [ ] Every state above exists
- [ ] Keyboard and screen reader pass
- [ ] Decision record and element register updated
