---
name: design-spec
description: Turn a feature contract into an implementable UX spec BEFORE any user-facing implementation — flows, every screen state, components, complete copy in all supported locales, accessibility, and verifier-checkable acceptance criteria. Owner — ux-ui-designer. Do not use for non-UI work or after the build (that is design-review).
---

Produce the binding UX spec the builder implements from. A spec that cannot be verified is an opinion — every requirement here must be checkable.

1. **Read the inputs.** The task contract, `docs/DESIGN_SYSTEM.md` (create it from the template below if absent), the closest existing screens (templates/widgets), and the user context in `docs/SELF_MODEL.md` / project planning. Reuse existing components and patterns by name; propose a new pattern only when no existing one fits, and record it in `DESIGN_SYSTEM.md`.
2. **Write `docs/design/<feature>.md`** (≤ 2 screens), containing:
   - **User + job:** who uses this and what job it completes; the success moment in one sentence.
   - **Flow:** entry point → steps → exit, with the step count justified (fewer taps beats more options; name the target, e.g. "receipt in ≤ 3 taps").
   - **Screen states — all of them:** empty, loading, error, success, and (for offline-capable surfaces) offline / queued / sync-pending / sync-rejected. A state without a design is a bug deferred to production.
   - **Components:** reused ones by name and path; new ones with their `DESIGN_SYSTEM.md` entry.
   - **Copy:** every label, button, error, and empty-state message, in every supported locale — no placeholders, no English-only rows where i18n is required.
   - **Accessibility:** tap-target sizes, contrast, focus order, screen-reader labels for icon-only controls.
   - **Acceptance criteria:** numbered, observable checks a verifier can run or inspect ("tapping X from state Y shows Z"), including one criterion per non-happy-path state.
3. **Stay in scope.** Spec only what the contract includes; list out-of-scope UI you deliberately did not design so nobody infers it was forgotten.
4. **Return** the spec path, the design-system delta, and any open decision that changes scope, risk, or cost.

## docs/DESIGN_SYSTEM.md starter template

```markdown
# Design system

> Conventions every user-facing change follows. Updated only by ux-ui-designer; violations are design-review findings.

## Principles
- [e.g. fewest taps to complete the money task; offline is a first-class state; all copy ships in en + tl]

## Foundations
- Type scale / spacing / color roles: [tokens or file path]
- Tap targets ≥ 48dp; contrast ≥ WCAG AA; focus order follows visual order.

## Components
| Component | Path | Use for | Never for |
| --- | --- | --- | --- |

## Screen-state patterns
- Empty / loading / error / offline / queued / sync-rejected: [canonical pattern per state]

## Copy rules
- [tone, locale coverage, currency/date formats]
```