---
name: kwark-handoff
description: Write a design-to-code handoff spec the Kwark way (purpose, journey, phone and desktop layout, components, tokens, every state, copy, accessibility, edge cases, data and offline). Use when a screen or feature is designed and needs a spec an engineer or a coding agent can build from without guessing.
---

# Write a Kwark handoff spec

A handoff spec lets someone build the screen without asking a question. In Kwark it comes after the journey and the wireframe have been agreed (UX before build), and it names parts and tokens instead of drawing pixels.

## Load first

- https://kwark.space/designSystem/agents/handoff.md (the method)
- https://kwark.space/designSystem/skills/kwark-handoff/template.md (the template to fill; it sits next to this file when the skill is installed)
- https://kwark.space/designSystem/AGENTS.md
- https://kwark.space/designSystem/components.json (what exists, so the spec names real parts)
- https://kwark.space/designSystem/patterns/phones.md

## Rules

- **Must** start with the person and the problem in one sentence, and the decision record it follows or creates.
- **Must** specify phone (375 and 320) and desktop (1440) separately. A phone layout is not a squeezed desktop.
- **Must** name each part by its component (`Button` primary, `Sheet`, `ListRow`) and each value by its token (`--k-space-4`, `--k-fs-title`). If no component fits, say "new component" and describe it with tokens.
- **Must** list every state: default, hover, focus, pressed, disabled with a reason, loading, empty, error, offline, read-only (a shared viewer), long text, an Indian script.
- **Must** write the real copy for every string, in Kwark's voice. No lorem ipsum, no "TBD".
- **Must** say what is saved, when, and what the person sees if it does not reach the cloud.
- **Must** give the keyboard path, the accessible names, the focus order and where focus returns.
- **Must** list the edge cases with the expected behaviour, and what is out of scope.
- **Never** leave a choice to the builder silently. If something is undecided, list it under Open questions with the options.
- **Never** add a dot, badge, count or colour without saying what it means and why it is there.

## Output

Fill the template's sections in order. Keep it to what a builder needs. End with the acceptance checks a reviewer will run.
