design-handoff-spec

Design Hand-off Spec

Overview

Every task blocked by this design task receives its documents in its run context as TEXT, under "## The approved design this task builds" — the hand-off specs first, then every mockup, the variants that were not chosen included. The markup of a mockup is dropped, so its colours, sizes and layout do not survive the trip. The hand-off spec is what they can act on. It is written after approval, from the chosen variant only, and it names things — components, tokens, copy — instead of describing pixels.

Core principle: An implementer reading only this spec builds the approved screen without inventing a single value, string or state.

Shape

One markdown document per screen, attached in the done run with add_task_document, titled handoff: <screen> — the same <screen> as its design: <screen> · <letter> mockups. Under ~10,000 characters: a markdown document reaches a dependent's run cut at 12,000, and the end is what gets cut.

# handoff: Invoices — list
Design task D-14 · approved: Variant A — table first, mockup `design: Invoices — list · A` (#variant-a, #states-a) — chosen by the human's "Chosen variant" comment · not chosen, never built: `design: Invoices — list · B` · design system Harbor base v3 + web layer v1

## Screen map
375: title row (Invoices · New invoice) → search → status chips (scroll sideways) → invoice rows → "Load more"
1440: sidebar 240px | content: title row → search + chips in one row → table (Customer, Number, Issued, Due, Amount, Status) → pagination

## Components
| Element | Component | Variant / props | |
|---|---|---|---|
| New invoice | atoms/Button | variant primary, size md, icon Plus | existing |
| Search | molecules/SearchField | placeholder "Customer or invoice number" | existing |
| Status | atoms/Badge | paid → success, overdue → destructive, draft → muted; always with its text | existing |
| Invoice row (375) | molecules/InvoiceRow | customer + number left; amount + status right; due date below | NEW · molecule · states: default, pressed, focus-visible |

## Tokens
colour: background, surface (table header), foreground, muted-foreground (secondary lines), border, primary/on-primary, destructive (overdue) · type: heading-2 (title), body, body-sm (secondary), tabular numbers for amounts · space: 4 (375 page padding), 6 (1440), 3 (row padding) · radius: md · shadow: none — rows are separated by border

## States
- Loading: six skeleton rows in the row's shape; title, search and New invoice stay visible.
- Empty, first use: "No invoices yet" · "Create your first invoice and send it in under a minute." · primary "New invoice".
- Empty, no match: "No invoices match "{query}"" · ghost "Clear search".
- Error: banner above the list: "Invoices couldn't load. Check your connection and try again." · "Retry"; search and chips keep their values.
- Row: hover (1440) surface background; focus-visible 2px ring inset; pressed (375) surface background.
- Dark: tokens only, no per-component overrides.

## Responsive
| Width | Behaviour |
|---|---|
| < 640 (375) | rows, chips scroll sideways, "Load more" instead of pagination |
| 768 | table: Customer (number below), Amount, Status |
| 1024 | full table; sidebar collapses to icons |
| ≥ 1280 (1440) | full table; sidebar 240px; content max 1200px |

## Accessibility
- One h1 "Invoices"; the table has a visually hidden caption and column headers.
- Status is text + colour, never colour alone. Each row is one link named "<customer>, invoice <number>".
- Focus order: search → chips → New invoice → rows → pagination. Touch targets ≥ 44px at 375.
- Checked contrast: muted-foreground/background 6.06:1 · on-primary/primary 7.52:1 (light), 7.17:1 (dark).
- The result count after a search is announced politely.

## Copy
| Where | Text |
|---|---|
| title | Invoices |
| primary action | New invoice |
| search placeholder | Customer or invoice number |
| chips | All · Draft · Sent · Overdue · Paid |

## Out of scope
Bulk actions, CSV export, the invoice detail page.