@xulthekl/team-flow 0.53.0 → 0.55.0

package/skills/design-system/references/agents/design-system-architect.md

@@ -1,13 +1,11 @@
-**Note: The current year is 2026.** Use this when assessing recency.
-
-You are a Design System Architect. You are dispatched by the `design-system` skill to **create or iterate** the project-level `.team-flow/design-system/base.md` — the single source of truth for design tokens, components, and anti-patterns (compounded back via prototype-sync). The orchestrating design-system skill **never writes `base.md` itself — you are the sole writer**. You run in two phases: first produce a **draft** (`confirmed: false`) for orchestrator review + human confirmation; then, re-dispatched with `confirmed: true`, **you yourself write the official path**. The orchestrator only reviews, confirms, and re-dispatches — it does not Write/Edit `base.md`.
+You are a Design System Architect. You are dispatched by the `design-system` skill to **create or iterate** the project-level `.team-flow/design-system/base.md` — the single source of truth for design tokens, components, and anti-patterns (compounded back via prototype-sync). The orchestrating design-system skill **never writes `base.md` itself — you are the sole writer**（v0.55.0 起写者范围另含**端变体的 `layout` 段**）。 You run in two phases: first produce a **draft** (`confirmed: false`) for orchestrator review + human confirmation; then, re-dispatched with `confirmed: true`, **you yourself write the official path**. The orchestrator only reviews, confirms, and re-dispatches — it does not Write/Edit `base.md`.
 
 ### 文件结构：base + variant
 
 architect 写入的文件采用 **base + variant** 结构：
 - **`.team-flow/design-system/base.md`**：基础设计系统（全量 token + 组件规范 + anti-patterns），是所有 variant 的公共底座。
 - **`.team-flow/design-system/variants/<name>.md`**（可选）：品牌/主题变体文件，只覆写差异 token（如暗色主题、子品牌色板），继承 base 未覆写部分。
-- architect 在 `confirmed: true` 阶段写入 base.md；如需 variant，同时写入对应 variant 文件。
+- architect 在 `confirmed: true` 阶段写入 base.md；如需 variant，同时写入对应 variant 文件。**v0.55.0 起另含端变体（`b-end.md` / `c-end.md`）的 `layout` 段**（页面范式声明 + 容器骨架块，见下方「端变体 `layout` 段写者」）。
 
 The plugin stays **generic**: do NOT hardcode any specific company/product brand. Derive tokens deterministically from the project's stated tone/brand input; when none is given, fall back to a neutral default and record the assumption.
 
@@ -17,7 +15,7 @@ The dispatch prompt provides:
 - `mode: create | iterate`.
 - `confirmed: false | true`（v0.15.0 两阶段落盘）：
   - `false`（默认，草案阶段）：只产草案（写 scratch 草稿路径或返回 response），**不写正式 `.team-flow/design-system/base.md`**。
-  - `true`（人工已确认）：把已确认的草案**写入正式 `.team-flow/design-system/base.md`**（你是唯一写者）。
+  - `true`（人工已确认）：把已确认的草案**写入正式 `.team-flow/design-system/base.md`**（你是唯一写者）；若本次产出 / 更新端变体的 `layout` 段（页面范式声明 + 容器骨架块），同批写入。
 - `design_system_path`: 正式目标路径（`confirmed: true` 时写入此处，默认 `.team-flow/design-system/base.md`）。
 - `draft`（`confirmed: true` 时传入）：上一阶段已确认的草案内容/路径。
 - `create` inputs (as available): project tone/brand hints, PRD path (to read product domain & voice), existing scaffold `.team-flow/design-system/base.md`.
@@ -33,15 +31,50 @@ Every `.team-flow/design-system/base.md` follows this schema (9 sections + a 5-d
 | `typography` | font-family / scale（1.25 比例）/ line-height |
 | `spacing` | 4 / 8 / 12 / 16 / 24 阶梯（基于 4 基数） |
 | `layout` | 栅格 12 列 / 断点 sm/md/lg / 容器 max-width |
-| `components` | button / input / card / table 规范（见 components/） |
+| `components` | **组件契约表（v0.54.0，全量真源）**：`\| 组件 \| 类型 \| variants \| sizes \| states \| 用途 \| 禁止 \|`；类型 ∈ 交互/轻量/豁免；**≥10 类起步**（20 类完整基线见下方组件清单） |
 | `motion` | duration 150–300ms / easing standard |
 | `voice` | 文案语气（专业、简洁） |
 | `brand` | logo / 品牌主色 |
 | `anti-patterns` | 禁止内联样式漂移 / 禁止非 token 颜色 |
+| `principles`（v0.54.0） | **设计原则 ≥3 条**（随 mood 预填，用户可调整） |
+| `governance`（v0.54.0） | `contract: v1`（**新建默认 v1；来源 ∈ {`create-from-docs` / `create-from-code` / 转换器产物 / 旧文件迁移} 时写 `legacy`**，v0.55.0 设计 §8.2.1 D-18；存量升级时由 iterate 置 v1）+ version + 负责人 + 弃用策略 + changelog |
+| `来源与裁决记录`（v0.55.0） | **导入类创建条件必填**（同上四类来源）：原始来源 / 导入方式 / 「为什么不是直接采纳」/ 主色裁决 / 待清理项——审计层 advisory，不进 `REQUIRED_SECTIONS` |
 | `palette`（5 方向确定性调色板） | neutral / primary / success / warning / danger，各含 50–900 阶梯 |
 | `aliases`（B-slot 别名层，v0.18.0） | `--fg-2 → var(--fg)` / `--meta → var(--muted)` / `--border-soft → var(--border)` / `--surface-warm → var(--surface)`——组件引用 B-slot 永远可解析 |
 | `extensions`（C-extension 待提升清单，v0.18.0） | 品牌专有 token 名单制；提升路径：C→B（≥2 品牌需要）→A2（有全局默认值） |
 
+> **文档头部还需一行 a11y 声明（v0.54.0）**：`> a11y: WCAG 2.2 AA（对比度 4.5:1 / 大字 3:1 / 焦点可见 / 键盘可达）`——从 prototype craft 层提级（guard L0-可访问性依据）。
+
+### 组件契约表：20 类完整基线（v0.54.0）
+
+新建设计系统时**至少产出 10 类**（guard 三档：<10 FAIL 标签 / 10-14 WARN 可用 / ≥15 PASS）。完整基线与分组（类型列决定 guard 的 states 下限）：
+
+| 组件 | 类型 | variants | sizes | states |
+|------|------|----------|-------|--------|
+| Button | 交互 | primary / secondary / ghost / danger | sm / md / lg | default / hover / focus-visible / active / disabled / loading |
+| Input | 交互 | default / error / success | sm / md / lg | default / focus / disabled / readonly / error / filled |
+| Select | 交互 | default / multiple / searchable | sm / md / lg | default / focus / disabled / error / open |
+| Checkbox | 交互 | default / indeterminate | sm / md | default / hover / focus / disabled / checked |
+| Radio | 交互 | default | sm / md | default / focus / disabled / selected |
+| Switch | 交互 | default | md | default / focus / disabled / on / off |
+| Tag | 轻量 | default / success / warning / danger / info | sm / md | default / hover / closable¹ |
+| Icon | 豁免 | — | sm / md / lg | — |
+| Avatar | 轻量 | circle / square | sm / md / lg | default / fallback / loading |
+| Tooltip | 轻量 | default | — | hidden / visible |
+| Modal | 交互 | default / confirm / destructive | sm / md / lg | open / loading / error / closing |
+| Drawer | 交互 | left / right / bottom | sm / md / lg | open / loading / error |
+| Tabs | 交互 | line / pill | — | default / active / disabled / loading |
+| Table | 交互 | default / compact / striped | — | default / loading / empty / error / selected |
+| Form | 交互 | single / two-column | — | untouched / dirty / submitted-pending / error |
+| Card | 交互 | default / interactive / stat | — | default / hover / selected / loading |
+| Pagination | 交互 | default / simple | sm / md | default / disabled / loading |
+| FilterBar | 交互 | default / collapsible | — | default / expanded / applied |
+| EmptyState | 豁免 | default / filtered / error | — | — |
+| Toast | 交互 | success / warning / error / info | — | entering / visible / exiting |
+
+> **¹ 行为项标记**：`closable` 是行为非状态（Tag 可同时处于 default + hover + closable）——后缀 `¹` 告知 guard 不计入 states 下限。值项（on/off、selected、checked）同理按值处理，但**不加 ¹**（它们计入但由与值正交的状态满足下限）。
+> **豁免组件**（Icon/EmptyState）不检查 states 与 variants。
+
 ### Token 四层模型（v0.18.0，参照 open-design token-schema）
 
 | 层 | 语义 | 完整性 |
@@ -51,7 +84,7 @@ Every `.team-flow/design-system/base.md` follows this schema (9 sections + a 5-d
 | **A2-derived** | 必选但有默认公式：`--accent-hover: color-mix(in oklab, var(--accent), black 8%)` / `--accent-active: ... black 14%` / `--focus-ring: ... accent transparent 70%` / `--elev-raised: ... fg transparent 92%` / `--success` `--warn` `--danger` / `--font-mono` / `--space-1~12` / `--radius-sm/md/lg/pill` / `--motion-fast/base` / `--ease-standard`（21 项） | 缺 = guard 失败 |
 | **B-slot** | 可选别名层：`--fg-2 → var(--fg)` / `--meta → var(--muted)` / `--border-soft → var(--border)` / `--surface-warm → var(--surface)`（4 项） | 组件引用永远可解析 |
 
-> **完整性约束**：每份 design-tokens.css 必须声明全部 A1+A2+B-slot token——agent 把单份 `:root` 块粘进单个 `<style>`，无全局级联，缺一个 token 规则悄悄失效。可运行 `node scripts/guard/design-token-guard.mjs` 校验。
+> **完整性约束**：每份 design-tokens.css 必须声明全部 A1+A2+B-slot token——agent 把单份 `:root` 块粘进单个 `<style>`，无全局级联，缺一个 token 规则悄悄失效。可运行 `node ${CLAUDE_PLUGIN_ROOT}/scripts/guard/design-token-guard.mjs` 校验。
 
 ## Methodology
 
@@ -65,11 +98,15 @@ When the project has no `.team-flow/design-system/base.md`:
    - **A2 派生状态色**（v0.18.0）：用 `color-mix(in oklab, ...)` 公式派生 accent-hover(black 8%) / accent-active(black 14%) / focus-ring(accent 30%) / elev-raised(fg 8%)。不手写固定 hex。
    - **B-slot 别名层**（v0.18.0）：`--fg-2 → var(--fg)` / `--meta → var(--muted)` / `--border-soft → var(--border)` / `--surface-warm → var(--surface)`。
    - **C-extension 清单**（v0.18.0）：如有品牌专有 token，列入 `extensions` 段（名单制），标注提升路径。
+   - **组件契约表（v0.54.0）**：按上方 20 类基线产出**至少 10 类**（`| 组件 | 类型 | variants | sizes | states | 用途 | 禁止 |`），全部 token-bound；类型列必须填写（交互/轻量/豁免）。
+   - **principles 段（v0.54.0）**：≥3 条，随 mood 预填（如 professional_minimal → "一致性优先于局部创意 / 清晰优于装饰 / 可访问性默认开启"）。
+   - **governance 段（v0.54.0；v0.55.0 改）**：`contract: v1`（**新建默认 v1**；**来源 ∈ {`create-from-docs`, `create-from-code`, 转换器产物, 旧文件迁移}（导入类）时写 `legacy`**——导入的既有资产未经校准，恒打 `v1` 会一落盘即 blocked）+ version + 负责人 + 弃用策略 + changelog。
+   - **`来源与裁决记录` 段（v0.55.0）**：来源属上列导入类时**条件必填**（原始来源 / 导入方式 / 「为什么不是直接采纳」/ 主色裁决 / 待清理项）；绿地创建可选，**不进 `REQUIRED_SECTIONS`**。
+   - **a11y 声明行（v0.54.0）**：文档头部 `> a11y: WCAG 2.2 AA（对比度 4.5:1 / 大字 3:1 / 焦点可见 / 键盘可达）`。
    - Fill color / typography / spacing / layout / motion / voice / brand / anti-patterns consistently with the palette.
-   - `components` references the reusable components the prototype will need (button/input/card/table at minimum), all token-bound.
    - `anti-patterns` MUST include "禁止内联样式漂移" and "禁止非 token 颜色".
 3. **`confirmed: false`**：Deliver the draft（写 scratch 草稿路径或返回 response），**不写正式路径**。Orchestrator 评审 + 人工确认后，**带 `confirmed: true` 重新派发你**，由你写入正式 `.team-flow/design-system/base.md`（主代理不写）。
-4. **`confirmed: true`**：把传入的已确认草案 `Write` 到正式 `.team-flow/design-system/base.md`，然后执行 **预览生成步骤**，返回 `status: done` + deliverable = 正式路径。
+4. **`confirmed: true`**：把传入的已确认草案 `Write` 到正式 `.team-flow/design-system/base.md`；若本次产出端变体（`b-end.md` / `c-end.md`），同批写入其 **`layout` 段**（页面范式声明 + 容器骨架块，见下方「端变体 `layout` 段写者」），然后执行 **预览生成步骤**，返回 `status: done` + deliverable = 正式路径。
 
 #### 预览生成步骤（confirmed: true 后自动执行）
 
@@ -81,14 +118,27 @@ When the project has no `.team-flow/design-system/base.md`:
 
 ### Mode: iterate（增量更新）
 
-When prototype-sync (or a change) introduces new components / tokens / anti-patterns:
+When prototype-sync (or a change) introduces new components / tokens / anti-patterns / **page-pattern specs（页面规范增量，v0.55.0）**:
 
 1. Read the existing `.team-flow/design-system/base.md`.
-2. **Merge** (not overwrite) the incoming increments: new components into `components`, new tokens into the relevant section + palette, new anti-patterns into `anti-patterns`.
-3. Keep token consistency — a new component must reference existing tokens; if it needs a new token, add the token to the palette/section too (no orphan tokens).
-4. Append a **变更履历** entry: 时间 / 变更内容 / 来源 change-id.
-5. **`confirmed: false`**：Deliver the merged draft（草稿路径或 response）for orchestrator review + human confirmation，**不写正式路径**。
-6. **`confirmed: true`**：把已确认的合并草案 `Write` 到正式 `.team-flow/design-system/base.md`（你是唯一写者），然后执行**预览生成步骤**（同上）。
+2. **Merge** (not overwrite) the incoming increments: new components into the `components` 契约表（必须指定类型列）, new tokens into the relevant section + palette, new anti-patterns into `anti-patterns`.
+   - **contract 升级（v0.54.0）**：若原系统为 `legacy`/无标记，且本次补全了契约表（≥10 类）→ 将 `contract` 置为 `v1`（并记 changelog：来源"本 change 增量回流"）。
+   - 变体文件的 components 段只写**端特有差异**并引用契约表（不重复定义组件清单）。
+3. **页面规范增量（v0.55.0 第四类增量）**：用户提供项目页面规范，或要更新既有 `页面范式来源` 声明 / 页面类型表时 → 写对应端变体的 `layout` 段（`### 容器骨架` 块 + `### 页面范式` 子块）。**用户不提供规范时默认补写 `页面范式来源：引用内置` 一行**，使 guard L3 的 ⚠️ 收敛为 ✅（绿地默认；已知属导入类棕地时改按 `项目自有` + 容器骨架块写——见 `variant-schema.md` 三态语义）。
+4. Keep token consistency — a new component must reference existing tokens; if it needs a new token, add the token to the palette/section too (no orphan tokens).
+5. Append a **变更履历** entry: 时间 / 变更内容 / 来源 change-id.
+6. **`confirmed: false`**：Deliver the merged draft（草稿路径或 response）for orchestrator review + human confirmation，**不写正式路径**。
+7. **`confirmed: true`**：把已确认的合并草案 `Write` 到正式 `.team-flow/design-system/base.md`（你是唯一写者）；若本次含页面规范增量，同批 `Write`/`Edit` 对应端变体的 `layout` 段，然后执行**预览生成步骤**（同上）。
+
+#### 端变体 `layout` 段写者（v0.55.0 扩面，设计 §8.2.2）
+
+**写者范围由「只写 `base.md`」扩为「`base.md` + 端变体的 `layout` 段」**——页面范式属端变体，而 architect 此前只写 base，导致该声明**无写者**、guard 的 ⚠️ 无从收敛。
+
+- **可写**：端变体（`b-end.md` / `c-end.md`）的 `layout` 段：
+  - `### 容器骨架` 块——表格 `| 容器 | 类名 | 关键 CSS 声明 |`（builder 的物料来源）
+  - `### 页面范式` 子块——`**页面范式来源**：…` 声明 + 页面类型表
+- **边界**：本次扩面**只涉及 `layout` 段**，其余段落维持既有分工，不借机扩张写面；`variants/<name>.md`（暗色等主题变体）不属本扩面。
+- **取值**（三态语义见 `variant-schema.md`）：`项目自有`（棕地导入，须附容器骨架块 + 页面类型表 ≥3 行）/ `同 <端>`（指向另一端）/ `引用内置`（绿地默认，只写声明）。
 
 ## Output Format
 
@@ -98,7 +148,7 @@ When prototype-sync (or a change) introduces new components / tokens / anti-patt
 ### Mode: {create | iterate}
 ### Target path: {.team-flow/design-system/base.md}
 
-### design-system.md (draft content)
+### base.md (draft content)
 {完整 9 段 schema + palette + aliases + extensions 的 markdown 内容，含 A2 派生色公式和 B-slot 别名层，可直接落盘}
 
 ### 变更履历 (iterate only)
@@ -113,7 +163,7 @@ When prototype-sync (or a change) introduces new components / tokens / anti-patt
 ## Tool Guidance
 
 - Use `Read` for the existing base.md / PRD / scaffold; `Glob` to scan existing `components/` and `variants/`.
-- **`Write` 权限按 `confirmed` 阶段使用**：`confirmed: false` → 只写 scratch 草稿路径（或仅返回 response），**绝不写正式 `.team-flow/design-system/base.md`**；`confirmed: true` → 写正式路径 + 生成 preview.html（你是唯一写者，主代理不写）。
+- **`Write` 权限按 `confirmed` 阶段使用**：`confirmed: false` → 只写 scratch 草稿路径（或仅返回 response），**绝不写正式 `.team-flow/design-system/base.md`**；`confirmed: true` → 写正式路径（含端变体 `layout` 段）+ 生成 preview.html（你是唯一写者，主代理不写）。
 - Keep everything token-based and offline-friendly (产物必须零外部依赖).
 
 ## Red Lines

package/skills/design-system/references/creation-flow.md

@@ -46,7 +46,7 @@
 |----|---------------------|------|---------|--------|
 | `compact` | 12px | 1.4 | 14px | technical_dense |
 | `balanced` | 16px | 1.5 | 16px | professional_minimal（**全局默认**） |
-| `spacious` | 20px | 1.65 | 17px | warm_approachable / editorial |
+| `spacious` | 20px | 1.65 | 18px | warm_approachable / editorial |
 
 ### 维度 5：目标端（target）— 决定产出几个变体文件
 
@@ -56,10 +56,20 @@
 | `c_end` | base.md + c-end.md |
 | `both` | base.md + b-end.md + c-end.md（**默认**，覆盖最广） |
 
+### 维度 6：主题（theme）— 决定是否派生暗色变体（v0.54.0 新增）
+
+| 值 | 产出 |
+|----|------|
+| `light` | 仅亮色（**默认**） |
+| `dark` | 仅暗色 |
+| `both` | 亮色 + `variants/dark.md`（确定性派生规则见 `token-derivation.md`） |
+
 ---
 
 ## Step 2: 确定性 Token 派生
 
+> **数值权威**：本文件的全部具体数值（色值 / 间距 / 字阶 / 字体栈）以 `token-derivation.md` 为唯一真相源，两处必须一致；发现分歧以该文件为准。
+
 ### Mood → 调色板映射表（确定性，同 mood 同色）
 
 | mood | accent（品牌主色 `--accent`） | neutral 锚点（ink `--fg` 基调） |
@@ -82,8 +92,8 @@
 ```
 --accent-hover:  color-mix(in oklab, var(--accent), black 8%)
 --accent-active: color-mix(in oklab, var(--accent), black 14%)
---focus-ring:    color-mix(in oklab, var(--accent), transparent 70%)
---elev-raised:   color-mix(in oklab, var(--fg), transparent 92%)
+--focus-ring:    0 0 0 3px color-mix(in oklab, var(--accent), transparent 70%)
+--elev-raised:   0 2px 8px color-mix(in oklab, var(--fg), transparent 92%)
 ```
 另含 `--success` `--warn` `--danger` `--font-mono` `--space-1~12` `--radius-sm/md/lg/pill`
 `--motion-fast/base` `--ease-standard`。
@@ -94,16 +104,56 @@
 ---
 
 ## Step 3-4: 草稿 + 预览
-- 按 target 生成 base.md + 变体（schema 见 `variant-schema.md`）。
+- 按 target 生成 base.md + 变体（schema 见 `variant-schema.md`），**含 v0.54.0 新增段**：
+  - `components` 组件契约表（≥10 类起步，含类型列）
+  - `principles`（≥3 条）+ `governance`（`contract: v1`）
+  - 头部 a11y 声明行（WCAG 2.2 AA）
+- **端变体 `layout` 段默认写 `页面范式来源：引用内置`（v0.55.0，设计 §8.2.2）**——生成端变体（`b-end.md` / `c-end.md`）时就要写，**不写则从零创建的产物两端一出生就落 ⚠️**（guard L3 声明层缺失，只能等 iterate 补）。绿地默认只写这一行；容器骨架块**可省**——内置 `template.html` 的类全是通用/营销向（`hero` / `topnav` / `pagefoot`），**C 端够用**；但 **target 为 B 端（`b_end` / `both`）时建议一并给**（内置骨架**无** `app-header` / `app-sider` / `app-main` 这类容器类，不给则 builder 每页手写整套后台骨架 CSS，单次派发无法复现）。取值三态见 `variant-schema.md`，缘由详见 `creation-modes.md` §5。
 - 用 `preview-template.html` 填 token 值 → 自包含 `preview.html`（色板/排版/间距/组件/明暗切换）。
 
+## Step 4.5: Design Showcase 草案（v0.54.0 新增，设计 §4.1.7）
+
+> **可选环节**：Step 5 呈现前询问用户是否需要（**产出前明示预估耗时**，S5 实测校准后回填）；不需要则跳过。
+
+**0) 询问前先做原型探测（v0.55.0，设计 §8.2.3 / FB-2a）**：
+
+- **探测面**：`prototype/` ∨ config `prototype.entry` 所在目录 ∨ `prototype.versionWorktree`（worktree 内原型）∨ repo_layout 各仓的 `prototype/`——**须覆盖 worktree 与多仓**，否则探测不到 → 提示不出现 → 用户被引导重画已有原型（正是本节要修的形态）。
+- **判据**：探测到 **≥1 个 HTML 页面文件**即提示（**不设行数阈值**——机制不替用户判断"够不够成熟"，由用户在知情下决定）。
+- **呈现**（`AskUserQuestion`）：
+
+  > 「检测到项目已有原型产物（`prototype/`：N 个页面 / M 行）。showcase 的目的是在设计系统落盘前预览效果，已有真实原型时可能重复。」
+
+  | 选项 | 后续动作 |
+  |------|---------|
+  | **跳过 showcase**（推荐） | Step 5 呈现时**改引用真实原型路径**（不产 showcase 草案） |
+  | 仍然产出 | 走下方原流程（brief 场景可调） |
+  | 调整场景 | 用户给出场景描述后产出 |
+
+  > **为什么**：showcase 的定位是"设计系统落盘**前**预览效果"；已有真实原型时它是**重复劳动**——不提示就是让用户白画一遍。
+
+1. architect 产出 **primer 草案**（scratch 路径 `/tmp/ds-draft-<slug>/primer-draft.md`，digest 记录**草案 base** 的哈希）
+2. 主代理派 `prototype-builder`（`mode: showcase`，单次派发）：
+   - 输入：showcase-board brief（按 target：`b_end` → b-end brief；`c_end` → c-end brief；`both` → 两个）+ 设计系统草案 + primer 草案
+   - 产出：`/tmp/ds-draft-<slug>/showcase/*.html`（b-end.html / c-end-website.html / c-end-app.html）
+3. **重画上界**：≤2 次（用户不满调整 token 后重画）；超过 2 次强制二选一（按现状确认 / 跳过 showcase）
+4. **digest 锚定**：每个 Board 头部记录 primer 草案 digest；Step 6 复制前比对（不一致 → 标"已过期"并提示重生成）
+
 ## Step 5: 用户评审 + 确认
 呈现三件套：① token 摘要表 ② preview.html 路径 ③ **默认值透明报告**。
 AskUserQuestion 三选项：**确认落盘 / 调整某项（回到 Step 1 对应维度）/ 重新来（清空重来）**。
 
 ## Step 6: 落盘 + guard
 两阶段写入由子代理执行（confirmed:false 草案 → 人工确认 → confirmed:true 写正式路径）。
-落盘后运行 `node scripts/guard/design-token-guard.mjs`，校验 A1+A2+B-slot 完整性。
+
+**新增落盘动作（v0.54.0）**：
+- **primer**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/gen-primer.mjs <base.md 路径>` → 生成正式 `.team-flow/design-system/primer.md`（含 digest）
+- **showcase 搬运**：design-system skill 从 scratch **复制**到 `.team-flow/design-system/showcase/`（**放弃确认**——用户选"重新来"→ 整体丢弃 scratch，不写任何正式路径）
+
+落盘后运行 `node ${CLAUDE_PLUGIN_ROOT}/scripts/guard/design-token-guard.mjs <设计系统目录 | design-system.md> [design-tokens.css]`
+> **target=both 时按端各跑一次**：`--variant b-end` 与 `--variant c-end` 各跑一遍——合并断言只保证「两端合起来覆盖 9 段」，**单端残缺会被合并掩盖**（P4 复验实证：c-end 缺 spacing/layout/motion 时合并跑仍 PASS，`--variant c-end` 跑报 3 项 FAIL）（v0.54.0；传目录/blob 时自动合并 base + 端变体）：
+- **硬校验**（失败 exit 1）：9 段 / palette / A1 / A2 公式 / B-slot——原有检查，不通过即返工
+- **六层审计报告**（advisory，恒 exit 0）：L0 原则治理 / L0 可访问性 / L1 Token / L1 双主题 / L2 组件契约 / L3 业务模式 / L4 页面范式 / L5 Primer——分层标签供参考，WARN 不阻断
+- `--strict`：存量系统按新体系标签输出（自查用）；`--json`：结构化输出
 
 ---
 
@@ -116,6 +166,7 @@ AskUserQuestion 三选项：**确认落盘 / 调整某项（回到 Step 1 对应
 | display_font 未给 | `sans_display` | 系统栈零依赖，跨端最稳 |
 | density 未给 | `balanced` | 16px 基准，适配多数信息场景 |
 | target 未给 | `both` | 一次产出双端，避免后续补做 |
+| theme 未给 | `light` | 暗色为可选派生产物，默认不产出以控制复杂度（可随时 iterate 补） |
 | mood 与某维度冲突（如 technical_dense + spacious） | 保留用户显式选择，仅在透明报告标注「非常规组合」 | 用户显式输入优先于推荐 |
 
 **优先级**：用户显式输入 > mood 联动推荐 > 全局默认。冲突时不静默改写，标注后由 Step 5 确认。

package/skills/design-system/references/creation-modes.md

@@ -0,0 +1,171 @@
+# 创建模式详解（v0.55.0）
+
+> 本文是 `SKILL.md` Step 0 的**展开说明**。Step 0 按「资产就绪度降序」列出 7 条起点，
+> 其中 6 条的完整流程在此（**iterate** 见 `creation-flow.md`；**从零创建**即 Step 1 起的交互 6 步）：
+> §1 移植 clone · §2 模板库 · §3 通用起点 `--profile antd` · §4 文档导入 create-from-docs ·
+> §5 B 端容器骨架为何必须给（贯穿 §1/§3） · §6 代码逆向 create-from-code。
+
+---
+
+## 1. 移植模式（clone）
+
+**场景**：**同类后台项目之间复用设计系统**——"以后其他项目是相同的后台"。
+
+**入口**：`/team-flow:design-system clone --from <源项目路径 | 源设计系统目录> --to <目标设计系统目录>`
+
+设计系统就是 `.team-flow/design-system/` 下的 markdown，技术上 `cp -r` 即可——但**直接复制会留 4 个坑**，
+`clone` 把它们自动化：
+
+| # | 坑 | 处置 |
+|---|-----|------|
+| 1 | **`来源与裁决记录` 失真**（复制后仍写着原项目的导入记录，而目标并未导入过） | **追加**移植记录，**保留**原裁决历史——其裁决依据对理解本系统取值仍有参考价值 |
+| 2 | **`primer.md` digest 失效**（锚定源 base 内容；改一字即 STALE，而 prototype Step 0 对 `contract: v1` 系统 **blocked**） | 强制重生成 + `--check` 校验 |
+| 3 | **业务专属组件残留**（如"协议富文本编辑器 / 内容预览画布"） | 输出契约表全量清单 → **逐条问询** |
+| 4 | **授权边界**（源 `references/` 下可能是企业内部资产） | 提示（不自动判定） |
+
+**脚本自动完成（确定性）**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/design-system-clone.mjs --from <源> --to <目标>`
+1. 校验源系统（跑 guard；不合规**只警告不阻断**——源可能是 legacy）
+2. 复制（**排除** `primer.md` / `pending.md` / `showcase/`）
+3. 追加移植记录
+4. 输出契约表清单（供第 5 步问询）
+5. 重生成 primer + `--check`
+6. 对结果跑 guard 并输出六层审计
+
+**需 LLM 承接（脚本不做的交互部分）**：
+- **业务组件逐条问询**：读第 4 步清单 → `AskUserQuestion` 逐条确认 → 删除不再需要的
+  → **提示用户**：组件数跌破档位会改变 L2 标签（<10 FAIL / 10-14 WARN / ≥15 PASS）
+- **品牌适配**：主色/字体不同 → 改 `base.md` 的 `color` 段 → **必须重跑 `gen-primer`**
+- **`contract` 取值**：移植产物继承源系统；若源为 `v1` 而目标尚未达标，可考虑降为 `legacy`
+- **页面范式来源复核（v0.55.0）**：`### 页面范式` 是**原样带过来**的，但目标项目的页面现实可能不同——
+  **判据 = 目标项目是否已有成文的页面规范或既有原型页面类型**：
+  源 `引用内置` 而目标是**棕地** → **改为 `项目自有`** + 补容器骨架块 + 页面类型表（否则目标既有的
+  页面规范进不了 builder，本次移植等于只搬了一半）；源 `项目自有` 而目标是**绿地**（无既有页面规范）
+  → 可改 `引用内置`（否则 builder 会按源项目的页面类型硬套，与目标实际页面不符）。改后**必须重跑 `gen-primer`**。
+
+**与 iterate 的分界**：clone 是**新建**（目标无设计系统）；目标**已有**设计系统 → 走 iterate（MERGE 不 OVERWRITE）。
+
+---
+
+## 2. 模板库导入
+
+**场景**：想参考某个成熟产品的视觉风格（Linear / Stripe / Vercel / Supabase / Sentry / PostHog / Notion / Claude）。
+
+**流程**：展示 `${CLAUDE_PLUGIN_ROOT}/templates/design-systems/registry.json` → 用户选定 →
+`node ${CLAUDE_PLUGIN_ROOT}/scripts/design-system-import.mjs <reference.md> --out .team-flow/design-system/base.md`
+→ **续跑 Step 5 评审 → Step 6 落盘**（落盘含 primer 生成 + guard 校验）。
+
+> **B 类参考**（如 linear-app）为**自动提取配色**，转换器会输出警告 → **须提示用户人工核对**。
+>
+> **风格种子**（`styles.json`，57 个）：Step 1 需求收集时作为 mood / 品牌主色的参考依据。
+
+---
+
+## 3. 通用起点（`--profile antd`）
+
+**场景**：全新项目、**没有任何规范**，先要一套合规的 token 底座。
+
+**入口**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/design-system-import.mjs --profile antd --out .team-flow/design-system/base.md`
+→ 续跑 Step 5 → Step 6。
+
+**产出规格**（全部来自 Ant Design v5 seed token（MIT）或 team-flow 自有规范）：
+
+| 规格 | 值 |
+|------|-----|
+| 控件高 | 32px（`controlHeight`） |
+| 圆角阶梯 | 2 / 4 / 6 / 8（`borderRadius`，v5 默认 6） |
+| 字号阶梯 | 12 / 14 / 16 / 20 / 24（`fontSize`） |
+| 间距 | 8 档 4→48px（**team-flow 自定**，参考 AntD size 阶梯） |
+| 组件契约表 | 20 类通用基线（team-flow 自有） |
+
+**零 LLM、零外部资产、零授权链风险**。
+
+> **定位**：它是**薄起点**——不含**业务**组件（20 类为通用基线，不针对任何业务）、
+> 不含**项目自有**页面范式（`### 页面范式` 声明 `引用内置`，页面类型表只是内置节奏的示意）。
+>
+> **但它含一份通用 B 端容器骨架块**（`app-header` / `app-sider` / `app-main`）。这不是矛盾：
+> 内置 `template.html` 的 15 个类全是**营销向**的（`hero` / `topnav` / `pagefoot` / `cta`），
+> **没有任何 B 端容器类**——不给物料，builder 就得每页手写整套后台骨架 CSS，
+> 单次派发无法复现（详见 §5「B 端容器骨架为何必须给」）。
+>
+> 要复用**厚资产**（如某项目已建好的 30+ 类契约 + 页面规范）请用**移植模式**。
+
+---
+
+## 4. 文档导入模式（create-from-docs）
+
+**场景**：手里有**既有的 Markdown 规范树**（非代码、非模板库形态）——如企业的三层规范
+（基础元素层 / 页面模板层 / 模式规范层）。
+
+**流程（5 步）**：
+
+1. **提取**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/token-extract.mjs <规范树目录> --docs`
+   → `.team-flow/token-extract/source-docs.json` + 报告（**零 LLM**）
+2. **呈现报告（含冲突项）**：报告器只呈现**证据与冲突**，**不做取值裁决**——
+   同一 token 名多值时显式并列（如 `--color-primary`：`#1890ff`×20 / `#3A94DD`×3），
+   标注"跨期/跨源矛盾，需人工裁决"
+3. **人工裁决**（多轮 `AskUserQuestion`）：**语义角色由人定，不由 LLM 定**
+4. **落盘**：base + 变体（含 `layout` 段的「容器骨架」块 + `页面范式来源：项目自有`）
+   + **`来源与裁决记录` 段（强制）**
+5. guard 校验
+
+**为什么报告器不做裁决**：真实规范树的 token 主形态是 **Markdown 表格行**，且列序不固定
+（实测 3 种，含交错列）；按频次排序会选出**错的主色**（现场实测：错值 `#1890ff` ×157
+vs 正确值 `#3A94DD` ×62——两期各自自洽、互未发现）。工具的职责是**把矛盾摊开**，不是选一个。
+
+**授权约束**：导入的既有资产**只留在项目内**，**不打包**进插件分发包。
+
+---
+
+## 5. B 端容器骨架为何必须给（v0.55.0）
+
+**事实**：内置 `template.html` 的全部 15 个类是
+`brand / btn / btn-primary / btn-secondary / container / eyebrow / hero / hero-center /
+hero-cta / lead / meta / pagefoot / row-between / section / topnav`——
+**清一色营销向**，没有 `app-header` / `app-sider` / `app-main` 这类后台容器类。
+
+**后果（不写骨架块时）**：builder 每页都要**从零手写**整套后台骨架 CSS（顶栏 sticky + 侧栏固定宽 +
+主区弹性），而它是**单次派发**的子代理——没有跨页记忆、无法从既有页面"抄"，同一项目不同页面
+会漂移出不同的骨架实现。
+
+**所以**：`--profile antd`（通用起点）与导入类模式**都附一份骨架块**（类名 + 关键 CSS 声明）。
+这不是"厚资产"，是**最小可复现物料**——与"薄起点"定位不冲突。
+
+**契约不变**：骨架类**不在** `layouts.md` 的类清单表内，按该表**同一条硬规则**处理——
+**先在页面 `<style>` 里定义，再使用**；绝不允许凭空发明没有 CSS 支撑的全局类。
+物料来源是 primer 的「容器骨架」块（`gen-primer` 逐端摘录原文）。
+
+> **三态下的骨架块**（与 `variant-schema.md` 的 `layout` 段三态表一致）：
+> `引用内置` → **可省**（C 端/营销页内置骨架够用），但 **B 端建议给**；
+> `项目自有` → **必须给**（这是棕地项目页面规范能进 builder 的唯一通道）；
+> `同 <端>` → 由被指向端保证，本端免写。
+
+---
+
+## 6. 逆向建库模式（create-from-code）
+
+**场景**：企业已有**符合规范的原型代码** → 基于它建立设计系统。
+
+**定位**：**确定性提取 + 人工策展**。不做自动语义推断——那会产出"垃圾设计系统 + 满分审计"
+（guard 只校验**结构**合规，不校验**语义**正确）。
+
+**入口**：`/team-flow:design-system create-from-code <代码目录>`
+
+> ⚠️ **单目录**：`token-extract.mjs` 的位置参数只接受一个源路径，传多个会**显式报错 exit 1**
+> （v0.55.0 修正：原实现静默丢弃其余路径，多仓场景下用户以为处理了全部）。
+> 多仓请**分批调用**，或先合并到一个目录。
+
+**流程（5 步）**：
+
+1. **提取**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/token-extract.mjs <目录>`
+   → `.team-flow/token-extract/source-tokens.json` + 统计报告（频次 + 位置证据，**零 LLM**）
+2. **呈现报告**：向用户展示提取统计（"47 个文件、23 个颜色、8 个间距值，高频 Top10 …"）
+3. **候选稿**：从高频值生成候选 token 表（**标注"候选"**）
+4. **人工策展**（多轮 `AskUserQuestion`）：用户指定 primary / 中性色 / 语义色 / 字体栈
+   （每项有频次+位置证据可参考）→ skill 按确定性规则补齐 A1/A2/B-slot + palette 阶梯
+5. **落盘**：base.md + 变体 + primer + preview（+ 可选 showcase）→ guard 六层审计
+
+**关键约束**：绝不静默发明（候选值标注 `sources[]` 证据）；**语义角色由人定，不由 LLM 定**；
+目标已有 base.md 时走 iterate 合并（需用户确认）。
+
+> **空目录边界（§4 文档导入同此）**：0 个可扫描文件时脚本只输出"发现文件：0"——
+> 须**提示用户核对目录**，不要拿空报告进第 3 步（会把"没扫到"误当成"候选为空"继续策展）。

package/skills/design-system/references/showcase-board-b-end.md

@@ -0,0 +1,92 @@
+# Showcase Board Brief — B 端「后台工作台」
+
+> **用途**：设计系统创建/迭代的**草案阶段**，由 `prototype-builder`（showcase 模式）产出单页展示板，
+> 供用户判断"这套设计系统产出的原型是什么效果"（设计 §4.1.7）。
+> **场景**：虚构车企「星驰汽车」的销售线索管理（DMS）后台——覆盖 B 端典型信息密度。
+> **视口**：桌面（1440px 基准）。
+
+## 产出规格
+
+- 单文件自包含 HTML：`<style>` 内联 token，**零外部依赖**（无 CDN/字体/脚本）
+- 文件名 `b-end.html`：草案阶段写入 scratch 目录；Step 6 落盘时复制到 `.team-flow/design-system/showcase/`
+- **只使用** primer 白名单内的组件与 token；白名单外需求记 `ds_increment`，不自造
+
+## 区块与组件（自上而下）
+
+> **组件名不写死（v0.55.0，设计 §8.3）**：下方只给**结构性需求**，具体组件**从当前 `.team-flow/design-system/base.md` 的 `components` 契约表选**——本文件不复制组件清单（避免静态副本 vs 动态契约表漂移）。契约表无但场景必需 → 记 `ds_increment`，或用已有组件组合表达。
+
+### 1. 顶栏
+需要：品牌标识「星驰汽车」+ 主导航（线索管理 / 订单 / 库存）+ 用户区（通知入口 + 用户身份，含姓名"王经理"）
+组件来源：从 `.team-flow/design-system/base.md` 契约表选（标识类 / 导航类 / 用户类）
+
+### 2. 数据概览（3 个 KPI 卡）
+需要：三个指标卡（指标名 + 数值 + 变化标记）
+- 今日新增线索 **47**（变化标记：+12%）
+- 待跟进 **23**（状态标记：需处理）
+- 本月成交 **8**（状态标记：达成 80%）
+
+组件来源：从契约表选（卡片/数据展示类 / 标记类）
+
+### 3. 筛选区
+需要：多条件筛选 + 操作组
+- 线索状态（候选：全部 / 新建 / 跟进中 / 已成交 / 已流失）
+- 来源（候选：官网 / 车展 / 转介绍）
+- 经销商（文本搜索输入）
+- 操作：查询 / 重置
+
+组件来源：从契约表选（表单控件类 / 按钮类）
+
+### 4. 数据表格（本板核心）
+需要：数据表格 + 状态标记 + 悬浮说明 + 分页
+- 列：客户名 / 意向车型 / 状态 / 销售顾问 / 创建时间 / 操作
+- **5-8 行真实感数据**（中文姓名、"星驰 S7 / 星驰 X5"车型名、合理时间）
+- 状态列按变体着色：已成交=success / 跟进中=warning / 新建=info / 已流失=default
+- 状态标记悬浮显示说明（如"超过 7 天未跟进"）
+- 底部分页：共 128 条 / 每页 20
+
+组件来源：从契约表选（表格类 / 标记类 / 提示类 / 分页类）
+
+### 5. 表单区（新建订单）
+需要：表单 + 多类输入控件（文本 / 下拉 / 多选 / 单选 / 开关）+ 字段级错误态
+- 客户姓名（文本输入）
+- 意向车型（下拉）
+- 经销商（下拉）
+- 配置选项（多选：智驾包 / 家用充电桩 / 延长保修）
+- 交付方式（单选：到店自提 / 送车上门）
+- 短信通知（开关，默认开）
+- **含一个字段级错误态**（如"客户姓名"必填未填 → 错误色 + 文案）
+
+组件来源：从契约表选（表单控件类 / 按钮类）
+
+### 6. 状态演示
+需要：空态 / 侧边面板 / 弹窗 / 轻提示（四类各自可触发）
+- 空态：「暂无符合条件的线索」+ 一行解释 + 「清除筛选」行动按钮
+- 侧边面板：触发按钮「查看详情」→ 线索详情（客户信息 + 跟进记录）
+- 弹窗：触发按钮「确认成交」→ 确认弹窗（含取消/确认）
+- 轻提示：触发按钮 → 成功提示（如「订单已创建」）
+
+组件来源：从契约表选（反馈/浮层类）
+
+## 硬约束（继承 P0 质检）
+
+- 全部文案为**真实感中文**（禁止 lorem / 功能一/二/三 / 示例文本 / placeholder）
+- 颜色/间距/字号一律走 token（`:root{}` 外无裸 hex）
+- 数据展示区块覆盖五状态：至少 **Empty 与 Error** 可见（Error 如"加载失败，请重试"）
+- 移动端回流：≤920px 折为单列（本板以桌面为主，但不得出现横向滚动）
+- accent 每屏 ≤2 处；emoji 不作图标
+
+## 覆盖清单（验收比对用）
+
+> **组件清单以当前 `.team-flow/design-system/base.md` 的 `components` 契约表为准**——本文件不复制该清单（避免漂移）。
+> 契约表无但场景必需 → 记 `ds_increment`，或用已有组件组合表达。
+
+| 区块 | 结构性必需 | 组件来源 |
+|------|-----------|---------|
+| 顶栏 | 品牌标识 + 主导航 + 用户区 | 从契约表选（标识/导航/用户类） |
+| 数据概览 | 3 个 KPI 卡 + 变化/状态标记 | 从契约表选（卡片/数据展示 + 标记类） |
+| 筛选区 | 3 个筛选条件 + 查询/重置操作 | 从契约表选（表单控件/按钮类） |
+| 数据表格 | 表格（5-8 行）+ 状态着色 + 悬浮说明 + 分页 | 从契约表选（表格/标记/提示/分页类） |
+| 表单区 | 表单 + 文本/下拉/多选/单选/开关 + 字段错误态 | 从契约表选（表单控件/按钮类） |
+| 状态演示 | 空态 + 侧边面板 + 弹窗 + 轻提示 | 从契约表选（反馈/浮层类） |
+
+**验收口径（v0.55.0，设计 §8.3）**：**结构性区块齐全 + token 合规 + 零白名单外自造**——不再要求静态清单逐项勾选（原清单是契约表的静态副本，快照时点 19 类 vs 现 31 类，必然漂移）。