@lemoncode/lemony 0.1.0 → 0.1.1-alpha.1

package/catalog/skills/build-ui/anti-slop.md

@@ -0,0 +1,107 @@
+# Anti-slop — building the design's point of view into the code
+
+Load this before generating any visual UI. The `ui-handoff.md` already chose the
+**direction** (the dials, the tone, the brand references); this resource is about
+**executing** that direction in code without collapsing back to the generic defaults a
+model reaches for unprompted.
+
+## The failure mode to avoid
+
+"AI slop" is what UI looks like when no decision was made: the safe system font, the
+predictable purple-to-blue gradient, the evenly-spaced card grid with no focal point, the
+centred hero with a heading and two buttons, borders and shadows on everything. None of it
+is _wrong_ — it is just **average**, and average reads as nobody-cared. The handoff set a
+point of view; your job is to make every screen carry it. When you catch yourself
+reaching for the obvious default, stop and ask what the dials in §2 actually asked for.
+
+Match the **variance dial**: at low variance, restraint and convention are correct — do
+not manufacture flair the handoff didn't ask for. At medium/high, the generic default is
+a failure. Calibrate to the dial, don't apply maximum expression everywhere.
+
+## Typography
+
+- **Establish a real scale, not ad-hoc sizes.** Sizes, weights and line-heights come from
+  the token scale; a screen using five arbitrary pixel sizes has no hierarchy.
+- **Hierarchy through contrast, not just size.** Weight, colour, letter-spacing and space
+  separate levels — a heading is not merely "bigger body text".
+- **Line length and leading are deliberate.** Long-form text wants ~60–75 characters and
+  generous line-height; dense UI labels want tight leading. One global line-height for
+  everything is a tell.
+- **Type carries the brand.** If the direction is expressive, the typeface and its
+  treatment are where it shows first — not a decorative afterthought bolted on at the end.
+
+## Colour
+
+- **Drive colour from semantic tokens, always.** No raw hex in components. Reach for the
+  intent (`color.surface`, `color.text.muted`), so a theme change is a token change.
+- **Restraint reads as intentional.** A tight, deliberate palette with one confident
+  accent beats a rainbow. Most of a good UI is neutrals; colour earns attention where it
+  carries meaning (state, emphasis, brand).
+- **Contrast is a design tool, not only an a11y gate.** Use it to direct the eye — but the
+  floor is the a11y requirement (see [accessibility.md](./accessibility.md)).
+- **The gradient/glow reflex.** A gradient is a choice, not a default. If you add one, it
+  should be motivated by the direction, not reflexively dropped behind every hero.
+
+## Space, layout and hierarchy
+
+- **Spacing comes from the scale and creates rhythm.** Consistent, intentional spacing is
+  most of what makes a UI feel designed. Uniform padding everywhere flattens hierarchy;
+  vary space to group and separate.
+- **Every screen has a focal point.** Decide what the eye hits first and build the layout
+  to deliver it. A grid of equal-weight cards with no anchor is the canonical slop layout.
+- **Use alignment and an underlying grid.** Things line up on purpose; deliberate
+  asymmetry is a choice, accidental misalignment is noise.
+- **Density follows the dial.** Airy vs compact is a decision in §2 — honour it. Don't
+  pad an expert, data-dense tool into a marketing page or cram a spacious landing page.
+- **Whitespace is structure, not leftover.** Generous space around a focal element is how
+  you signal importance; reaching to fill every region is a reflex to resist.
+
+## Depth, borders and surface
+
+- **Don't outline everything.** Borders-and-shadow on every element is slop. Separate with
+  space and surface colour first; reach for a border or elevation only where it carries
+  meaning (an interactive boundary, a raised layer).
+- **Elevation is a system, not per-component guesswork.** Shadows come from the token
+  scale and map to a consistent sense of layering, not random blur values.
+- **Radius and stroke are part of the voice.** Sharp vs soft corners, hairline vs heavy
+  strokes — keep them consistent and aligned to the direction, from tokens.
+
+## Motion as craft
+
+Motion appetite is the **motion dial** in §2 — respect it; do not animate a low-motion
+brief, and don't leave a high-motion one static.
+
+- **Motion has a job.** Animate to show a relationship — where a thing came from, what
+  changed, what is loading. Decoration-only motion is noise.
+- **Fast and eased.** UI transitions are short (typically ~150–250ms) with easing that
+  matches the feel; linear, slow, or bouncy-by-default reads as amateur.
+- **Animate cheap properties.** Prefer transform and opacity; animating layout-affecting
+  properties janks.
+- **Respect `prefers-reduced-motion`.** Provide a reduced or no-motion path — this is both
+  craft and an accessibility requirement (see [accessibility.md](./accessibility.md)).
+
+## Responsive as craft
+
+- **Design the breakpoints, don't just let things reflow.** Decide what actually changes
+  per the handoff's §7 — a layout shift, a nav pattern, a density change — rather than
+  shrinking the desktop layout until it breaks.
+- **Touch and pointer differ.** Targets, hover affordances and spacing adapt to the input,
+  not just the viewport width.
+- **No horizontal scroll, no clipped content.** The small-screen state is a first-class
+  design, including the empty/loading/error states from §6.
+
+## Component and state completeness
+
+- **Build every state the handoff names.** Empty, loading, error, success and edge content
+  (§6) are part of the design — a component that only renders the happy path is unfinished.
+- **Reuse the design system; don't reinvent primitives.** Match existing components and
+  their variants. A bespoke one-off button next to the system button is slop.
+- **Microcopy is the words in the handoff (§10), verbatim and in voice.** Don't substitute
+  generic "Submit" / "Something went wrong" when the handoff specified the real copy.
+
+## The point-of-view test
+
+Before you call a screen done, ask: **could this have been generated for any product?** If
+yes, it has no point of view — return to the dials and the brand references in §2 and make
+the deliberate choice the handoff asked for. A design that someone could not have
+articulated alone is the bar; the average is the failure.

package/catalog/skills/code-explorer/SKILL.md

@@ -26,7 +26,7 @@ worthless.
 first — it is the maintained high-level map of the system's shape (contexts, boundaries,
 seams). Use it as your baseline: don't re-derive what it already states; deep-dive only
 where it is thin or stale for the question at hand. If it is **absent**, map from scratch
-as below — and never suggest creating it (it is the client's choice, decision #8). When the
+as below — and never suggest creating it (it is the client's choice). When the
 map contradicts the code in an area you read (the map says X, the code does Y), call out the
 staleness in your report's **Notes** so the Architect (your invoker, who owns the map) can
 reconcile it via `update-architecture` — don't silently trust either side.

package/catalog/skills/design-critique/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: design-critique
+description: The design-QA review lens for the UI Designer — judge an implemented UI change against its ui-handoff.md design contract (dials, focal point, states, microcopy) and the point-of-view test. Confidence-gated, verdict plus route-back, no severity theatre. Use at REVIEW when a task touched UI, alongside a11y-audit.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+phase: post-implementation
+invoked-by: [ui-designer]
+---
+
+# Design Critique
+
+Judge the **design quality** of an implemented UI change, with **fresh context** — the
+subjective half of design QA. The objective, measurable half (WCAG contrast, keyboard,
+semantics) is the `a11y-audit` skill, run alongside this one. This skill does not re-judge
+accessibility; it asks whether the screen carries the **point of view the handoff chose**.
+
+Your bar is the `ui-handoff.md` the Orchestrator authored for this task (under the task's
+`spec/` directory) — its dials, focal points, component and state decisions, motion
+appetite and microcopy. The build twin is the implementer's `build-ui/anti-slop.md`: this
+lens checks, in judge voice, what that resource asks the implementer to build. When you
+change an axis below, keep its build twin in step.
+
+## What you judge against — and what you don't
+
+Every finding ties to one of two anchors, never to raw preference:
+
+- **A handoff deviation** — the build did not honour a decision the handoff made: the §2
+  dials, the §4 focal point, the §6 states, the §10 microcopy, the §8 motion appetite.
+- **The point-of-view test** — _could this screen have been generated for any product?_ If
+  yes, it has no point of view, which is itself a failure of the handoff's chosen direction.
+
+You do **not** flag "I would have done it differently". The UI Designer holds a point of
+view but holds it lightly; a critique that relitigates settled, handoff-honouring choices
+trains the reader to ignore it. If the handoff itself is wrong or silent on a case, that is
+a **discovery**, not a rejection — raise it (`raise-discovery`) so the designer or human
+resolves it, rather than failing the change.
+
+## Confidence gating
+
+Only raise a finding you are **>80% confident** is a real deviation or point-of-view
+failure. State confidence when borderline. Match the **variance dial**: at low variance,
+restraint is correct and manufactured flair is the bug; at medium/high, the generic default
+is the failure. Calibrate to the dial — don't demand maximum expression everywhere.
+
+## The axes
+
+For each, the question is "does the build carry the handoff's decision?" — not "is this how
+I'd do it?".
+
+### Typography
+
+Does the type establish the handoff's hierarchy through a real scale (size, weight,
+colour, space), or fall back to arbitrary sizes and one global line-height? If the direction
+is expressive, does the typeface treatment actually carry it?
+
+### Colour
+
+Is colour driven from semantic tokens with the restraint the dial asked for — most of the
+UI neutral, the accent earning attention where it carries meaning — or a reflexive
+gradient/rainbow the handoff never called for?
+
+### Space, layout and hierarchy
+
+Does spacing come from a scale and create rhythm, with the density the §2 dial set? Is there
+a deliberate focal point (§4), or a flat grid of equal-weight cards with no anchor — the
+canonical slop layout?
+
+### Depth, borders and surface
+
+Is separation carried by space and surface first, with borders and elevation only where
+they mean something — or is everything outlined and shadowed? Are radius, stroke and
+elevation consistent and on-voice, from tokens?
+
+### Motion as craft
+
+Does motion match the §8 appetite — present where the brief is high-motion, absent where
+it's low — and does each animation show a relationship (origin, change, loading) rather
+than decorate? Fast and eased, not slow or bouncy-by-default?
+
+### Responsive as craft
+
+Are the §7 breakpoints designed — a real layout/nav/density change — rather than the
+desktop layout shrunk until it breaks? Are the small-screen empty/loading/error states
+first-class, with no horizontal scroll or clipped content?
+
+### Component and state completeness
+
+Are all the §6 states built (empty, loading, error, success, edge), or only the happy path?
+Does the change reuse the design system rather than introduce a bespoke one-off next to the
+system component? Is the §10 microcopy verbatim and in voice, not generic "Submit"?
+
+## Report
+
+Output a concise verdict the Orchestrator can act on — prose and a one-line verdict, **not**
+a severity table:
+
+```
+## Design Critique — <task name>
+
+**Against**: ui-handoff.md (<the focal decisions you checked>)
+
+<findings — each tied to a handoff section or the point-of-view test, with confidence
+when borderline; or "no design deviations">
+
+**Verdict**: approve / changes requested — <one-line reason>
+```
+
+"Changes requested" routes back to the Implementer (transient — no label). When the handoff
+is the thing at fault, raise a discovery instead. An independent defect unrelated to this
+change is a side finding (`note-side-finding`), not a rejection.

package/catalog/skills/design-tool-sync/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: design-tool-sync
+description: The token sync connector between the canonical design-tokens.json and a design tool (Figma, Pencil, or any variables-capable tool). Provider-agnostic and runtime-detected — the tool is a projection of the JSON, never a peer source of truth. import pulls tool variables into the 3-tier JSON (human-curated); export projects the JSON to the tool as an additive upsert that never deletes. Use when syncing tokens with a design tool, or when a drift check shows an export is pending.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+invoked-by: [ui-designer]
+---
+
+# Design-Tool Sync
+
+Keep the design tool and the canonical `docs/design-tokens.json` in step — tokens only. The
+JSON is the **single source of truth**; the design tool is a **projection** of it that can run
+ahead. That asymmetry shapes everything here:
+
+- **`import` (tool → JSON)** is the primary flow and **human-curated**: the tool cannot
+  silently overwrite the source of truth, so you present the diff and the human picks the
+  slice that lands.
+- **`export` (JSON → tool)** is an **additive upsert**: it creates and updates variables but
+  **never deletes** a tool-only variable. The JSON leads; the tool catches up.
+- **drift** is one-directional and deterministic: "has the JSON changed since the last
+  export?" — a pure-JSON check that needs no tool connection.
+
+You are invoked two ways: by `/sync-design-tokens` (the human's explicit handle, argument
+`import` or `export`), and at DEFINE when the drift check shows an export is pending and the
+current user has the tool connected.
+
+## Detect the tool (runtime, detect-or-skip)
+
+There is no per-provider configuration baked into the harness. Detect at runtime:
+
+1. Read the binding at the root of `docs/design-tokens.json`:
+   `$extensions["com.lemony.design-tool"]` → `{ "provider": "<tool>", "lastProjected": "<hash>" }`.
+   A declared `provider` means the project syncs; **no binding means the project is pure-code
+   — there is nothing to sync, stop here.**
+2. Confirm the declared tool's MCP server is actually connected in this session. If the
+   provider is declared but its MCP server is **not** available (a teammate's tool, a CI run,
+   a disconnected session), **skip gracefully**: say so in one line and do nothing. The
+   deterministic drift check still works without the tool, so detection never blocks.
+
+You bridge the tool's MCP and the deterministic CLI. The CLI never talks to the tool; **you**
+read and write tool variables over MCP and shuttle them through a provider-neutral file.
+
+## The neutral file (the bridge)
+
+Your per-provider adapter normalizes the tool's variables into one provider-agnostic shape the
+CLI consumes (and produces). It is a third representation, distinct from both the tool's raw
+variables and the DTCG JSON:
+
+```json
+{
+  "schemaVersion": 1,
+  "provider": "<tool>",
+  "variables": [
+    { "name": "primitive.color.brand", "type": "color", "value": "#3b82f6" },
+    {
+      "name": "semantic.color.text",
+      "type": "color",
+      "ref": "primitive.color.brand"
+    },
+    {
+      "name": "semantic.color.surface",
+      "type": "color",
+      "value": "#ffffff",
+      "modes": { "dark": "#000000" }
+    }
+  ]
+}
+```
+
+- `name` — the variable's dotted path. Map it to/from the tool's own grouping separator.
+- `value` for a literal; `ref` for an alias (the name of the variable it points at).
+- `modes` — per-theme overrides (the base theme is `value`/`ref`, not repeated).
+
+The CLI maps this to the 3-tier DTCG model: `ref` → an alias `{path}`, `modes` →
+`$extensions["com.lemony.modes"]`, and the tier follows the path (a literal defaults to
+`primitive`, an alias to `semantic` when the name carries no tier).
+
+## import — tool → JSON
+
+1. **Read** the tool's variables over MCP and write them to a neutral file (a temp path).
+2. **Preview** the diff (writes nothing):
+   `lemony design-tokens import --from=<neutral-file>`. It prints, per token, the target tier
+   and `new` / `changed` (with the old → new value) / `unchanged`.
+3. **Present and curate.** Walk the human through it: which new tokens to take, which changes
+   to accept, and — where a tool-origin name is ambiguous — whether a literal belongs in
+   `primitive` or `semantic`. The human owns the slice.
+4. **Apply** the agreed slice:
+   `lemony design-tokens import --from=<neutral-file> --apply --only=<dotted,paths>`.
+   This does the additive merge into `docs/design-tokens.json` deterministically (it
+   bootstraps the file if it does not exist yet). Then run `lemony design-tokens validate` to
+   confirm the result is well-formed.
+
+## export — JSON → tool
+
+1. **Plan.** Read the tool's current variables over MCP into a neutral file, then:
+   `lemony design-tokens export --tool-state=<tool-state> --out=<projection-file>`. It prints
+   the additive upsert plan (how many to create, how many to update — **never any deletes**)
+   and writes the projection the tool should hold to `<projection-file>`. The `--tool-state`
+   is optional; without it every variable is planned as a create (the upsert is idempotent by
+   name either way).
+2. **Confirm.** Show the plan; the human approves.
+3. **Push.** Write the projection's variables into the tool over MCP — create new ones, update
+   changed ones, leave tool-only variables untouched.
+4. **Record — only after the push succeeds.** `lemony design-tokens export --record` stamps
+   the drift baseline (`lastProjected`) so `status`/`doctor` report in sync. If the push
+   failed, do **not** record: the file correctly keeps reporting an export is pending.
+
+## Drift and degradation
+
+- `lemony status` and `lemony doctor` surface an **export-pending** state (the JSON moved past
+  the last projection). This is deterministic and needs no tool — it works in CI.
+- A declared-but-unavailable tool is never an error: skip with an informational note and let
+  the deterministic gates carry on.
+
+## Known limit (MVP)
+
+Export is **additive**: it does not propagate JSON-side deletions or renames to the tool. A
+variable removed or renamed in the JSON leaves its old counterpart in the tool — clean that up
+by hand. This is rare and deliberate: the safe default is to never delete a designer's work.
+Visual/screen sync is out of scope — this connector is tokens only.

package/catalog/skills/grill-ui/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: grill-ui
+description: Design-direction interview run by the Orchestrator. Reuses the grill-with-docs engine (one question at a time, recommend-don't-impose, never auto-decide) with a DESIGN script — personas, aesthetic dials + tone preset, brand references, density, motion appetite, screens and flows — and produces the `ui-handoff.md` design contract (not a PRD). Inherits the task's PRD and consumes `docs/personas.md` if present. Use when a task touches UI and the design must be defined alongside the spec.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+invoked-by: [orchestrator]
+attribution:
+  - source: mattpocock/skills
+    author: Matt Pocock
+    url: https://github.com/mattpocock/skills
+    license: MIT
+    relationship: derived-from
+    note: grill interview engine — one question at a time, decision-by-decision interrogation
+---
+
+# Grill UI
+
+The Orchestrator's **DEFINE** design method: a design-direction interview that turns a task into a
+`ui-handoff.md` design contract the implementer can build from. It is the design sibling of
+`grill-with-docs` — the same interrogation engine, a different script and a different output. You
+run it yourself, on your human-facing surface, and you author the handoff it produces.
+
+## Identity & taste
+
+Run this interview as a **design director with real taste** — the kind a solo dev without a
+designer wishes they had on call. Hold a high bar and bring conviction:
+
+- **Default to deliberate, distinctive design.** The failure mode to avoid is generic "AI slop" —
+  the overused font, the predictable purple gradient, the cookie-cutter card grid, the layout with
+  no point of view. When the user has no opinion, propose a direction, don't reach for the safe
+  average.
+- **Have a point of view, hold it lightly.** Recommend boldly and explain _why_, then let the user
+  decide. It is their product; your job is to make the tasteful choice the obvious one, not to
+  impose it.
+- **Decisions, not know-how.** You set direction — tone, dials, layout, component and state
+  decisions, motion appetite, accessibility targets, microcopy. _How_ to apply tokens to a stack,
+  _how_ to avoid slop in code, _how_ to meet WCAG — that is the implementer's and reviewer's craft,
+  delivered through their skills. Never restate it.
+- **Ground taste in craft, not vibes.** Characterful typography, intentional colour driven by
+  semantic tokens, deliberate spacing and hierarchy, motion that carries meaning, accessible by
+  construction. Cite the reason a choice is good.
+
+Drill every design branch. Present concrete options with trade-offs — never just open questions.
+The goal is a design the user could not have articulated alone, captured as decisions the
+implementer can execute and the review can verify.
+
+## Hard rules
+
+1. **NEVER auto-decide.** Every design decision (tone, dials, layout, component variant, motion,
+   a11y target, copy voice) goes through `AskUserQuestion`. "My recommendation: X" is fine as an
+   OPTION — never as a closed decision in the handoff.
+2. **One question at a time.** Always. Wait for the answer before continuing.
+3. **Recommend, never impose.** Mark one option `(Recommended)` and explain why; the user chooses.
+   You have taste, but it is the user's product.
+4. **Don't close the handoff unilaterally.** Ask before marking it complete. A WIP handoff is fine;
+   a falsely-closed one is not.
+5. **Capture decisions at decisions-altitude.** The handoff holds DECISIONS and targets, not
+   know-how. How to implement a token system, avoid slop, or meet WCAG lives in the implementer's
+   and reviewer's skills — never restate it here.
+
+## Inheritance — don't re-ask the need
+
+This interview runs **after** the general grill and **before** the Spec Author writes the spec — so
+the design direction it settles can inform the spec. Before the first question:
+
+- **Read the task's PRD** (`docs/prds/<topic>-*.md`). The _what_ and _why_ are already settled there
+  — do NOT re-ask them. You are defining the _how it looks and feels_. (The spec doesn't exist yet;
+  don't look for it.)
+- **Consume `docs/personas.md` if it exists** — the project's user models. Treat it as input; do not
+  re-derive personas the file already states. **If it is absent, ask inline** (the persona branch
+  below) and capture the answer in the handoff's §1 — **don't write `docs/personas.md` mid-interview**
+  (it is client-owned; the harness only consumes it). When you captured personas inline **because the
+  file was absent**, offer at the end to persist them to `docs/personas.md` for future tasks (see
+  [Persisting personas](#persisting-personas-when-absent)) — an opt-in offer on your human-facing
+  surface, never an unasked write.
+- **Consume `docs/design-tokens.json` if it exists** — the single source of truth for tokens. The
+  handoff §11 points at it; you never inline token values.
+- **Read `docs/architecture.md` if it exists** — orient against the system's shape so design
+  proposals don't contradict existing surfaces. Absent is fine; never push the user to create it.
+
+## The design script — branch by branch
+
+Walk these one at a time, in roughly this order. Skip a branch when the PRD/personas already
+settle it; mark a branch **N/A** when it doesn't apply to the task. Each closed branch maps to a
+section of [ui-handoff-format.md](./ui-handoff-format.md).
+
+1. **Personas / who it serves** (→ §1). Consume `docs/personas.md` if present; else ask: who uses
+   this, in what context, with what constraints (device, expertise, frequency)? Capture only what
+   shapes design decisions. If you asked inline because the file was absent, offer to persist them at
+   the end ([Persisting personas](#persisting-personas-when-absent)).
+2. **Aesthetic direction** (→ §2). The heart of the interview. Start from an optional **tone
+   preset** (`controlled` / `impact` / `innovative`) as shorthand that seeds defaults, then set the
+   three explicit **dials** — **variance** (conventional ↔ expressive), **motion** (still ↔
+   animated), **density** (airy ↔ compact). Gather **brand references** (sites/products the user
+   admires and why) and any voice/feel words. The dials are the canonical, verifiable direction
+   language — see [ui-handoff-format.md](./ui-handoff-format.md) §2 for the full definitions.
+3. **Screens & flows** (→ §3). Enumerate the screens/surfaces this task adds or changes; map the
+   navigation / user-flow between them in text or mermaid. **Text-first** — no pixels.
+4. **Per-screen layout** (→ §4). For each screen, the structural intent: regions, hierarchy, what
+   draws the eye first. Words, not mockups.
+5. **Components** (→ §5). Name the components and the variant/states that matter. **Graduated
+   altitude**: decisions-altitude by default (name the variant + the states that matter); the full
+   component anatomy ONLY for a genuinely novel or critical component.
+6. **States** (→ §6). Empty / loading / error / success / edge content for the task's surfaces.
+7. **Responsive** (→ §7). Breakpoint behavior that actually changes for this task.
+8. **Motion / interaction** (→ §8). Motion appetite (from the dial) + the few interactions that
+   carry meaning. Not an animation catalogue.
+9. **Accessibility** (→ §9). Target level (default WCAG 2.1 AA) + any task-specific a11y decisions.
+   The _audit_ and _how-to_ are skills — capture only decisions here.
+10. **Microcopy** (→ §10). The actual words for the task's key labels/messages, **inline**. Voice
+    follows §2; no separate copy artifact.
+11. **Tokens** (→ §11). Point at `docs/design-tokens.json`. If the project has no token file yet,
+    don't invent one mid-interview — surface it at the end as an opt-in offer
+    ([Design-tokens & design-tool on-ramp](#design-tokens--design-tool-on-ramp-when-absent)); if the
+    human declines, capture it as an open question.
+
+After important branches, offer a checkpoint:
+
+> "We've set direction, screens, and components. Three branches remain: states, responsive,
+> accessibility. Keep going, prioritize, or pause here?"
+
+## Co-creation — Socratic + proposals
+
+When the user has no formed design opinion, NEVER leave it open. Present alternatives with
+trade-offs and a recommendation:
+
+> "For variance you have: **low** — safe, system-like, fast to build, risks generic;
+> **medium** — distinctive but restrained; **high** — bold and memorable, more build cost and
+> more ways to get it wrong. Recommendation: medium for an internal tool, high for a landing
+> page. Which fits?"
+
+This teaches through forced trade-off comparison rather than blind choice.
+
+## Output — `ui-handoff.md`
+
+The interview produces **`ui-handoff.md`** under `.claude/state/tasks/<id>/spec/`, a sibling of the
+Spec Author's `requirements.md` / `design.md` / `tasks.md`. You **own** it. Use the canonical
+**11-section** contract in [ui-handoff-format.md](./ui-handoff-format.md).
+
+- A `Status:` field marks WIP vs done: `in_progress` while the design is being defined,
+  `completed` when closed. **Same file**, just a different status.
+- Update it **inline** as branches close — don't batch at the end.
+
+## Persisting personas (when absent)
+
+`docs/personas.md` is **client-owned**: the harness consumes it, never imposes it. So when the
+file was **absent** and you gathered personas inline (§1 above), don't write it mid-interview — the
+choice to keep a persistent user-model doc is the human's. Make it an explicit offer instead:
+
+1. **Offer at the end.** Once the design is defined, ask on your human-facing surface whether to
+   persist the inline personas to `docs/personas.md` for future tasks. Opt-in, never unasked.
+2. **On yes, write a minimal `docs/personas.md`** from the personas already captured in §1 — the
+   client's own words, not an invented cast. Keep it a skeleton the client can grow: one short block
+   per persona (who they are, their context/device, expertise, frequency, the goals and constraints
+   that shape design). Create `docs/` if absent. This is the client's real content, surfaced from
+   their own answers — never a vendor template, never personas the harness guessed.
+3. **On no, write nothing:** the inline personas live on in the handoff's §1 for this task, and the
+   next UI task will simply ask again.
+
+## Design-tokens & design-tool on-ramp (when absent)
+
+`docs/design-tokens.json` and a design-tool connection are **client-owned inputs** — the harness
+consumes them if present and otherwise leaves them alone, the same regime as personas. For a repo
+adopting the harness fresh, that silence is a dead end: no tokens, no way in. So when either is
+**absent**, don't dead-end at a silent open question — make an explicit, opt-in offer at the end, on
+your human-facing surface. Never scaffold or connect unasked.
+
+### Tokens absent → offer to scaffold
+
+When the project has **no `docs/design-tokens.json`**, offer once, after the design is defined:
+
+1. **Offer at the end.** Ask whether to scaffold a starter `docs/design-tokens.json` from the
+   direction just defined, or keep it as an open question in §11.
+2. **On yes, derive from the answers.** Build a minimal 3-tier DTCG file (`primitive` → `semantic`
+   → `component`) from what the human actually stated — the colours, type, spacing and radii that
+   came out of the aesthetic-direction branch (§2) and the components branch (§5). This is the
+   client's own direction, surfaced as tokens — **never a vendor template**, never a palette the
+   harness guessed.
+3. **Offer to cover the gaps too.** The interview rarely names every token. Ask a follow-up: for the
+   aspects the conversation **did not cover**, do they want a sensible **starter** set generated (a
+   neutral scale, default spacing and radii) so the file is usable from day one, or only the tokens
+   the answers implied? Opt-in — the human chooses how far to go, and you never pad the file unasked.
+4. **Validate before closing.** After writing, run `lemony design-tokens validate` and fix anything
+   it flags, so the scaffolded file is well-formed (3-tier, aliases resolve) — a scaffold that fails
+   the validator is worse than none.
+5. **On no, write nothing:** capture the missing token file as an open question in §11, exactly as
+   before. The next UI task simply asks again.
+
+### No design tool → offer to connect
+
+When `docs/design-tokens.json` carries no `com.lemony.design-tool` binding — or there is no tokens
+file at all — offer to **connect a design tool** (e.g. a Figma or Pencil bridge) so tokens can
+round-trip between the repo and the tool:
+
+1. **Offer, opt-in.** Ask whether to connect a design tool now, or **stay pure-code** (tokens live
+   only in the repo). Most repos are happy pure-code — recommend that unless the human wants a
+   visual tool in the loop.
+2. **On yes,** write the `com.lemony.design-tool` binding (the provider) into `docs/design-tokens.json`
+   and run the first import to bootstrap tokens from the tool. The `design-tool-sync` skill and the
+   `sync-design-tokens` command own the mechanics — you point the human at them; you don't
+   re-implement the bridge here.
+3. **Skip gracefully.** If the tool's MCP bridge isn't connected, say so and fall back to the open
+   question — never block the interview on an unavailable tool.
+4. **On no, stay pure-code:** write no binding. The design tool is only ever a projection of
+   `docs/design-tokens.json`, never a peer source of truth — declining costs nothing.
+
+## Pause & Resume
+
+Design definition is part of completing the spec, not a separate state. Pausing and resuming use
+the lifecycle you already own — don't invent a parallel mechanism:
+
+- **Pausing**: write `ui-handoff.md` with `Status: in_progress` and the sections closed so far,
+  record the sub-state `awaiting design definition` in the task's `progress.md`, and park the task.
+  Confirm with the user before ending the turn.
+- **Resuming**: `/resume <id>` re-enters via that sub-state. Read the in-progress `ui-handoff.md`,
+  confirm which sections are closed and which branch comes next, then continue.
+- **Completing**: flip `Status: in_progress` → `Status: completed`, then remove the
+  `harness:needs-design` flag at/before `spec-ready`.
+
+## Tone
+
+**Adaptive**, like the general grill. Start curious-collaborative; escalate when answers are shallow
+("I don't know", "whatever looks good"); never go beyond constructive provocation. You bring taste
+and conviction — push for a real direction, but the user decides.
+
+## When the design is underspecified
+
+If a design decision needs input the PRD left open with more than one valid answer and the user
+can't resolve it in the interview, **capture it as an open question** in the handoff rather than
+guess, and mark the handoff `Status: in_progress` until it is settled — never close a design on a
+guessed fork.
+
+## Cross-references
+
+```
+grill-ui → ui-handoff.md → implementer (build-ui) → REVIEW (design-critique + a11y-audit) → merge gate
+```
+
+The implementer reads `ui-handoff.md` as its obligatory design input; the REVIEW design lens checks
+the built UI against it. The `build-ui`, `design-critique`, and `a11y-audit` skills carry the
+know-how and the audits — this skill only defines the contract.
+
+---
+
+See also:
+
+- [ui-handoff-format.md](./ui-handoff-format.md) — the canonical 11-section `ui-handoff.md` contract,
+  the dials + tone-preset definitions (§2), and the graduated component anatomy.