design-playbook 0.7.0

package/skills/ui-evaluator/references/rubric.md

@@ -0,0 +1,45 @@
+# evaluator rubric
+
+## 维度如何选
+
+- **落地页**：设计质量 / 原创性 / 工艺 / 功能
+- **控制台**：设计质量 / 可用性 / 信息密度 / 工艺 / 一致性
+
+维度从场景读出，引擎不写死；**判据必须能回到声明**。
+
+## 回流示例
+
+| 发现 | 表层说法 | 回指 |
+| --- | --- | --- |
+| 失败无重试 | 交互不完整 | `spec` 状态流 |
+| 高危灰标签 | 颜色不醒目 | `domain` + `components` |
+| 按钮硬编码 hex（如 `#4f46e5`） | 代码不规范 | `design` token |
+| 列表变卡片墙 | 版式不对 | `template` |
+
+## 禁止
+
+- 「整体还可以优化」无指征
+- 只改 CSS 不回到声明
+- 用新审美词覆盖未写清的 L5
+
+## preview seam 健康（supporting，ADR-0008）
+
+若该 run 跑了 `preview*`（`.scratch/<run>/preview/log.md` + `confirm-round-*.json` 存在），把它列为 supporting finding：
+
+- 读 `preview/log.md` + confirm json：反馈是否驱动了 revision，还是空/无关锚点滑过结构 floor。`decision-round-*.json` 仅用于审计/恢复，不是确认权威或第二份语义输入（ADR-0013）。
+- 结构 floor（adapter，G5）只挡空反馈/无注释锚点；**语义**问题（如「安师大」这种与被批注元素无关的合法字符串）floor 挡不住，靠这里兜。
+- `source` 归 `preview* seam`（orchestrator 的 preview 步骤契约），不是 UI source —— 当缺陷在 adapter loop 契约而非生成 UI 本身时用这个。
+- 过程缺口（seam 契约）与产品 findings（UI）分开记；不混在回流闭包 trail 里。
+
+## observe* mirror surface（supporting）
+
+若 `evidence/manifest.jsonl` 任一条 capture 声明 **`surface: mirror`**（或等价 note），必须有 finding：
+
+```text
+issue:    observe used semantic mirror, not live Fill host
+source:   observe* seam
+fix:      re-capture on live host URL when available; keep surface: mirror until then
+severity: low
+```
+
+Do not treat G6 artifact presence alone as proof the Fill tree was runtime-verified.

package/skills/ui-picker/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ui-picker
+description: UI shell and component semantics. Use when scaffolding a product page (list, dashboard, settings, detail, agent-admin), or when the wrong template/Badge-Tag pairing is about to be coded.
+---
+
+# ui-picker
+
+Before code: map the job to a **template** (shell) and **component semantics**. Appearance follows meaning.
+
+## Steps
+
+### 1. Density + scene
+
+Choose density (console-tight vs marketing-loose) and scene class (list / detail / settings / dashboard / editor / agent-admin / …).
+
+When a verified `.scratch/<run>/design-baseline/state.json` binds a baseline (`status: ready` from `design_baseline.verify`), read that binding path first (`baseline.path`, usually `DESIGN.md` or `.stitch/DESIGN.md`). It is the project-specific authority for atmosphere, visual roles, density, layout, motion, and component conventions. Preserve it unless the requested change explicitly revises the baseline.
+
+When `.scratch/<run>/reference/contract.md` exists (ADR-0011), read its **Visual cues for ui-picker**, Keep/Change, and Do not copy / exclusions. Use them as input for density, scene, region weight, and risks — never as hex tokens or as a license to copy brand chrome.
+
+**Done when:** one scene label and one density choice are explicit; a bound baseline is cited by path + SHA-256; if a reference contract exists, the decision report's risks or exclusions surface its Do not copy / brand risks (path citation is enough).
+
+### 2. Template
+
+Read [`references/template.md`](references/template.md). Assign main / side / action / status regions.
+
+**Done when:** each region maps to a duty from `spec` L2 (or a stated gap in the spec).
+
+### 3. Components
+
+Read [`references/components.md`](references/components.md). For each field/action, pick by **role** (status vs category vs confirm vs detail).
+
+Load only if needed:
+
+- business risk / desensitize → [`references/domain.md`](references/domain.md)
+- token roles while deciding surfaces → verified `<binding.path>` first, then generic fallback [`references/design.md`](references/design.md)
+
+**Done when:** every primary datum/action has a named component role; easy-mix pairs (Badge/Tag, Dialog/Drawer, Dropdown/Menu/Command) are resolved in writing.
+
+### 4. Decision report
+
+Write, then wait for confirmation if the user is in the loop:
+
+```text
+design-baseline: <binding.path> sha256:<digest> | waived:<reason>
+scene:
+density:
+template:
+regions: …
+components: …
+baseline-changes: none | <explicitly approved change>
+risks: …
+```
+
+**Done when:** the report exists, records the bound baseline or explicit waiver, and coding has not started without it.
+
+### Branch — structure still open
+
+If template is underdetermined, offer 2–3 IA variants (same `spec`, different main-region weight), one-line tradeoff each, pick one, then complete step 4.
+
+## Defaults that hold
+
+- Brand color as token/role, not a hex literal.  
+- Easy-mix pair semantics and shell 禁用 rules live in `references/components.md` and `references/template.md` — resolve against those tables, not from memory.

package/skills/ui-picker/references/components.md

@@ -0,0 +1,31 @@
+# components（组件语义）
+
+## 登记四层
+
+| 层 | 要声明 |
+| --- | --- |
+| 来源 | shadcn / 自有 / 业务定制 |
+| 语义角色 | 状态 / 分类 / 动作 / 容器 / 导航 / 反馈 |
+| 变体与状态 | size、variant、loading、disabled… |
+| 组合边界 | 允许/禁止嵌套与替代 |
+
+## 易混
+
+| 对 | 差别 |
+| --- | --- |
+| Badge / Tag | 状态·计数 vs 分类·可选·可移除 |
+| Modal / Dialog / Drawer | 打断程度、信息密度、退出方式 |
+| Tabs / Tabs-Switch | 同空间视图 vs 模式/口径 |
+| Dropdown / Menu / Command | 局部选择 / 动作集 / 搜索式操作 |
+
+## Illustrative mapping (agent-ops list row)
+
+Generic example — adapt per product; not a fixed template.
+
+| Datum | Role | Component |
+| --- | --- | --- |
+| running / failed | run status | Badge |
+| high-risk | risk | RiskBadge (+ domain) |
+| instance type / environment | category | Tag |
+| view log | inline action | Link/Button |
+| retry | recovery action | Button |

package/skills/ui-picker/references/design.md

@@ -0,0 +1,21 @@
+# design.md（视觉系统执行约束）
+
+## 意图（默认）
+
+- CJK-first；控制台密度优先；品牌色克制；中性色承层级。
+
+## 角色示例
+
+- `--brand` 主 CTA
+- `--brand-surface` 选中行/软徽章
+- `--foreground-link` 正文链接
+- `--warning-high` 高风险
+- `--chart-1..12` 多系列图
+
+## 执行三律
+
+1. 所有视觉值走 `var(--*)`
+2. hover/active/disabled/selected 从基础 token 派生
+3. 找不到 token：记 `gaps.log` + 合法 fallback 或拒生成该细节
+
+禁止裸写 hex、随意 px/ms/cubic-bezier 字面量绕过系统。

package/skills/ui-picker/references/domain.md

@@ -0,0 +1,26 @@
+# domain（领域语义，可按产品替换）
+
+## 任务状态
+
+| 状态 | 表达 |
+| --- | --- |
+| 排队 | 中性，不示风险 |
+| 运行中 | 正常进行 |
+| 完成 | 成功 |
+| 失败 | 必须提供恢复动作 |
+| 超时 | 原因 + 后续操作 |
+
+## 风险色（示例 token 角色）
+
+- 高危 → `var(--warning-high)`
+- 可疑 → `var(--warning-medium)`
+- 低风险 → `var(--warning-low)` 或 `var(--info)`
+
+## Data safety
+
+- Secrets, credentials, account IDs, host IPs default to masked
+- Plaintext requires explicit click; reveal action may be audited
+
+## 危险操作
+
+关闭防护、批量删除、解除高危屏蔽等：二次确认 + 写清后果，禁止「确定吗？」空确认。

package/skills/ui-picker/references/template.md

@@ -0,0 +1,24 @@
+# template（页面骨架声明）
+
+## 看板 / 调度（默认示例）
+
+- **场景**：任务调度、运行监控、队列、批处理进度。
+- **骨架**：
+  - 顶：总览指标
+  - 主：任务列表或任务流
+  - 侧：趋势、队列压力、失败原因
+  - 操作：刷新、批量重试、暂停等
+- **密度**：控制台密度；总览只承载核心指标；图不抢主列表。
+- **禁用**：营销落地页、纯图表大屏、sample/playground 当生产。
+
+## 列表页
+
+- 筛 + 表 + 行操作 + 空/载/错；批量区与主表同级可见。
+
+## 详情页
+
+- 标题元信息 + 主内容 + 次级 tabs/侧栏；危险操作有确认。
+
+## 设置页
+
+- 分组表单 + 保存反馈；不把设置塞进随意 Modal 墙。

package/skills/ux-spec/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ux-spec
+description: Declaration-first UI spec (six-layer spec.md). Use when turning a short product/UI ask into six-layer spec.md, or when goal, edge-state, acceptance, or evidence requirements are missing before build.
+---
+
+# ux-spec
+
+Write a **six-layer `spec.md`**: the functional **declaration** for what must be true. Visual skin, tokens, and Badge-vs-Tag choices are out of scope.
+
+## Steps
+
+### 1. Pin L1
+
+From the ask, fix the user-visible goal, target user, in-scope scenes, **non-goals**, and always/ask/never boundaries. Ask only when a missing answer materially changes one of them; otherwise record a conservative assumption.
+
+When `.scratch/<run>/reference/contract.md` exists (ADR-0011), **read it before writing L1–L6**. Fold its functional constraints, non-goals implied by Do not copy, and always/ask/never hints into L1 (and later L5/L6 edges). Cite the path; do not re-derive the screenshot from memory. The reference contract is input only — it does not replace any L1–L6 heading.
+
+**Done when:** all five L1 fields are explicit — goal, target user, in-scope scenes, non-goals, and always/ask/never boundaries — with each assumption labeled as such; none left blank or implied; and if a reference contract exists, its functional constraints are reflected (or an explicit rejected-with-reason note is recorded).
+
+### 2. Expand L2–L4
+
+- L2 regions and duties  
+- L3 states and transitions  
+- L4 control behavior per relevant state  
+
+Use the headings in [`references/spec-template.md`](references/spec-template.md).
+
+**Done when:** every primary user job has a state path; every region has an owner duty.
+
+### 3. Force L5–L6
+
+- L5: empty, loading, error, permission — each with what the user can do next  
+- L6: checkable acceptance; every top-level item explicitly contains `Given`, then `When`, then `Then`, with the proof required for that item
+
+Evidence is criterion-shaped: visible states require rendered inspection at named target viewports; behavior requires an interaction trace or automated check; implementation health uses the relevant tests, type/lint checks, or affected build when available. Planning-only work names the future proof instead of claiming it exists. Where the proof is a runtime state, name the **capture seed** — the state to capture (e.g. "error-state screenshot") and the capture type. This is the seed the `observe*` step derives a capture plan from (`Given`/`When` → state+actions, `Then` → required); do not write selectors, URLs, or actions here — those are derived later.
+
+**Done when:** L5 is not a single word (“loading”); every L6 item is a top-level list item that uses `Given -> When -> Then` in that order, can be ticked pass/fail without taste debate, and says what evidence will prove it (naming the capture seed where the proof is a runtime state).
+
+### 4. Emit
+
+Output the full `spec.md` using the template structure. Stop. Do not scaffold UI or pick components here.
+
+**Done when:** one markdown spec exists containing every L1–L6 heading from the template, with steps 1–3 Done-when criteria still holding in the emitted file, ready for the next pipeline step (`ui-picker` / fill).
+
+## Scope fence
+
+| In | Out → |
+| --- | --- |
+| Functional truth, flows, edges, acceptance | Color/type/motion → `design` / `craft-guard` |
+| | Risk/secrets meaning → `domain` |
+| | Component identity → `ui-picker` / `components` |

package/skills/ux-spec/references/spec-template.md

@@ -0,0 +1,43 @@
+<!-- spec-schema: 1 -->
+
+# [功能名] 交互设计 Spec
+
+## L1 定位与意图
+- 用户可见目标：
+- 目标用户：
+- 场景清单：
+- 非目标：
+- 行为边界：始终 / 询问后 / 永不
+
+## L2 信息架构
+- 空间区域定义：
+- 区域边界规则：
+- 内容生长规则：
+
+## L3 核心链路
+- 状态清单：
+- 主链路：
+- 分支链路：
+
+## L4 组件功能细节
+- 组件定位与功能清单
+- 默认 / 悬停 / 加载 / 禁用 / 错误 等状态
+- L4 declares control behavior only; reuse / no-internal-change constraints must name exceptions (for example, allow a minimal patch when they conflict with L5).
+
+## L5 边界条件
+- 空态：
+- 加载态：
+- 错误态：
+- 权限降级：
+
+## L6 验收标准
+- 每条验收是一个顶层列表项，按序显式包含 `Given` → `When` → `Then`（顺序固定），并写明该条的必备证据
+  - 必备证据：规划声明覆盖 / 目标视口渲染 / 交互记录或自动化检查 / 相关 test、type、lint、build（按任务适用项选择）
+  - 证据为运行时状态时，命名 capture seed（要捕获的状态 + 捕获类型，如 "error-state screenshot"）；不写 selector/URL/actions
+- 设计完成定义：
+
+---
+
+## Worked snippet (illustrative)
+
+For an agent-ops list: a failed item must show cause + retry (L3/L4); no-data shows a non-blank empty state (L5); without permission the dangerous action is disabled with a reason (L5); acceptance ticks each of these (L6). Adapt to the actual product; this is not a fixed domain.