design-playbook 0.7.0

package/skills/craft-guard/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: craft-guard
+description: UI craft and feedback quality. Use when polishing product UI (motion, loading/error feedback) or when a page reads as AI slop.
+---
+
+# craft-guard
+
+**Craft** declaration for cross-product quality: hierarchy, wait feedback, purposeful motion, CJK-safe type. Does not own business risk (`domain`) or token inventory (`design`).
+
+When a verified design-baseline binding exists (`status: ready`), use that path as the project-specific visual baseline. Report clear divergence (density, type, spacing, shape, motion, or primitive treatment) to `ui-evaluator` with source set to the bound path; do not replace valid project choices with this skill's generic taste defaults.
+
+## Apply (checklist)
+
+Treat as exhaustive for the surface under edit.
+
+### Hierarchy and type
+
+- One clear primary; secondary recedes via density/space, not rainbow chrome.  
+- CJK UI uses the project Chinese stack (`var(--font-cn)` or equivalent).  
+- Brand solid + brand-gradient **≤ 3** emphasis hits per viewport; neutrals carry the rest.
+
+**Done when:** a cold reader can name the primary action/region in one glance.
+
+### Loading tiers
+
+```text
+<300ms      no indicator
+300ms–2s    skeleton (layout stable)
+>2s         loader + what is happening
+>10s        timeout + retry (or cancel)
+```
+
+**Done when:** every async path in scope maps to a tier with a next action on failure/timeout.
+
+### Motion
+
+- UI motion ≤ 300ms; animate `transform` / `opacity` only.  
+- Each animation names the state change it explains.  
+- Honor `prefers-reduced-motion`. Keyboard-triggered actions stay free of decorative motion.
+
+**Done when:** every motion in scope states the state change it explains.
+
+### AI slop → target look
+
+For implemented UI, run all eight checks in [`references/detectors.md`](references/detectors.md) against rendered UI plus relevant source. Write exactly one `clear|hit|blocked` row per detector to `.scratch/<run>/craft-guard.md`. Detector output is advisory: record evidence, exception check, and positive fix; leave declaration source, severity, and verdict to `ui-evaluator`. Missing proof is `blocked`, not a silent clear.
+
+| Push toward | Instead of default sludge |
+| --- | --- |
+| Accent on key noun + primary CTA | Purple–blue gradient wallpaper |
+| Glass only on rare floating layers | Blur on every card |
+| Project CJK stack | Inter/Roboto as Chinese body |
+| Weighted modules | Equal white card grid |
+| State-explaining motion | Bounce/elastic decoration |
+
+[`references/craft.md`](references/craft.md) — **required when the surface has L4 interactive zones** (per-zone hover/motion affordance, with its own Done when); also holds edge craft (failure/permission feedback, 圆角/阴影, charts).
+
+## Completion
+
+**Done when:** hierarchy, every in-scope wait/fail path, every animation, and — when the surface has L4 interactive zones — every zone's affordance (per `references/craft.md`) pass their checks; implemented UI also has all eight detector rows with no unexplained missing proof. Residual hits and blocked proof are handed to `ui-evaluator`; detector rows do not assign source, severity, or verdict.

package/skills/craft-guard/references/craft.md

@@ -0,0 +1,29 @@
+# craft 细则
+
+## 状态反馈
+
+等待分层归 `SKILL.md` loading tiers；此处只管失败与降级：
+
+- 失败：原因 + 可恢复动作（重试/忽略/查看日志）
+- 权限不足：禁用 + 需要的权限说明
+
+## 工艺
+
+- 嵌套圆角与间距分层，忌全站同一圆角同一阴影
+- 阴影档位少而稳；层级靠 surface 不靠彩虹边
+- 中英混排：中文行高与标点优先
+
+## 交互 affordance（L4 交互区，grill v0.3 Q3.4）
+
+每个 L4 声明的交互区（行、卡片、按钮组、可点单元）须有有意的 motion/hover affordance，且在 craft review 里说明用途：
+
+- 默认 hover/active 有过渡（opacity / transform / background 之一，~120ms），用途写在 craft 报告（如「行可点 → 提示可进入详情」「行只读 → 不加 hover」）。
+- 静态 throwaway 也得体现 affordance 目标：要么给出 hover，要么显式声明「此区只读，无 hover」——不允许「交互区既无 hover 又无声明」的静默 PASS。
+- 数据表/list 的 ledger 行尤其易漏：扫描密集时 hover 是可扫描性 affordance，不是装饰。
+
+**Done when：** 每个 L4 交互区都有 motion/hover purpose（给出或显式声明只读）；无静默漏 hover 的交互区。
+
+## 图表
+
+- 分类色稳定可复述；风险色回 `domain`
+- 容器与坐标可读，不为「炫」牺牲扫描

package/skills/craft-guard/references/detectors.md

@@ -0,0 +1,124 @@
+# Craft detector protocol
+
+Run all eight detectors for implemented UI. Inspect rendered UI at declared target viewports and relevant source. Generic detector taste never overrides a verified project baseline; safety, usability, and explicit declarations still do.
+
+Record exactly one row per detector in `.scratch/<run>/craft-guard.md`:
+
+```text
+| ID | Status | Rendered evidence | Source evidence | Exception check | Positive fix |
+| CRAFT-01 | clear|hit|blocked | observable or missing proof | source location or missing proof | applied exception or none | required for hit; `-` otherwise |
+```
+
+Allowed status is `clear`, `hit`, or `blocked`. `blocked` names missing proof. Detector rows are advisory: do not assign declaration source, severity, or verdict. `ui-evaluator` owns those decisions.
+
+## CRAFT-01 — Primary hierarchy
+
+**Purpose:** Detect absent or competing primary actions and regions.
+
+**Rendered signals:** More than one element claims primary emphasis, or no action/region leads the scan.
+
+**Source signals:** Multiple primary variants, equivalent emphasis tokens, or page structure without a main landmark.
+
+**Legitimate exceptions:** Deliberate equal-choice comparison supported by spec or verified baseline.
+
+**Owner hint:** `craft` for emphasis; `template` when shell composition causes conflict.
+
+**Positive fix:** Preserve one scene-appropriate primary and make secondary actions recede through placement, density, or neutral treatment.
+
+## CRAFT-02 — Repeated card wall
+
+**Purpose:** Detect undifferentiated card grids replacing useful information structure.
+
+**Rendered signals:** Most content appears as equal floating cards with no scanning hierarchy or task grouping.
+
+**Source signals:** Repeated card wrappers applied to unrelated regions or list/table records without a card-specific interaction.
+
+**Legitimate exceptions:** Browsable collections where each item is a genuinely independent object and the verified baseline uses cards.
+
+**Owner hint:** `template` for scene structure; `craft` for visual weighting.
+
+**Positive fix:** Use list, table, band, or unframed grouping that matches comparison and action needs; reserve cards for independent items.
+
+## CRAFT-03 — Nested or floating containers
+
+**Purpose:** Detect cards inside cards and page sections styled as decorative floating panels.
+
+**Rendered signals:** Multiple nested borders, radii, shadows, or detached section surfaces obscure ownership.
+
+**Source signals:** Card components nested for spacing, or full-width sections wrapped in decorative card primitives.
+
+**Legitimate exceptions:** A real framed tool, modal, or repeated item nested within an unframed page region.
+
+**Owner hint:** `template` for section composition; `components` for wrong primitive identity.
+
+**Positive fix:** Flatten page regions, use spacing and dividers for grouping, and retain a frame only where interaction semantics require one.
+
+## CRAFT-04 — One-note palette
+
+**Purpose:** Detect hue dominance that erases semantic contrast and hierarchy.
+
+**Rendered signals:** Backgrounds, surfaces, accents, and states rely on variations of one hue family.
+
+**Source signals:** One color ramp fills unrelated semantic roles or repeated gradients replace neutral surfaces.
+
+**Legitimate exceptions:** Verified monochrome brand systems with sufficient state, contrast, and hierarchy differentiation.
+
+**Owner hint:** `design` for token roles; `craft` for emphasis distribution.
+
+**Positive fix:** Keep brand color selective, restore neutral surfaces, and use semantic colors only for named roles.
+
+## CRAFT-05 — Shape and pill overuse
+
+**Purpose:** Detect excessive rounded containers and text pills where familiar controls fit.
+
+**Rendered signals:** Most labels, actions, and containers share pill geometry or oversized rounding.
+
+**Source signals:** Large border-radius tokens applied globally, or text-in-rounded-rectangle controls replacing icons, toggles, tabs, or badges.
+
+**Legitimate exceptions:** Verified brand geometry or semantic chips/tags whose shape communicates grouping or status.
+
+**Owner hint:** `components` for control identity; `design` for radius tokens; `craft` for repetition.
+
+**Positive fix:** Use control-specific primitives and restrained radii; reserve pills for semantics that need compact grouping.
+
+## CRAFT-06 — Type-scale mismatch
+
+**Purpose:** Detect typography whose scale conflicts with container and workflow density.
+
+**Rendered signals:** Hero-sized copy dominates compact panels, or hierarchy depends on oversized text instead of structure.
+
+**Source signals:** Display tokens used in cards, toolbars, dashboards, or narrow controls without a true hero context.
+
+**Legitimate exceptions:** Literal landing-page hero or verified expressive product surface with stable responsive fit.
+
+**Owner hint:** `design` for type roles; `craft` for contextual hierarchy.
+
+**Positive fix:** Match type role to container and task density, using structure and weight before display scale.
+
+## CRAFT-07 — Text-as-control and icon misuse
+
+**Purpose:** Detect verbose rounded text controls where familiar symbols or dedicated controls communicate better.
+
+**Rendered signals:** Repeated Undo, Close, Save, formatting, color, or binary actions consume space as text buttons.
+
+**Source signals:** Text buttons replace available icon buttons, swatches, segmented controls, toggles, or checkboxes.
+
+**Legitimate exceptions:** Unfamiliar, high-risk, or ambiguous actions that require explicit text; accessibility names remain required for icons.
+
+**Owner hint:** `components` for primitive choice; `craft` for density and recognition.
+
+**Positive fix:** Use familiar icon/control primitives with accessible names and tooltips where recognition needs support.
+
+## CRAFT-08 — Decorative or purposeless motion
+
+**Purpose:** Detect motion that explains no state change or destabilizes interaction.
+
+**Rendered signals:** Bounce, elastic, looping, or entrance motion draws attention without communicating state.
+
+**Source signals:** Animation targets layout properties, lacks reduced-motion handling, or has no named state transition.
+
+**Legitimate exceptions:** Expressive game or immersive scene motion declared by product intent and kept clear of task controls.
+
+**Owner hint:** `craft` for motion purpose; `design` for motion tokens.
+
+**Positive fix:** Remove decorative motion or replace it with short transform/opacity feedback tied to a named state change.

package/skills/design-baseline/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: design-baseline
+description: Discover, validate, or draft a project-owned DESIGN.md before adding or revising UI in an existing frontend. Use during design-playbook initialization when a repository already has pages, components, themes, tokens, or styles; when new UI looks inconsistent with existing surfaces; when DESIGN.md may be missing, incomplete, conflicting, or stale; or when the user asks to generate a design system from existing frontend source. Produces a provenance-backed draft and requires confirmation before creating or replacing the durable baseline.
+---
+
+# design-baseline
+
+Establish one project-owned visual authority before UI decisions or Fill. Treat existing code and rendered pages as evidence, not as permission to silently rewrite `DESIGN.md`.
+
+## Authority boundary
+
+| This skill owns | Does not own |
+| --- | --- |
+| Discovering and structurally validating project `DESIGN.md` | Functional success criteria (`spec` L1–L6) |
+| Extracting a draft from first-party frontend source | Third-party reference Keep/Change/Do not copy (`reference-intake`) |
+| Source hashes, observed/inferred labels, confidence, unresolved gaps | Component/template selection (`ui-picker`) |
+| Confirmation before a durable baseline write | Pass/Fail verdict (`ui-evaluator`) |
+
+Canonical authority is `<project-root>/DESIGN.md`. Accept `.stitch/DESIGN.md` as a compatibility candidate only. If both exist with different content, stop for an explicit user choice; never merge them silently.
+
+## Deep module (SSOT for deterministic work)
+
+All path resolution, scanning, drafting, hashing, durable write, and re-verification live in one module:
+
+[`scripts/design_baseline.py`](scripts/design_baseline.py)
+
+Public interface:
+
+```python
+prepare(project_root, run_root) -> state
+confirm(project_root, run_root, decision, reason=None) -> state
+verify(project_root, run_root) -> state
+```
+
+CLI:
+
+```text
+python scripts/design_baseline.py prepare <project_root> <run_root>
+python scripts/design_baseline.py confirm <project_root> <run_root> --decision accept|waive [--reason ...]
+python scripts/design_baseline.py verify  <project_root> <run_root>
+```
+
+State is a cache, not authority. Every public call resolves paths against the supplied project root. `verify` re-hashes the bound baseline and its first-party sources before returning a downstream binding. Fill and other consumers may only use a binding that just passed `verify`.
+
+| `status` | Meaning |
+| --- | --- |
+| `ready` | Bound baseline (`decision.kind` = `existing` or `accepted`) |
+| `needs_confirmation` | Provenance-backed draft awaits accept/waive |
+| `waived` | Explicit user waiver with non-empty reason |
+| `ambiguous` | Conflicting candidates; human choice required |
+
+## Workflow
+
+### 1. Classify the project
+
+Apply the existing-product gate when the requested build or fix adds/revises UI and the repository already contains meaningful first-party UI: pages/routes, shared components, theme or token files, global styles, or shipped screenshots/stories.
+
+Skip for answer-only, review-only, diagnosis-only, or planning-only work that will not change UI. Skip the entry gate for a true greenfield repository with no existing visual surface. Narrate either skip in one line.
+
+**Done when:** the run records `existing-product` or `greenfield`, with the file signals used for that classification.
+
+### 2. Prepare (`prepare`)
+
+Run `prepare(project_root, run_root)`. Deterministic code:
+
+- discovers `DESIGN.md` / `.stitch/DESIGN.md` (rejects escaping symlinks);
+- validates a complete existing baseline in place;
+- or scans first-party theme/token/style/component/page sources, writes `evidence.json` + `DESIGN.draft.md`, and returns `needs_confirmation`;
+- writes `.scratch/<run>/design-baseline/state.json` (`schema: design-baseline/v1`).
+
+Agent work after prepare:
+
+- if `status` is `ready` → cite path + sha256 and continue;
+- if `ambiguous` → stop for the smallest user decision; never invent a third authority;
+- if `needs_confirmation` → review the draft; optionally enrich only material claims with `[inferred confidence=…]` **in the draft file**, then re-run prepare if structure/sources changed (do not hand-edit hashes).
+
+Never write or overwrite project `DESIGN.md` in this step.
+
+**Done when:** `state.json` exists with one of the four statuses above; drafts carry source paths + SHA-256 and observed/inferred labels.
+
+### 3. Confirm or waive (`confirm`)
+
+Show a compact summary: atmosphere, core tokens, typography, layout, primitives, conflicting evidence, inferred claims. Ask before the durable write.
+
+- **Accept:** `confirm(..., decision="accept")` atomically writes canonical `<project-root>/DESIGN.md` from the bound draft and returns a `ready` state.
+- **Waive:** `confirm(..., decision="waive", reason=<user reason>)` does not write `DESIGN.md`. Existing-product Fill may continue only after this explicit waiver.
+- **Revise:** edit only the draft (or fix sources), then `prepare` again.
+
+Never infer acceptance from silence. Never replace a valid baseline merely because extraction found different implementation details; report the drift for a decision.
+
+**Done when:** `state.json` is `ready` (existing or accepted) or `waived` with a non-empty reason.
+
+### 4. Verify before Fill (`verify`)
+
+Immediately before Fill (and any time a consumer needs a binding), call `verify(project_root, run_root)`.
+
+- Re-checks path containment, baseline hash, source freshness, and provenance alignment.
+- Rejects forged `state.json`, stale sources, candidate conflicts, and symlink escape.
+- On success, returns the binding: baseline path + sha256 (or an explicit waiver).
+
+Downstream may only consume this verified result — not a hand-edited confirm file and not a draft.
+
+**Done when:** `verify` returns without error; the decision report can cite `design-baseline: <path> sha256:<digest>` or `waived:<reason>`.
+
+### 5. Bind downstream consumers
+
+| Consumer | Required behavior |
+| --- | --- |
+| `ui-picker` | Cite the verified baseline in the decision report; preserve visual roles, density, layout, and component conventions unless a declared change is approved |
+| Fill | Use project tokens and primitives; log missing roles instead of inventing raw values; gate on successful `verify` |
+| `craft-guard` | Treat obvious baseline drift as a craft failure, not merely personal taste |
+| `ui-evaluator` | Point observable drift back to `DESIGN.md`; the baseline is supporting declaration evidence, never L6 runtime proof by itself |
+
+Third-party or sample `DESIGN.md` files remain `reference-intake` inputs. They never become project authority automatically.
+
+## Artifacts
+
+```text
+<project-root>/DESIGN.md                            # durable authority after accept
+.scratch/<run>/design-baseline/state.json           # gate cache (schema design-baseline/v1)
+.scratch/<run>/design-baseline/evidence.json        # extraction evidence (when drafted)
+.scratch/<run>/design-baseline/DESIGN.draft.md      # proposal; never authority by itself
+```
+
+The deep module `prepare`/`confirm`/`verify` is the sole gate surface. An adopted existing `DESIGN.md` only needs to carry verifiable source provenance (path + SHA-256 under `## Source Evidence & Confidence`) to be bound; the other section names in [`references/design-template.md`](references/design-template.md) are draft guidance, not a structural contract imposed on hand-written baselines.
+
+## Scope fence
+
+| In | Out → |
+| --- | --- |
+| First-party visual baseline and provenance | Functional behavior → `ux-spec` |
+| Existing-source extraction | External inspiration → `reference-intake` |
+| Confirmation before durable write | Scene/template/component decision → `ui-picker` |
+| Baseline drift source for point-back | Runtime evidence judgment → `ui-evaluator` |

package/skills/design-baseline/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Design Baseline"
+  short_description: "Discover, validate, or draft project DESIGN.md"
+  default_prompt: "Use $design-baseline to inspect this project's existing UI and establish a confirmed DESIGN.md baseline before adding a new page."

package/skills/design-baseline/references/design-template.md

@@ -0,0 +1,73 @@
+---
+name: "<project-name>"
+colors:
+  background: "<#hex-or-token>"
+  surface: "<#hex-or-token>"
+  text: "<#hex-or-token>"
+  primary: "<#hex-or-token>"
+---
+
+# Design System: <project-name>
+
+## Visual Theme & Atmosphere
+
+- [observed] <dominant visual character and evidence>
+- [inferred] <design intent, with confidence>
+
+## Color Palette & Roles
+
+### Foundation
+
+- `<token or value>` — <background/surface role>
+
+### Interactive and Functional
+
+- `<token or value>` — <primary/success/warning/error role>
+
+### Text Hierarchy
+
+- `<token or value>` — <primary/secondary/muted role>
+
+## Typography Rules
+
+- Font families: <families and fallbacks>
+- Hierarchy: <display/heading/body/label sizes, weights, and line heights>
+- Usage: <where each role appears>
+
+## Component Stylings
+
+- Buttons: <shape, variants, states, spacing>
+- Containers/cards: <radius, border, elevation, padding>
+- Navigation: <layout and active states>
+- Inputs: <shape, focus, validation, touch target>
+- Domain primitives: <project-specific components>
+
+## Layout Principles
+
+- Container/grid: <width, columns, alignment>
+- Spacing: <base unit and density>
+- Responsive behavior: <breakpoints and collapse rules>
+
+## Motion & Interaction
+
+- Timing/easing: <tokens or observed values>
+- State transitions: <hover/focus/pressed/loading>
+- Reduced motion: <behavior>
+
+## Accessibility
+
+- Contrast and color semantics: <rules>
+- Focus and keyboard: <rules>
+- Touch targets and text scaling: <rules>
+
+## Source Evidence & Confidence
+
+- path: `src/path/to/high-signal-file`
+  sha256: `<64-lowercase-hex-digest>`
+  captures: <tokens/theme/layout/components>
+  confidence: <high|medium|low>
+
+## Known Gaps & Exceptions
+
+- <contradiction, unverified inference, legacy override, or missing state>
+

package/skills/design-baseline/references/extraction-guidance.md

@@ -0,0 +1,39 @@
+# Existing UI extraction guidance
+
+Use source precedence to separate intended design rules from accidental one-offs.
+
+## 1. Discover the frontend shape
+
+Identify framework and styling signals from manifests and configuration. Map pages/routes, shared components, global styles, themes/tokens, fonts, assets, and stories/screenshots. Ignore generated output, dependencies, caches, and vendored UI.
+
+Classify the project as existing-product only when meaningful first-party UI exists. A dependency on React/Vue/Svelte alone is not enough.
+
+## 2. Read sources in precedence order
+
+1. Explicit tokens and theme files.
+2. Global CSS variables, Tailwind/theme configuration, font declarations.
+3. Shared primitives: buttons, inputs, cards, navigation, dialogs.
+4. Two to five representative pages covering dominant and edge-case layouts.
+5. Rendered evidence when the app can be inspected safely.
+
+Higher-precedence sources express intent. Lower-precedence sources prove what shipped. Record conflicts; do not hide them by averaging values.
+
+## 3. Extract by functional role
+
+- Colors: background, surface, text hierarchy, interaction, semantic state.
+- Typography: family, scale, weight, line height, letter spacing, usage.
+- Layout: container width, grid, density, spacing unit, responsive collapse.
+- Components: shape, variants, states, focus, elevation, domain primitives.
+- Motion: duration, easing, state change, reduced-motion handling.
+- Accessibility: contrast intent, focus visibility, keyboard, touch targets.
+
+Consolidate near-duplicate values only when their role is demonstrably the same. Keep unexplained divergence under Known Gaps & Exceptions.
+
+## 4. Preserve provenance
+
+For every high-signal source included in the baseline, record its project-relative path and SHA-256. Label design claims `[observed]` when directly supported and `[inferred]` when synthesized. Give inferred claims a confidence level and expose unresolved contradictions.
+
+## 5. Draft, then confirm
+
+Generate only `.scratch/<run>/design-baseline/DESIGN.draft.md`. Compare it with representative existing pages. Present the meaningful design rules and conflicts to the user. A draft becomes `<project-root>/DESIGN.md` only after explicit confirmation.
+