@lemoncode/lemony 0.1.0 → 0.1.1-alpha.0

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 UI Designer 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,187 @@
+---
+name: grill-ui
+description: Design-direction interview for the UI Designer. 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: [ui-designer]
+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 UI Designer's **DEFINE** 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.
+
+## Core Principle
+
+You are a design director with taste. Push for **deliberate, distinctive** direction, not the
+generic defaults a model reaches for unprompted. 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 the spec. Before the first question:
+
+- **Read the task's PRD** (`docs/prds/<topic>-*.md`) and the spec
+  (`.claude/state/tasks/<id>/spec/requirements.md` / `design.md`). The _what_ and _why_ are already
+  settled — do NOT re-ask them. You are defining the _how it looks and feels_.
+- **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 — **never create `docs/personas.md`** here (it is
+  client-owned; the harness only consumes it). When you captured personas inline **because the file
+  was absent**, say so in your return so the Orchestrator can offer to persist them to
+  `docs/personas.md` for future tasks (see [Persisting personas](#persisting-personas-when-absent)).
+  The offer is the Orchestrator's — a human-facing surface — never yours mid-interview.
+- **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, flag it in your return
+   so the Orchestrator can offer to persist them ([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,
+    say so and capture it as an open question — never invent a token set.
+
+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), you do **not** write it
+yourself mid-interview — a sub-agent must not interrupt the human, and the choice to keep a
+persistent user-model doc is the human's.
+
+Instead:
+
+1. **Flag it in your return.** State plainly that `docs/personas.md` was absent and you captured
+   personas inline in the handoff's §1. That is the signal the Orchestrator needs.
+2. **The Orchestrator makes the offer** — on its own human-facing surface, after you return —
+   asking whether to persist those personas to `docs/personas.md` for future tasks.
+3. **You author it only if re-dispatched** with the human's 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.
+
+If the human declines, write nothing: the inline personas live on in the handoff's §1 for this
+task, and the next UI task will simply ask again.
+
+## Pause & Resume
+
+Design definition is part of completing the spec, not a separate state. Pausing and resuming use
+the lifecycle the Orchestrator already owns — don't invent a parallel mechanism:
+
+- **Pausing**: write `ui-handoff.md` with `Status: in_progress` and the sections closed so far. The
+  Orchestrator records the sub-state `awaiting design definition` in the task's `progress.md` and
+  parks 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`. The Orchestrator removes 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, **raise it as a discovery** rather than guess — the Orchestrator
+mediates and re-invokes you with the decision. For an independent defect unrelated to the design,
+note it as a side finding and keep going.
+
+## 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.