Kwark. Design System
Open Kwark

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.

For agents

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), 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)

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

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.

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.

“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.”

Do

“Empty state: TBD.” or “Show a nice illustration and a call to action.”

Don’t

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.
  • 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 is installed, screenshots at the four widths, and a list of what the system did not cover.

The kwark-handoff skill writes a spec in this shape from a design description.

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

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

Open .mdllms.txt
Loading…