design-playbook 0.7.0

package/skills/design-playbook/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: design-playbook
+description: Orchestrate outcome-first Design I/O for product UI. Use when building or revising a page, dashboard, list, or settings surface from a short ask, or recirculating a failed design review through declarations and evidence.
+---
+
+# design-playbook
+
+**Design I/O** — same process every run: inject **declarations** (what good is), run **contracts** (how work enters the pipeline), **recirculate** failures to the declaration that owns them.
+
+Not a style library. For palettes/type catalogs use other packs; here the product pipeline and acceptance are the product.
+
+## Run contract
+
+Keep each control in one authoritative place:
+
+| Control | Single source | Required content |
+| --- | --- | --- |
+| **Goal** | `spec` L1 | User-visible outcome, target user and scene, non-goals |
+| **Success** | `spec` L6 | Observable pass/fail criteria; every top-level L6 item is `Given -> When -> Then` |
+| **Evidence** | `spec` L6 + evaluator ledger | Exactly one `L6.<n>` ledger row per criterion; planning-only uses declaration coverage, implementation uses rendered states, interaction/test results, and applicable code checks |
+| **Stop** | this orchestrator | Pass; smallest missing decision; unavailable required evidence or authority; repeated blocker |
+| **Confirm** | this orchestrator + user decision | Any consequential action not already authorized |
+
+Answer, review, diagnose, and plan requests end with findings or a plan. Build and fix requests continue through in-scope local edits and the most relevant available validation. Ask the smallest question only when the answer changes the goal, scope, platform, success criteria, or authority; otherwise record a conservative assumption in L1.
+
+Pause for explicit confirmation before an external, destructive, costly, or scope-expanding action that the request did not already authorize. This includes adding a dependency, changing an API/backend/data contract, deploying or publishing, and accepting a blocking finding. When required evidence or authority is unavailable, stop with the exact blocker and the smallest next decision. If the same blocking finding survives two repair -> re-evaluate cycles without new evidence, stop recirculating and report it.
+
+## Steps
+
+> **Stage-list mirror (monorepo maintainers only):** repo-root `scripts/run_status.py` → `STAGES` mirrors this section's steps and artifact filenames for status/resume narration. **Not shipped** with the installable plugin package (`packages/design-playbook/`). Plugin users ignore this pointer. If you add/remove a step or change an artifact filename here, update that monorepo table.
+
+Do in order. Data flow:
+
+`design-baseline? → reference-intake? → ux-spec? → plan? → (native-craft?) → ui-picker → (preview*) → fill → craft-guard → (observe*) → ui-evaluator`
+
+- `?` = conditional entry/route
+- `*` = run only when the matching MCP tool is available (`preview_prototype` for preview, `execute_capture_plan` for observe); otherwise skip
+- When you skip a step, say so in one line — step name + reason + how to enable, with the gate label when one applies. Matters most for `preview*`/`observe*` adapter absence, e.g. `-> preview*: adapter absent, skipped (G5 not triggered; enable via packages/design-playbook/mcp/preview/ or host MCP)`. Other conditional skips may use the same shape; entry lines are optional (keep output lean). Narration only — not a run-contract control.
+- Do not code a pretty shell until the active step’s completion criterion is met
+
+### 1. Entry routing
+
+**SSOT for this decision is this skill only** (not `commands/design-io.md`).
+
+- **Existing-product UI build/fix** (meaningful first-party pages/components/theme/styles already exist) and no usable verified baseline binding under `.scratch/<run>/design-baseline/state.json` → step **1A. `design-baseline`**
+- **Reference materials present** (screenshot, design file path, URL, or product/brand analogy) and no usable `.scratch/<run>/reference/contract.md` → step **2. `reference-intake`**
+- **Missing `spec`** (no usable six-layer `spec.md` for this run) → step **3. `ux-spec`**
+- **Spec present** → step **4. plan** (do not re-run `ux-spec` unless structural conflict forces it)
+- No meaningful existing UI, or no UI mutation in scope → skip `design-baseline` with one-line narration
+- No reference materials → skip `reference-intake` with one-line narration
+
+### 1A. `design-baseline` (existing-product UI only)
+
+Invoke **design-baseline** before reference intake or specification work. Call the deep module `prepare` → (user confirm/waive) → `confirm` as needed; immediately before Fill call `verify`. Discover and validate project `DESIGN.md`; if missing or incomplete, generate only run-local `DESIGN.draft.md` + `evidence.json` from first-party UI evidence and wait for confirmation before a durable write.
+
+Gate artifact is only `.scratch/<run>/design-baseline/state.json` (`schema: design-baseline/v1`). A valid existing baseline becomes `status: ready` with `decision.kind: existing`. A generated draft requires `confirm(..., "accept")` (`ready` + `accepted`) or explicit `confirm(..., "waive", reason=...)` (`waived`). `needs_confirmation` and `ambiguous` block Fill. A draft alone is not authority.
+
+**Done when:** **design-baseline**'s own completion criteria hold (that skill is SSOT). Smoke: `state.json` exists; candidate conflicts and stale source hashes are exposed by prepare/verify; status is `ready` or `waived`; no valid baseline was silently replaced.
+
+### 2. `reference-intake` (when reference materials present)
+
+Invoke **reference-intake**. Produce `.scratch/<run>/reference/contract.md` + `manifest.json` (ADR-0011).
+
+**Done when:** **reference-intake**'s own completion criteria hold (that skill is SSOT). Smoke: sources inventoried; observed vs inferred labeled; Keep/Change/Do not copy present for product-analogy, third-party URL, **and third-party screenshot/design**; license/brand risks recorded. Does not write `spec.md` or a decision report.
+
+Then continue to **3. `ux-spec`** (or **4. plan** when spec already exists).
+
+### 3. `ux-spec` (when spec is missing)
+
+Invoke **ux-spec**. Produce six-layer `spec.md`. When `.scratch/<run>/reference/contract.md` exists, **ux-spec** must read it first (functional constraints, non-goals, always/ask/never) — do not wait for plan.
+
+**Done when:** **ux-spec**'s own completion criteria hold (that skill is SSOT). Smoke: L1–L6 present; L5 substantive, not "show loading"; every top-level L6 item uses ordered `Given -> When -> Then`, names its evidence, and names the capture seed where the proof is a runtime state; reference constraints folded when a contract exists.
+
+Then continue to **4. plan**.
+
+### 4. plan (pipeline step — pure orchestration)
+
+Not a run-contract control and **not** a machine gate. Does not become Goal / Success / Evidence / Stop / Confirm SSOT.
+
+Write a light handoff at `.scratch/<run>/plan.md` (required on disk). When `.scratch/<run>/reference/contract.md` exists, the handoff must point to it (path only; do not paste the full contract) and fold its functional constraints into the description→spec map and its visual cues/exclusions into the ui-picker input pack. Minimum three blocks:
+
+1. **本次 run 范围** — pointers to L2 / scenes / non-goals (do not copy L1–L6 wholesale)
+2. **用户描述 → spec 映射** — which L1/L2/L6 this ask touches; unmapped items → conservative assumptions
+3. **ui-picker 输入包** — scene hints, constraints, explicit exclusions
+
+**禁止:** paste the full spec; pre-write a decision report inside plan.
+
+**描述 × spec 分轨:**
+
+- **Structural conflict** (L1 outcome, L6 criteria, platform/permission/data contract, overturned non-goal) → stop; revise `ux-spec` or user Confirm of an exception recorded in plan
+- **Presentation preference** (scene density, region weight, component role preference without L6 change) → put in the ui-picker input pack; `ui-picker` decides
+- **Unmapped description** → mapping table as conservative assumption; do not silently edit L1
+
+**Done when:** `plan.md` exists with the three blocks; ui-picker can consume the input pack without re-deriving scope from chat.
+
+### 5. Shell → conditional `native-craft` → `ui-picker`
+
+Native desktop order: `ux-spec` → `native-craft` → `ui-picker` → `fill` → `craft-guard` → `ui-evaluator`. (Conditional entry `?` and optional adapters `preview*`/`observe*` are shown in the full sequence above, step 0.)
+
+- Invoke **native-craft** only for an explicit native-desktop target or a request for native-feel. Web and mobile Web skip `native-craft`; a Web UI that merely resembles a desktop admin tool is still Web.
+- If the target platform is unclear, ask once before choosing the route. Do not assume native desktop.
+- For native desktop, require the native decision gate and render-surface seam before invoking **ui-picker**. If `native-craft` cannot load or does not produce them, stop and report what is missing; do not silently choose a Web shell.
+- Pass the decision gate and seam to **ui-picker** as required shell context. The caller does not reconstruct or reinterpret them.
+
+Invoke **ui-picker**. Map scene → template + component semantics. Read its `references/` only as that skill directs. When `.scratch/<run>/reference/contract.md` exists, pass its visual cues / exclusions (via plan input pack and/or direct path) into **ui-picker**.
+
+**Done when:** **ui-picker**'s own completion criteria hold (that skill is SSOT). Smoke: the decision report names scene, density, template, regions, components, and risks; coding has not started before that report exists. For native desktop, it also consumes the declared render-surface seam.
+
+`ui-picker` **stops at the decision report** — it has no preview step.
+
+### 6. preview* (optional external MCP adapter)
+
+After the decision report exists, probe MCP `tools/list` for **`preview_prototype`**.
+
+- **Absent** → skip preview; go to Fill (current behavior). No preview artifacts required.
+- **Present** → run the preview loop in this orchestrator (not inside `ui-picker`):
+  1. Host agent generates a disposable prototype HTML (structure-semantics floor: readable scene, named template regions, key component roles as placeholders). Path under `.scratch/<run>/preview/round-{n}.html`.
+  2. Call `preview_prototype` with `path` (preferred) or `html`, plus `summary`, `round`, `report_ref` (current decision report), optional `options`.
+  3. Adapter shows the prototype, collects feedback, applies the **feedback floor** (ADR-0008: non-empty feedback, OR ≥1 anchor with non-empty selector + non-empty comment), writes confirm/log under `.scratch/<run>/preview/`. A confirm that fails the floor is written with `confirmed: false` + `floor_failure` reason — it does **not** count as a confirm.
+  4. On “需要修改” (or `confirmed: false` from a floor failure): append feedback to `preview/log.md`, revise the decision report in place (mark round), generate next prototype; **same blocker two repair rounds without new evidence → stop the loop and report**.
+  5. On confirmed: the tool's `confirmed=true` is **not authoritative on its own** — the confirm record must also carry `floor_pass: true`. Proceed to Fill only with the confirmed + floor-passed decision report (+ plan pointers).
+
+**Native desktop:** still run Web preview when the adapter exists; coverage is **render-surface seam and above** only. Note that limitation once in `preview/log.md`. Do not skip preview solely because the route is native (skip only when the adapter is missing).
+
+**Hard boundary:** never copy `preview/round-*.html`, preview-only assets, fake data shells, **`reference/assets/`**, or **`reference/example.html`** (or any other file under `.scratch/<run>/reference/`) into the Fill source tree. Fill consumes report + `spec` semantics, not prototype or reference media files.
+
+**Re-Fill signal (preview after Fill already exists):** if a Fill surface (code under the host tree or `filled-ui.*`) already exists and a later preview round **revises the decision report** (new round, structural/component change absorbed into `decision-report.md`), you **must re-Fill** (or explicitly record user acceptance that the existing Fill already matches the new report) **before** observe* / ui-evaluator. Do not run observe against a Fill that predates the current confirmed report. Log the re-Fill (or acceptance) once in `preview/log.md`.
+
+**Done when:** either preview was skipped (no adapter), or a `confirm-round-*.json` with `confirmed: true` **and `floor_pass: true`** matches the current decision report (G5 when `validate_run.py` is given `--preview-dir` / `--decision-report`). A confirmed record without `floor_pass` fails G5 — empty/garbage feedback is a silent false-pass that must not reach Fill. When Fill already existed, the re-Fill signal above is satisfied.
+
+### 7. Fill
+
+Implement structure from the decision report + `spec` + confirmed project `DESIGN.md` when bound. Prefer project tokens: visual values via `var(--*)`; missing tokens → `gaps.log` (or project equivalent), not raw hex/px/ms.
+
+**Hard boundary (design baseline):** for existing-product UI work, do not enter Fill unless `design_baseline.verify(project_root, run_root)` succeeds with `status` `ready` (bound path + sha256) or `waived` (non-empty reason). A draft alone is not authority.
+
+**Hard boundary (reference):** never copy `.scratch/<run>/reference/assets/`, `reference/example.html`, or third-party brand media inventoried by reference-intake into the host Fill tree. Honor Do not copy via report + `spec` only.
+
+If a reused host component conflicts with spec L5, record the conflict and recirculate to `spec` via the authoritative map in `ui-evaluator` before choosing a minimal patch or explicit acceptance.
+
+Load on demand (only if the fill needs them):
+
+- domain / risk / sensitive fields → `ui-picker/references/domain.md`
+- token roles / gaps → `ui-picker/references/design.md`
+- component pairs → `ui-picker/references/components.md`
+
+**Done when:** with a codebase — main flow renders and every L5 state named in the spec has a concrete UI path (not a blank region); planning-only — every L5 state has a named concrete UI landing, no blank region.
+
+### 8. Craft → `craft-guard`
+
+Invoke **craft-guard**. Apply loading tiers, motion purpose, hierarchy, CJK type. For native desktop, `craft-guard` owns shared UI above the render-surface seam and defers to `native-craft` below it. If a finding crosses the seam, split it into separate point-backs to the owning declarations.
+
+**Done when:** **craft-guard**'s own completion criteria hold (that skill is SSOT). Smoke: every wait/fail path maps to a loading tier; every animation states its purpose; L4 interactive-zone affordance resolved; residual issues handed to `ui-evaluator` with source `craft`.
+
+### 9. observe* (optional external MCP adapter)
+
+After craft, probe MCP `tools/list` for **`execute_capture_plan`**.
+
+- **Absent** → skip; `ui-evaluator` ledger `observed` stays free-text (current behavior). G6 not triggered.
+- **Present** → for each L6 criterion whose proof is a runtime state, run the evidence loop in this orchestrator (not inside any skill):
+  1. **Derive** a capture plan from L6 `Given -> When -> Then` (in memory, not on disk): `Given`/`When` → `state` + `actions`; `Then` → required proof (already in the ledger `required` field). Do not add or remove verification intent; L6 wins on conflict.
+  2. **Execute**: call `execute_capture_plan({url, type, state, actions, artifact_path})`. The provider returns `{artifact, observed_state, result, error, written_path}` and never sees the criterion. Prefer `written_path` (absolute) when locating the file; if it points outside `.scratch/<run>/`, fix `DESIGN_PLAYBOOK_RUN_ROOT` / cwd before binding. `artifact_path` must start with `evidence/` (e.g., `evidence/empty-state.png`, not `empty-state.png`) — the provider resolves it under `<run_root>/evidence/` and refuses absolute paths, `..` segments, or anything that escapes that subtree (`mcp/evidence/server.py` `_resolve_artifact_path`); a bare filename is rejected because it would land outside the evidence subtree.
+  3. **Bind** (orchestrator owns the manifest; provider never writes it). After **each** successful or failed capture, **immediately append** one line to `.scratch/<run>/evidence/manifest.jsonl` — do not batch-rewrite the file at the end. Rules:
+     - **`observed_state` / `result` / `error`**: copy the provider return **verbatim**. If the provider returns `unknown`, write `unknown` — never overwrite with the requested `state` (request intent lives only under `capture.state`).
+     - **Embedded capture snapshot**: store the full call parameters used (`url` including query string, `type`, `state`, `actions`, `artifact_path`). Omit nothing that would be needed to re-run the capture.
+     - **`ts`**: wall-clock of **this** capture's completion (ISO-8601). Distinct captures must not share one batch timestamp.
+     - Also record: criterion ref, `artifact` (run-root-relative), optional `artifact_sha256`, optional `written_path` from the provider.
+  4. **Manual provider**: when no ecosystem provider is present but a human operates + screenshots to `artifact_path`, write the same-format manifest entry (`capture.provider: "manual"`); `observed_state` is what the human actually saw, not the planned label.
+- v1 capture types: `screenshot` / `a11y tree` / `interaction trace`.
+
+**Capture surface (url choice — honesty, not a machine gate):**
+
+1. **Prefer the live host** — running Fill surface (dev server route / real app URL) that implements the decision report.
+2. **Semantic mirror** (static HTML / fixture that only *looks like* Fill) is allowed only when the live host is unavailable or unsafe. Then **all** of:
+   - every manifest entry's capture snapshot includes `note` (or equivalent) with **`surface: mirror`** and a one-line reason;
+   - **ui-evaluator** must emit a finding (severity at least **low**) that observe used a mirror, `source` = `observe* seam` (or preview*/observe* seam), and the fix is "re-capture on live host when available";
+   - do **not** claim G6/process Pass as proof that the Fill tree was runtime-verified.
+3. **Mirror `data-state` (recommended):** when using a semantic mirror, set the page state the provider can read so `observed_state` is not forced to `unknown`. The evidence adapter reads `body[data-state]` or `[data-state]` (see `mcp/evidence/server.py` `_read_observed_state`). Example:
+
+   ```html
+   <body data-state="empty">
+     <!-- empty-state UI for L6 empty criterion -->
+   </body>
+   ```
+
+   Prefer one root marker that matches the capture plan's `state` intent. Still **never invent** `observed_state` in the manifest — copy the provider return verbatim (unknown stays unknown).
+
+Evidence is captured, not judged — copy provider returns verbatim here; `pass`/`fail` authority is the evaluator's (step 9 / `ui-evaluator`). Full authority model (three ledgers: spec names what to prove, manifest what happened, evaluator what it means): SSOT `ui-evaluator` step 2.
+
+**Done when:** either observe was skipped (no provider, ledger `observed` free-text), or each runtime-proven criterion has a manifest entry whose artifact exists (G6 when `validate_run.py` is given `--evidence-dir`); and if any capture used a mirror surface, the point-back includes the required mirror finding.
+
+### 10. Accept → `ui-evaluator`
+
+Invoke **ui-evaluator**. Issues must **point back** to a declaration.
+
+**Done when:** the report includes the criterion-shaped evidence ledger (`criterion / required / observed / result`) and findings as `issue / source / fix / severity`; the authoritative verdict completion criterion in `ui-evaluator` is met; **and** you show the user a short **run artifact index** (paths under `.scratch/<run>/`) so declaration products are discoverable — at minimum: `design-baseline/` (if triggered), `reference/` (if any), `spec.md`, `plan.md`, `decision-report.md`, `preview/` (if any), Fill surface path, `evidence/` (if any), `point-back.md`. One block is enough; do not only leave paths buried in tool logs.
+
+Machine seam (optional local check): `python scripts/validate_run.py <spec.md> <point-back.md> [--preview-dir <preview/>] [--decision-report <report>] [--evidence-dir <evidence/>] [--run-root <run>]`.
+
+## Recirculate
+
+When a finding has no owner or you need the observable -> declaration routing, use the **authoritative recirculate map in `ui-evaluator`** (do not duplicate it here). Fix only the owning layer, then resume from the step that consumes it.
+
+## Contracts on this pipeline
+
+| Contract | Skill |
+| --- | --- |
+| Discover/validate/generate the project visual baseline | `design-baseline` |
+| Reference intake (observed/inferred + Keep/Change/Do not copy) | `reference-intake` |
+| Write the functional declaration | `ux-spec` |
+| Choose shell + component meaning | `ui-picker` |
+| Craft / feedback quality | `craft-guard` |
+| Native-feel desktop declaration (render seam + conventions) | `native-craft` |
+| Acceptance + point-back critique | `ui-evaluator` |
+
+`plan`, `preview*`, and `observe*` are orchestrator steps (plus optional external MCPs for preview and observe), not rows in this table. `design-baseline?` is a conditional existing-product orchestrator gate (ADR-0012); `reference-intake?` is a conditional skill step (ADR-0011), not a machine gate.
+
+Slash (installed plugin, namespaced): `/design-playbook:design-io` · `/design-playbook:ux-spec` · `/design-playbook:ui-review`.
+With `claude --plugin-dir` the same command files apply under the plugin namespace.

package/skills/native-craft/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: native-craft
+description: Native-feel declaration for desktop apps. Use when a cross-platform desktop app (macOS+Windows) must feel indistinguishable from native. Invoked before ui-picker for native-desktop targets, not web pages.
+---
+
+# native-craft
+
+**Native-feel** is a Design I/O **platform declaration**: it fixes the render-surface seam and the native conventions before any web shell is picked. It is the native-desktop twin of `craft-guard` (which owns web craft); the two do not overlap.
+
+Inspired by yetone/native-feel-skill (MIT) - see `NOTICE`. Depth lives in [`references/native-feel.md`](references/native-feel.md); do not load it until this skill applies.
+
+## When to apply / skip
+
+- **Apply** when the target is a desktop app that must feel native on macOS + Windows (launcher, system utility, all-day productivity tool).
+- **Skip** when: one OS only (build pure native), Electron-is-fine polish bar, internal tool, cold-start < 100 ms hard, or pure web/mobile. The decision gate in `references/native-feel.md` rules this stack **out** for those shapes - say so directly.
+
+## The declaration: place the seam at the rendering surface
+
+The cross-platform boundary is drawn at the **WebView surface**, nowhere else.
+
+- **Below the seam** - windowing, hotkeys, materials, file dialogs, tray, a11y, input methods, context menu - **native**, written twice in idiomatic Swift / C#. No abstraction is fast or correct enough.
+- **Above the seam** - React tree, business logic, extension API, AI orchestration - **shared**, written once in TS.
+
+Test every platform decision: *is this above or below the rendering surface?* Below -> write it twice. Above -> write it once. Refuse to draw the line elsewhere.
+
+## Native-feel tenets (cite by short name when advising)
+
+- **Seam at render surface** - the boundary altitude where neither side can mimic the other.
+- **Adopt the platform, don't compete** - the OS draws blur, scrollbars, dark mode, focus rings better than you. "Let the OS do it" *is* the implementation; custom is last resort.
+- **Perception is performance** - users feel promises kept (keystroke, frame, latency), not MB/FPS. Define the perception target before optimizing.
+- **Cross boundaries intentionally** - every IPC is a design decision: async, batched, schema-typed, observable. Never treat IPC like a function call.
+- **Iteration loop is the product** - hot-reload (~200 ms) vs native recompile (~30 s) is 150x; the cross-platform tax buys this, protect it.
+
+## Pipeline integration
+
+`native-craft` runs at **plan / shell**, before `ui-picker`:
+
+1. Run the decision gate (`references/native-feel.md`). If it rules native-feel **out**, stop - tell the user to use Electron / pure native / web.
+2. Declare the seam: what is native (below) vs shared TS (above).
+3. Declare native conventions (materials, cursor, windowing, keyboard, drag-drop) - the audit in `references/native-feel.md`.
+4. Hand to `ui-picker` for the shared UI shell; `craft-guard` still applies **above** the seam but must defer to native conventions below it (e.g. no `cursor: pointer`, no web toasts, OS materials).
+
+## Done when
+
+- The decision gate has been run and native-feel is either confirmed in-scope or ruled out (with the reason stated).
+- The seam is declared: every platform-touching feature labeled native (below) or shared (above), no "convenient" third line.
+- Native conventions that block native-feel are listed for the surface in scope (cursor, context menu, materials, window controls, scroll, motion, keyboard, drag-drop).
+- `craft-guard` rules above the seam and native conventions below it are reconciled - no conflict where web idiom would telegraph "web app".
+
+## Recirculate
+
+| Observable | Declaration |
+| --- | --- |
+| App feels like a web page (cursor:pointer, web toasts, box-shadow windows) | `native-craft` conventions |
+| Wrong seam (UI in native, or platform code in TS) | `native-craft` seam |
+| Slow perception despite low memory | `native-craft` perception tenet |
+| Used this stack for a one-OS / Electron-fine / <100ms app | `native-craft` decision gate (rule out) |
+
+Depth: decision gate + native-conventions audit -> [`references/native-feel.md`](references/native-feel.md). Full evidence (WebView survival, IPC contract, memory truths) -> original `native-feel-skill` (user installs separately).

package/skills/native-craft/references/native-feel.md

@@ -0,0 +1,79 @@
+# native-feel - decision gate + conventions audit
+
+Condensed in our voice from yetone/native-feel-skill (MIT). Full depth (WebView survival, IPC contract, memory truths, Raycast evidence) lives in the original skill - install it separately if you need it.
+
+## Decision gate - run first, rule OUT honestly
+
+| Question | Ruled OUT (use instead) |
+| --- | --- |
+| One OS only? | Pure native (Swift/AppKit or C#/WinUI) - cross-platform tax not worth it |
+| "Nice but Electron is fine"? | Electron + good designer - this stack's polish budget is 5-10x Electron |
+| Internal tool, no end-user polish? | Web app / Electron |
+| Cold start must be < 100 ms? | Pure native - WebView+Node boot floor is ~150-300 ms even prewarmed |
+| Pure web or mobile? | Not this skill |
+
+Proceed only when: macOS + Windows (optionally Linux), native-feel is a competitive differentiator, and warm-start < 50 ms / cold < 500 ms is acceptable.
+
+## The seam (the one structural decision)
+
+The below/above split is declared in `SKILL.md` — that list is authoritative. This reference adds the IPC rule:
+
+One schema for all IPC -> generate typed clients per runtime (UniFFI for Rust<->Swift/Kotlin/C#). Hand-written marshalling drifts in a sprint.
+
+## Native-conventions audit - the "not a web page" checklist
+
+Each item telegraphs "web app" when wrong. None changes a benchmark; all change what the user feels. A skeptic should conclude "regular Mac/Windows app" in 30 s.
+
+### Input & cursor
+- No `cursor: pointer` on hoverable rows. Native list rows don't change cursor.
+- No text selection on chrome (labels, button text, headings) - only content areas select.
+- Native context menu, not WebKit's: override `willOpenMenu` (Mac) / `CoreWebView2.ContextMenuRequested` (Win).
+- No spellcheck underlines / dictionary popups / link previews on chrome.
+- IME composition window at the caret, not above the WebView (test Pinyin/kana).
+
+### Windowing & focus
+- Native window behavior: ⌘W / Alt-F4 close, ⌘M / Win+Down minimize.
+- Dock/Taskbar click re-shows last window, doesn't spawn a new one.
+- Settings in a native window (⌘, on Mac), not an in-app modal.
+- Native `NSAlert` / `MessageBox` for confirms - no backdrop-blur modal overlays.
+- OS notification center - no web toasts.
+- Real title bar / chromeless region; drag works on full title bar.
+- Traffic lights left (Mac) / min-max-close right (Win); Mac green = zoom not fullscreen.
+- Window remembers size/position across launches, per-screen.
+
+### Materials & visual
+- Platform material for window background: Mac `NSVisualEffectView` / `NSGlassEffectView` (Liquid Glass, macOS 26+); Win `DWMWA_SYSTEMBACKDROP_TYPE` mica / acrylic.
+- Dark mode follows system, no per-frame flicker.
+- Accent color follows system accent - don't hardcode brand blue.
+- System font: Mac `-apple-system, BlinkMacSystemFont`; Win `'Segoe UI Variable', 'Segoe UI'`.
+- No `box-shadow` for window shadows, no `border-radius` for window rounding - the OS draws those.
+
+### Scrolling
+- Overlay scrollbars on Mac (fade out) - let WebKit do it.
+- No smooth-scroll JS polyfills (`behavior: 'auto'`).
+- Scroll position persists across in-window navigation.
+
+### Motion
+- Cut between views by default - no route fades.
+- Honor `prefers-reduced-motion`.
+- Window resize animated by OS, not JS layout animations.
+- No loading skeletons for sub-200 ms ops (web idiom) - spinner or nothing.
+- No spring/bounce on simple state changes; reserve spring for grab-and-drag.
+
+### Keyboard
+- Full keyboard nav; focus rings match platform.
+- Native shortcuts (⌘F Mac, Ctrl+F Win); Escape always does something.
+- Type-ahead in lists.
+
+### File / drag-and-drop
+- Native drag-and-drop with file URLs (`NSPasteboard` / `IDataObject`), not browser drag API.
+- Drop files onto dock icon opens them (`application:openFiles:`).
+
+## How to use this reference
+
+1. Run the decision gate. If ruled out, stop and say so.
+2. If in scope, declare the seam for the feature in question.
+3. Walk the audit for the surface in scope; each unchecked item is a native-feel bug.
+4. Reconcile with `craft-guard`: craft rules apply above the seam, native conventions below it. Where they'd conflict (e.g. craft says skeleton, native says no skeleton <200ms), native-feel wins below the seam.
+
+Full depth (WebKit/WebView2 throttling fixes, IPC typing, memory measurement truths, Raycast binary evidence) -> install `native-feel-skill` and consult its `references/03-webview-survival.md`, `04-ipc-contract.md`, `05-memory-truths.md`, `07-evidence-raycast.md`.

package/skills/reference-intake/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: reference-intake
+description: Reference intake contract from screenshot, URL, design file, or product analogy. Use when the user supplies visual/product reference before build, or when Keep/Change/Do not copy boundaries are missing for a design ask.
+---
+
+# reference-intake
+
+Turn raw reference material into a **run-local declaration input** the pipeline can consume without re-deriving from chat.
+
+Not a style library. Not a code export. Not a Pass/Fail gate.
+
+Authority boundary (ADR-0011):
+
+| This skill owns | Does not own |
+| --- | --- |
+| Observed vs inferred evidence about the reference | `spec.md` L1→L6 |
+| Keep / Change / Do not copy | decision report / Fill source |
+| License and brand risk notes | evaluator verdict |
+
+## When to apply / skip
+
+**Apply** when the ask includes at least one of:
+
+- local screenshot / mock / design export path
+- URL of a live product or design
+- existing in-repo design artifact the user points at
+- explicit product or brand analogy ("like Linear", "参考飞书设置页")
+
+**Skip** when the ask is text-only product requirements with no reference material. Narrate once: `-> reference-intake?: no reference materials, skipped`.
+
+## Steps
+
+### 1. Inventory sources
+
+List every reference source. For each source record:
+
+- `kind`: `screenshot` | `url` | `design_file` | `product_analogy` | `other`
+- locator (path or URL or product name)
+- for files: SHA-256 when the file is readable; for URLs: the exact URL string
+- `captured_at` (ISO-8601) and `tool` (how it was collected)
+
+Write `manifest.json` under `.scratch/<run>/reference/` using the shape in [`references/contract-template.md`](references/contract-template.md). Copy durable local media into `reference/assets/` only when needed for later human review; never into the host Fill tree.
+
+**Done when:** every cited source appears in `manifest.json` with kind + locator; file sources that exist on disk carry `sha256`.
+
+### 2. Separate observed from inferred
+
+Read the sources. Fill **every required heading** from [`references/contract-template.md`](references/contract-template.md) (SSOT for section names and bullet prompts). Do not invent alternate headings.
+
+Mark every claim as **observed** or **inferred**. Unlabeled claims are invalid; rewrite them before emit.
+
+**Done when:**
+
+- `contract.md` has every template heading (including always/ask/never hints and Unresolved questions)
+- Keep / Change / Do not copy are each non-empty whenever any source is a product analogy, third-party URL, or third-party screenshot/design (first-party user-owned assets may put `none — first-party owned` under Do not copy only, with an ownership note)
+- at least one license/brand risk line exists (`none identified` only for pure first-party assets the user owns)
+
+### 3. Emit and stop
+
+Write:
+
+```text
+.scratch/<run>/reference/contract.md
+.scratch/<run>/reference/manifest.json
+.scratch/<run>/reference/assets/   # optional
+```
+
+Optional disposable `example.html` may be generated under `reference/` only as a later preview input. It is **not** a Fill source (same hard boundary as `preview/round-*.html`).
+
+Stop. Do not write `spec.md`, do not pick components, do not implement UI.
+
+**Done when:** both `contract.md` and `manifest.json` exist; steps 1→2 Done-when criteria still hold in the files.
+
+## Scope fence
+
+| In | Out → |
+| --- | --- |
+| Source inventory + hashes | L6 acceptance → `ux-spec` |
+| Keep / Change / Do not copy | template/component identity → `ui-picker` |
+| Functional constraints derived from reference | coding / Fill |
+| License and brand risk notes | visual similarity score as gate |
+| | third-party skill or brand-kit port into the plugin |
+
+## Handoff
+
+After emit, the orchestrator continues to `ux-spec?` (or `plan?` when spec already exists). Consumers must cite `reference/contract.md` rather than re-describing the screenshot from memory.

package/skills/reference-intake/references/contract-template.md

@@ -0,0 +1,82 @@
+# Reference contract template
+
+Emit as `.scratch/<run>/reference/contract.md`. Headings are required.
+
+## Source summary
+
+- Ask (one line):
+- Sources (ids matching `manifest.json`):
+- Captured at (ISO-8601; may match `manifest.json` top-level `captured_at`):
+
+## Evidence (observed)
+
+- ...
+
+## Inferred (labeled)
+
+- ... | confidence: high|medium|low | why:
+
+## Keep
+
+- ...
+
+## Change
+
+- ...
+
+## Do not copy
+
+- ...
+
+## Functional constraints for ux-spec
+
+- Goal / scene hints:
+- States or edges implied:
+- Non-goals implied by Do not copy:
+- always / ask / never hints:
+
+## Visual cues for ui-picker
+
+- Density:
+- Scene class hints:
+- Region weight / hierarchy:
+- Explicit exclusions:
+
+## License / brand risks
+
+- ...
+
+## Unresolved questions
+
+- ... (or `none`)
+
+---
+
+## manifest.json shape
+
+Write beside this contract as `.scratch/<run>/reference/manifest.json`:
+
+```json
+{
+  "schema": "design-playbook.reference.manifest/v1",
+  "run_id": "<run>",
+  "captured_at": "2026-07-22T00:00:00+08:00",
+  "tool": "reference-intake",
+  "sources": [
+    {
+      "id": "src-1",
+      "kind": "screenshot",
+      "locator": "assets/hero.png",
+      "sha256": "<hex or null>",
+      "note": "optional"
+    }
+  ]
+}
+```
+
+Rules:
+
+- `kind` is one of: `screenshot`, `url`, `design_file`, `product_analogy`, `other`
+- file locators are run-root-relative under `reference/` when copied into `assets/`
+- URL locators are absolute strings; `sha256` is null for pure URLs and product analogies
+- do not put host Fill paths into `sources`

package/skills/ui-evaluator/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: ui-evaluator
+description: Run evidence-backed UI acceptance. Use after generating a page, or when the user wants a design review or recirculatable critique against declared goals and success criteria.
+---
+
+# ui-evaluator
+
+**Evaluator** contract: turn **declarations** into checks. Do not invent new taste standards. Every issue **points back** to a declaration.
+
+## Steps
+
+### 1. Bind declarations
+
+Identify which of these apply to this surface (repo files, prior turns, or design-playbook defaults):  
+`spec` · `domain` · `craft` · `design` · `components` · `template`.
+
+When a verified `.scratch/<run>/design-baseline/state.json` binds a baseline (`status: ready`, path from `baseline.path`), include it as the project-specific visual declaration. It can support design-drift findings but is never L6 runtime proof by itself. An explicit `status: waived` disables baseline-drift checks for that run; it does not waive `spec`, accessibility, or craft checks.
+
+When `.scratch/<run>/reference/contract.md` exists (ADR-0011), you **may** use it as supporting context for findings about copied brand chrome, distinctive illustration, or other **Do not copy** breaches (`source` = `reference` or the owning declaration). It is **never** L6 proof and never a Pass/Fail gate by itself.
+
+**Done when:** the check set is named; if `spec` L6 exists, every criterion and its required proof are on the list.
+
+### 2. Run checks
+
+Walk every applicable row (exhaustive for bound declarations):
+
+| Check | Source |
+| --- | --- |
+| Empty / loading / error / permission | `spec` |
+| Risk color, secrets, dangerous ops | `domain` |
+| AI slop, hierarchy, purposeless motion | `craft` |
+| New surface drifts from confirmed project visual roles/patterns | bound `<binding.path>` |
+| Raw hex / px / ms (unlogged) | `design` |
+| Badge/Tag, Dialog/Drawer, … | `components` |
+| Shell matches scene | `template` |
+| Each L6 acceptance item | `spec` |
+| Required proof exists for each L6 item | `spec` |
+
+Dimension selection, 回流示例, the preview-seam health check (required when the run produced `preview/` artifacts), and the **observe\* mirror-surface** finding (required when any manifest capture notes `surface: mirror`): [`references/rubric.md`](references/rubric.md).
+
+When `.scratch/<run>/craft-guard.md` exists, consume all eight `CRAFT-01` through `CRAFT-08` rows as supporting craft input. Detector rows are advisory: verify their rendered/source evidence and exception checks, then use the authoritative recirculate map below to choose declaration source and assign severity. A detector never decides source, severity, or verdict. Carry every `blocked` row into evaluation as a craft proof gap. Implemented UI cannot claim complete craft Pass while required rendered or source proof is blocked; planning-only work may record an explicit `N/A` rationale without claiming rendered inspection. Keep craft detector rows out of the G6 manifest and L6 evidence ledger: they are craft-stage audit records, not runtime artifacts or criterion results.
+
+Record an evidence ledger before writing findings. Every L6 criterion has exactly one row:
+
+```text
+criterion: L6.<n>
+required:  <declared proof>
+observed:  <artifact path, interaction, check result, or missing>
+result:    pass|fail|blocked|N/A
+```
+
+`observed` is either an **artifact path** (relative to the run root, e.g. `evidence/L6.3-error.png`) when a runtime capture was bound by a manifest, or **free-text** describing a manual observation. Both are legitimate; the machine seam (G6) only validates artifact-path references. When using an artifact path, keep the path as the **leading token** of the line (e.g. `observed: evidence/L6.3-error.png`); trailing commentary is tolerated by G6 — it reads the leading token, breaking on whitespace, `(` / `（`, or `,` / `，` / `:` / `：`. Other punctuation (em dash, slashes, etc.) will be treated as part of the path, so put elaboration on a separate `note:` line for clarity when unsure.
+
+Evidence is captured, not judged. A manifest entry records that an artifact was collected at a state — it does not say the criterion passed. `pass`/`fail` is this evaluator's verdict against `required` vs `observed`; a screenshot can prove a criterion false. Three ledgers, each one authority: `spec` L6 names **what to prove**; the manifest records **what happened**; this ledger decides **what it means**. Providers produce artifacts; the manifest binds them to criteria; the evaluator decides.
+
+For implemented UI, visible-state proof is a rendered inspection at the declared target viewport; behavior proof is an interaction trace or automated check; code-health proof is the relevant available test, type/lint, or affected build result. Planning-only proof is declaration coverage and must not claim a render or test occurred. Non-L6 declaration checks may be supporting observations or findings; they do not enter the machine ledger.
+
+**Done when:** every bound row was considered; every L6 criterion has exactly one non-empty `criterion / required / observed / result` row keyed as `L6.<n>`; results use only `pass|fail|blocked|N/A`; unavailable required proof is `blocked`, not skipped.
+
+### 3. Emit point-back findings
+
+```text
+issue:    <observable>
+source:   <declaration>
+fix:      <next edit>
+severity: high (blocking)|high|med|low
+```
+
+Order: **blocking** first (broken L5/L6, unsafe dangerous ops, removed focus rings), then polish.
+
+**Done when:** every finding has all four fields; no “generally improve the design” lines.
+
+### 4. Verdict
+
+- Emit exactly one `## Verdict` section containing exactly one anchored verdict: `Pass` or `Recirculate`.
+- **Pass:** zero blocking; every L6 criterion has exactly one evidence row; every required evidence row passes (every evidence result is `pass`); token gaps are logged or fixed.
+- **Recirculate:** each blocking `source` names the step/declaration to reopen in design-playbook; `fail` or `blocked` evidence remains visible.
+
+For a repaired blocker, record exactly one closure line whose issue text is identical to the finding:
+
+```text
+- closes: <exact issue value> -> recirculate -> fix -> re-eval -> 0 blocking
+```
+
+**Done when:** the explicit verdict is structurally unique; blocking sources are non-empty; every blocking finding has exactly one matching closure before `Pass`. A blocking finding cannot be waived inside a Pass artifact. Without a user in the loop, blocking findings remain in recirculate and the run requests a decision; only after an explicit user decision that updates the owning declaration or severity — recorded against the user's statement or decision record — may the evaluator re-evaluate; the final Pass artifact contains no blocking severity.
+
+The artifact shape behind this verdict is machine-checkable: `scripts/validate_run.py` gates L1-L6, ordered `Given -> When -> Then` in every top-level L6 item, one non-empty four-field evidence row per `L6.<n>`, allowed evidence results, all-pass evidence for `Pass`, four non-empty finding fields, one explicit verdict, and one exact issue-linked closure per blocking finding. These checks are the completion criteria above, not extra prose.
+
+## Recirculate map (authoritative)
+
+Single source of truth for the observable -> declaration routing. The orchestrator and other skills point here; do not duplicate it.
+
+| Observable | Declaration |
+| --- | --- |
+| Happy path only; empty/fail/auth missing | `spec` |
+| Wrong business meaning / risk / secrets | `domain` |
+| AI slop, flat hierarchy, purposeless motion | `craft` |
+| New UI visually conflicts with confirmed existing-product baseline | bound `<binding.path>` |
+| Scattered hex/px/ms | `design` |
+| Badge↔Tag, Dialog↔Drawer mixups | `components` |
+| Wrong page shell (e.g. list as card wall) | `template` |
+| Desktop app feels like a web page / wrong seam | `native-craft` |
+| Copied third-party brand / Do not copy breach | `reference` (supporting) → fix in Fill / re-intake |
+| Critique with no owner | re-run `ui-evaluator` |
+
+Fix only the owning layer, then resume from the pipeline step that consumes it.
+
+## Guard
+
+Prefer positive fixes in `fix`. Reserve bans for non-negotiables (e.g. open dangerous action without confirm) and always pair with the required behavior.