@xulthekl/team-flow 0.52.0 → 0.54.0

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,39 @@
 ---
 
 ## 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）
 - 用 `preview-template.html` 填 token 值 → 自包含 `preview.html`（色板/排版/间距/组件/明暗切换）。
 
+## Step 4.5: Design Showcase 草案（v0.54.0 新增，设计 §4.1.7）
+
+> **可选环节**：Step 5 呈现前询问用户是否需要（**产出前明示预估耗时**，S5 实测校准后回填）；不需要则跳过。
+
+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 +149,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/showcase-board-b-end.md

@@ -0,0 +1,78 @@
+# 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`，不自造
+
+## 区块与组件（自上而下）
+
+### 1. 顶栏
+组件：**Icon / Avatar / Button**
+- 品牌标识「星驰汽车」+ 主导航（线索管理 / 订单 / 库存）
+- 右侧：通知 Icon + 用户 Avatar（含姓名"王经理"）
+
+### 2. 数据概览（3 个 KPI 卡）
+组件：**Card(stat) / Tag**
+- 今日新增线索 **47**（Tag: +12%）
+- 待跟进 **23**（Tag: 需处理）
+- 本月成交 **8**（Tag: 达成 80%）
+
+### 3. 筛选区
+组件：**FilterBar / Select / Input / Button**
+- 线索状态（Select：全部/新建/跟进中/已成交/已流失）
+- 来源（Select：官网/车展/转介绍）
+- 经销商（Input 搜索：输入经销商名称）
+- 操作：查询 / 重置
+
+### 4. 数据表格（本板核心）
+组件：**Table / Tag / Tooltip / Pagination**
+- 列：客户名 / 意向车型 / 状态 / 销售顾问 / 创建时间 / 操作
+- **5-8 行真实感数据**（中文姓名、"星驰 S7 / 星驰 X5"车型名、合理时间）
+- 状态列用 Tag 变体着色：已成交=success / 跟进中=warning / 新建=info / 已流失=default
+- Tooltip：状态 Tag 悬浮显示说明（如"超过 7 天未跟进"）
+- 底部分页：共 128 条 / 每页 20
+
+### 5. 表单区（新建订单）
+组件：**Form / Input / Select / Checkbox / Radio / Switch / Button**
+- 客户姓名（Input）
+- 意向车型（Select）
+- 经销商（Select）
+- 配置选项（Checkbox 多选：智驾包 / 家用充电桩 / 延长保修）
+- 交付方式（Radio：到店自提 / 送车上门）
+- 短信通知（Switch，默认开）
+- **含一个字段级错误态**（如"客户姓名"必填未填 → 错误色 + 文案）
+
+### 6. 状态演示
+组件：**EmptyState / Drawer / Modal / Toast**
+- EmptyState：「暂无符合条件的线索」+ 一行解释 + 「清除筛选」行动按钮
+- Drawer：触发按钮「查看详情」→ 侧边面板（线索详情：客户信息 + 跟进记录）
+- Modal：触发按钮「确认成交」→ 确认弹窗（含取消/确认）
+- Toast：触发按钮 → 成功提示（如「订单已创建」）
+
+## 硬约束（继承 P0 质检）
+
+- 全部文案为**真实感中文**（禁止 lorem / 功能一/二/三 / 示例文本 / placeholder）
+- 颜色/间距/字号一律走 token（`:root{}` 外无裸 hex）
+- 数据展示区块覆盖五状态：至少 **Empty 与 Error** 可见（Error 如"加载失败，请重试"）
+- 移动端回流：≤920px 折为单列（本板以桌面为主，但不得出现横向滚动）
+- accent 每屏 ≤2 处；emoji 不作图标
+
+## 覆盖清单（验收比对用）
+
+| 组件 | 出现区块 | 组件 | 出现区块 |
+|------|---------|------|---------|
+| Button | 全局 | Table | 数据表格 |
+| Card | 数据概览 | Tooltip | 数据表格 |
+| Tag | 概览/表格 | Pagination | 数据表格 |
+| FilterBar | 筛选区 | Form | 表单区 |
+| Select | 筛选/表单 | Checkbox | 表单区 |
+| Input | 筛选/表单 | Radio | 表单区 |
+| Icon | 顶栏/操作 | Switch | 表单区 |
+| Avatar | 顶栏 | EmptyState / Drawer / Modal / Toast | 状态演示 |

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

@@ -0,0 +1,92 @@
+# Showcase Board Brief — C 端「官网 + 车主 APP」
+
+> **用途**：设计系统创建/迭代的**草案阶段**，由 `prototype-builder`（showcase 模式）产出展示板，
+> 供用户判断"这套设计系统在 C 端语境的产出效果"（设计 §4.1.7）。
+> **场景**：虚构车企「星驰汽车」的官网车型展示 + 车主 APP 服务。
+> **视口**：官网 = 桌面（1440px）；APP = 移动（390px）。
+
+## 产出规格
+
+- **两个**单文件自包含 HTML：`c-end-website.html`（桌面）+ `c-end-app.html`（移动）
+- `<style>` 内联 token，**零外部依赖**
+- **只使用** primer 白名单内的组件与 token；白名单外需求记 `ds_increment`，不自造
+
+---
+
+## 板 1：官网车型展示（c-end-website.html，桌面视口）
+
+### 区块 1：Hero
+组件：**Button / Icon**
+- 品牌主张（一句话，如「星驰 S7 ｜ 智能电动，从容出行」）
+- 主 CTA：「预约试驾」+ 次 CTA：「查看配置」
+
+### 区块 2：车型卡片网格（3 列）
+组件：**Card / Tag / Button**
+- 3 个车型卡：星驰 S7（Tag: 新车）/ 星驰 X5（Tag: 热销）/ 星驰 E3（Tag: 限时权益）
+- 每卡：车型名 + 一句话卖点 + 价格区间（"¥22.98 万起"）+ 「了解详情」按钮
+- 图片位用 `.ph-img` 占位（零外部依赖：不得链外网图）
+
+### 区块 3：参数对比
+组件：**Tabs / Table / Tooltip**
+- Tabs：续航 / 性能 / 智能座舱
+- Table：参数对比表（车型 × 参数，3 行 × 4 列）
+- Tooltip：专业术语悬浮说明（如"CLTC 续航"）
+
+### 区块 4：预约试驾表单
+组件：**Form / Input / Select / Radio / Button**
+- 姓名（Input）、手机号（Input）、意向车型（Select）、经销商（Select）
+- 试驾时间（Radio：本周内 / 周末 / 随时）
+- 提交按钮 + 提交中态示例
+
+**官网覆盖**：Button / Icon / Card / Tag / Tabs / Table / Tooltip / Form / Input / Select / Radio
+
+---
+
+## 板 2：车主 APP（c-end-app.html，移动视口 390px）
+
+### 区块 1：我的车辆
+组件：**Card / Tag / Avatar / Icon / Button**
+- 车辆卡：车型名「星驰 S7」+ 车牌（如"沪 A·D12345"）+ 状态 Tag（已连接）
+- 快捷操作：解锁 / 空调 / 充电（Icon + Button）
+- 右上角用户 Avatar
+
+### 区块 2：服务记录
+组件：**Card / Tag / EmptyState**
+- 记录列表（2-3 条）：保养 / 维修 / 充电订单 + 状态 Tag + 时间
+- 空态示例：EmptyState「暂无服务记录」+ 「预约保养」行动
+
+### 区块 3：设置项
+组件：**Switch / Button**
+- 消息通知（Switch 开）、车辆定位共享（Switch 关）
+- 「退出登录」按钮（次要样式）
+
+### 区块 4：交互演示
+组件：**Modal / Tooltip / Toast**
+- Modal：触发「预约保养」→ 确认弹窗
+- Tooltip：设置项说明
+- Toast：操作反馈（如「已解锁」）
+
+**APP 覆盖**：Card / Tag / Avatar / Icon / Button / EmptyState / Switch / Modal / Tooltip / Toast
+
+---
+
+## 硬约束（继承 P0 质检）
+
+- 全部文案为**真实感中文**（禁止 lorem / 功能一/二/三 / 示例文本）
+- 颜色/间距/字号一律走 token；图片用占位样式（`.ph-img`），**图片占位不链外网**
+- APP 板为移动视口：单列布局、触控目标 ≥44px，无横向滚动
+- 数据展示区块覆盖五状态（至少 Empty 与 Error 可见）
+- accent 每屏 ≤2 处；emoji 不作图标
+
+## 覆盖清单（验收比对用）
+
+| 组件 | 板 | 组件 | 板 |
+|------|----|------|----|
+| Button | 官网+APP | Tooltip | 官网+APP |
+| Icon | 官网+APP | Form | 官网 |
+| Card | 官网+APP | Input | 官网 |
+| Tag | 官网+APP | Select | 官网 |
+| Tabs | 官网 | Radio | 官网 |
+| Table | 官网 | Avatar | APP |
+| EmptyState | APP | Switch | APP |
+| Modal / Toast | APP | （本板 16 类；Checkbox / Pagination / FilterBar / Drawer 不在本板，由 `showcase-board-b-end.md` 覆盖——**两板合计覆盖 20 类基线全量**） | |

package/skills/design-system/references/token-derivation.md

@@ -1,4 +1,6 @@
-# 确定性 Token 派生规则（v0.19.0）
+# 确定性 Token 派生规则（v0.54.0）
+
+> **本文件是设计系统全部具体数值的单一真相源**（色值 / 间距 / 字阶 / 字体栈 / density 倍率 / dark 派生）；其它文件（`creation-flow.md` 等）出现分歧时以本文件为准。v0.54.0 新增：density 倍率语义 + 确定性 dark 派生规则。
 
 > **原则**: 同输入 = 同输出。不即兴发挥。每个 token 值由映射表确定性决定。
 
@@ -14,8 +16,8 @@
 | `--muted` | fg lightened 40% | `#6B6964` |
 | `--border` | fg lightened 80% | `#E8E5DF` |
 | `--accent` | mood→accent mapping (or user hex) | `#3B82F6` |
-| `--font-display` | font preference→stack | `Georgia, serif` (serif_display) |
-| `--font-body` | always system sans | `-apple-system, system-ui, sans-serif` |
+| `--font-display` | font preference→stack | `'Iowan Old Style', Charter, Georgia, serif` (serif_display；sans_display 见 creation-flow 维度 3) |
+| `--font-body` | always system sans | `-apple-system, 'Segoe UI', system-ui, sans-serif` |
 
 ---
 
@@ -106,10 +108,33 @@
 
 ## Density → 间距/排版修正
 
-| Density | base font | space unit | container |
-|---------|-----------|------------|-----------|
-| compact | 14px | 4px | 1280px |
-| balanced | 16px | 4px | 1120px |
-| spacious | 18px | 8px | 960px |
+| Density | 倍率 | base font | `--space-4` | container |
+|---------|------|-----------|-------------|-----------|
+| compact | ×0.75 | 14px | 12px | 1280px |
+| balanced | ×1.0 | 16px | 16px | 1120px |
+| spacious | ×1.25 | 18px | 20px | 960px |
+
+**倍率语义（确定性）**：`--space-N` = 下方 4px 基准阶梯（4/8/12/16/20/24/32/40/48/64/80/96）× density 倍率，取整到整数 px；`--radius-*` 与字阶同倍率。density **不改变** token 名称或色彩。
+
+> **单一真相源**：本表是 density 数值的权威；`creation-flow.md` 维度 4 表必须与本表逐值一致。
+
+---
+
+## Dark 主题派生规则（v0.54.0）
+
+`theme` 维度取 `dark` 或 `both` 时启用。**确定性派生**（同输入同结果），产出 `variants/dark.md`——只写差异 token，继承 base 其余部分。
+
+| Token | 派生规则 |
+|-------|---------|
+| `--bg` | 近黑画布：按 mood 从 fg 转极暗（professional_minimal → `#0A0A0B`；warm_approachable → `#141210`；technical_dense → `#0B1220`；editorial → `#0A0A0B`；brutalist → `#000000`） |
+| `--surface` | bg 提亮一阶（如 `#141517`） |
+| `--fg` | 从原 `--bg` 转亮（如 `#EDEDEC`） |
+| `--muted` | fg 降 40% 明度 |
+| `--border` | `rgba(255,255,255,0.08)` 半透明体系（不透明描边在暗底上过重） |
+| `--accent` | 保持色相；按对比度**有界确定性**提亮：计算 `contrast(accent, dark --bg)`，若 <4.5:1 则按 10% 步长提亮（`color-mix(in oklab, var(--accent), white N×10%)`，N=1..3）取首个达标值；**N=3 仍不足 → 记入 `extensions`（C-token 名单）留人工裁定，不静默继续** |
+
+**对比度校验**：正文 ≥4.5:1、大字 ≥3:1（WCAG AA）——派生后逐对校验 fg/bg 与 accent/bg。
+
+**A2/B-slot 不重复派生**：`--accent-hover` 等 A2 公式与 B-slot 别名随 `--accent`/`--fg` 自动生效（color-mix 引用变量），dark 变体只需覆写上表 6 个基色。
 
-density 只影响数值倍率，不影响 token 名称或色彩。
+**验证**：guard 六层审计的 L1-双主题维度——检测到 `variants/dark.md` 或 CSS 中的 `[data-theme="dark"]` 覆盖即达标。

package/skills/design-system/references/variant-schema.md

@@ -5,7 +5,11 @@
 
 ```
 .team-flow/design-system/
-├── base.md      # 品牌共享层（color/brand/voice/anti-patterns/extensions）
+├── base.md      # 品牌共享层（color/brand/voice/anti-patterns/extensions + components 契约表全量真源）
+├── primer.md    # AI 约束入口（gen-primer 生成：组件白名单 + Token 速查 + digest）
+├── pending.md   # 增量待办（单写者 = design-system skill）
+├── showcase/    # 展示板（草案阶段产出，供用户判断效果）
+├── variants/    # 主题变体（dark.md——确定性派生规则见 token-derivation.md）
 ├── b-end.md     # B 端变体（typography/spacing/layout/components/motion）
 ├── c-end.md     # C 端变体（同结构，按 C 端密度/字号覆写）
 └── preview.html
@@ -22,6 +26,13 @@
 | `voice` | 文案语气（专业/简洁/温度等级），跨端统一 | voice |
 | `anti-patterns` | 禁止内联样式漂移 / 禁止非 token 颜色 / 禁止跨端私改品牌色（**必含前两条**） | anti-patterns |
 | `extensions` | C-token 名单制清单：品牌专有 token + 提升路径标注（C→B→A2） | C-extension |
+| `components` | **组件契约表（全量真源，v0.54.0）**：`\| 组件 \| 类型 \| variants \| sizes \| states \| 用途 \| 禁止 \|`；类型 ∈ 交互/轻量/豁免（决定 guard 的 states 下限：交互 ≥3 / 轻量 ≥2 / 豁免跳过；**交互/轻量的 variants 亦必填**，guard 会判违规）；≥15 类 PASS / 10-14 类 WARN / <10 类 FAIL 标签 | components |
+| `principles` | **设计原则 ≥3 条（v0.54.0）**：如"一致性优先于局部创意 / 清晰优于装饰 / 可访问性默认开启" | principles |
+| `governance` | **治理声明（v0.54.0）**：`contract: v1\|legacy`（guard 降级判定依据）+ version + 负责人 + 弃用策略 + changelog 指向 | governance |
+
+> **a11y 声明（v0.54.0）**：base.md 文档头部（标题下）增加一行 `> a11y: WCAG 2.2 AA（对比度 4.5:1 / 大字 3:1 / 焦点可见 / 键盘可达）`——从 prototype craft 层**提级**到设计系统层（guard 六层审计的 L0-可访问性依据）。
+>
+> **`contract` 标记语义**：`v1` = 新体系（六层审计不达标标 FAIL 标签）；`legacy` 或无标记 = 存量（降级 WARN）。升级动作 = 重跑 iterate 补契约表时由 architect 置为 `v1`。guard `--strict` 可让 legacy 按 v1 标签输出（供自查，不改变 exit code）。
 
 > base 不含排版/间距/布局——这些随端变化，归变体。base 的 A1+A2+B-slot 必须完整可过 guard。
 
@@ -32,7 +43,7 @@
 | `typography` | font-display/body/mono 引用 + type scale（`--text-xs~4xl`，1.25 比例）+ weights + line-height（按 density） | A1-structure |
 | `spacing` | `--space-1~12` 阶梯（基于 density 基准：compact 12 / balanced 16 / spacious 20） | A2-derived |
 | `layout` | 栅格 12 列 / 断点 sm/md/lg / 容器 max-width（B 端宽容器、C 端窄容器） | A1-structure |
-| `components` | button / input / card / table 规范（**最少这 4 类**），全部 token-bound，引用 B-slot | components |
+| `components` | **端特有覆盖说明（v0.54.0 改）**：只写该端对 base.md 契约表的差异（如 C 端 Button 用 pill 圆角）并**引用**契约表；**不再重复定义组件清单**（全量真源在 base.md——消除双份维护） | components（差异） |
 | `motion` | duration（`--motion-fast/base`，150–300ms）+ `--ease-standard` | A2-derived |
 
 > B 端 vs C 端差异示例：B 端 compact + 14px + 宽表格容器；C 端 spacious + 17px + 窄卡片容器。
@@ -57,4 +68,4 @@
 - 渲染某端时：把 base `:root` + 该端变体 `:root` 合并进**单个 `<style>`**（无全局级联）。
 - 缺任何一个 A1/A2/B-slot token → 规则悄悄失效 → `design-token-guard.mjs` 失败。
 - 同 token 名 base 与变体冲突时：**变体优先**（仅限排版/间距/布局/动效类）；颜色/品牌类冲突 = 错误，guard 报错。
-- 迭代（iterate）走 MERGE 不 OVERWRITE：新组件进变体 `components`，新共享色进 base `color`，并记变更履历。
+- 迭代（iterate）走 MERGE 不 OVERWRITE：**新组件进 base `components` 契约表**（全量真源，见 §base.md 段落与 :42），端特有点（如圆角/密度差异）写变体 `components` 的覆盖说明；新共享色进 base `color`，并记变更履历。

package/skills/prototype/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prototype
-description: 本地 HTML 原型设计与维护 skill（零外部依赖、可离线）。产品级需求的原型环节由 workflow-orchestrator S2 内部调用（含 PRD 一致性自动评审循环）；直接调用仅限：独立原型迭代、change 完成回写（prototype-sync）、设计系统(design-system.md)创建/维护。当用户需要基于项目设计系统产出/迭代全局 prototype/（多页面+组件+导航的自包含 HTML 原型系统）时使用。不适用于：依赖 GUI 设计软件（Claude Design / Open Design 桌面应用 / Trae）、需要高保真交互动效、非 HTML 原型场景。
+description: 本地 HTML 原型设计与维护 skill（零外部依赖、可离线）。产品级需求的原型环节由 workflow-orchestrator S2 内部调用（含 PRD 一致性自动评审循环）；直接调用仅限：独立原型迭代、change 完成回写（prototype-sync）、design-system skill 的 Showcase 展示板模式（mode=showcase）。当用户需要基于项目设计系统产出/迭代全局 prototype/（多页面+组件+导航的自包含 HTML 原型系统）时使用。不适用于：依赖 GUI 设计软件（Claude Design / Open Design 桌面应用 / Trae）、需要高保真交互动效、非 HTML 原型场景。
 ---
 
 # Prototype（本地 HTML 原型 skill）
@@ -8,14 +8,14 @@ description: 本地 HTML 原型设计与维护 skill（零外部依赖、可离
 基于 team-flow v0.3 第十五章 + v0.15.0 内部编排重构。全局一份 `prototype/`（与 PRD 同级，git 分支隔离），由本 skill 产出维护，**零外部依赖、可离线**。
 
 ## 何时使用
-- 新项目初始化：基于 PRD(v1) + 项目 `design-system.md` 生成 `prototype/`（设计系统缺失时先创建设计系统）。
+- 新项目初始化：基于 PRD(v1) + 项目 `.team-flow/design-system/`（base.md + 端变体）生成 `prototype/`（设计系统缺失时先创建设计系统）。
 - 需求迭代：PRD 升版（v1→v2）时，在对应 git 分支演进 `prototype/`。
 - change 实施：各 change 引用全局 `prototype/` 作 UI 契约（进 `execution-contract.md`）。
-- change 完成：UX 增量经 `prototype-sync` 回写全局 `prototype/` + `design-system.md`。
+- change 完成：UX 增量经 `prototype-sync` 回写全局 `prototype/` + `.team-flow/design-system/`。
 
 ## 内部编排模型（v0.15.0 核心，主代理只编排不实施）
 
-> **硬原则**：本 skill 加载进主上下文后，**主代理只做编排**（环境探查派发、评审组织、循环控制、人工评审、路由决策），**严禁主代理直接 Write/Edit 原型 HTML 或 design-system.md**。所有探查/绘制/设计系统产出经子代理（§18.1 交接协议）。人工评审/路由因需 AskUserQuestion 必须由主代理执行（subagent 不能阻塞提问）。
+> **硬原则**：本 skill 加载进主上下文后，**主代理只做编排**（环境探查派发、评审组织、循环控制、人工评审、路由决策），**严禁主代理直接 Write/Edit 原型 HTML 或 `.team-flow/design-system/` 下任何文件**。所有探查/绘制/设计系统产出经子代理（§18.1 交接协议）。人工评审/路由因需 AskUserQuestion 必须由主代理执行（subagent 不能阻塞提问）。
 >
 > **后台子代理等待范式（v0.20.0）**：③绘制 / ④评审是长任务（实测 25-50 分钟）。派发后台子代理后**依赖完成通知（`<task-notification>`）再行动**，**禁止反复 `TaskOutput(block=true)` 阻塞轮询**——其对长任务超时返回会倾泻完整子代理 transcript（含 thinking/tool_use/tool_result，单次数万 token），连续轮询会撑爆主上下文。长任务派发后可先处理可并行工作或结束本轮等待通知，**不空转死等**；确需中途观察用 `block=false` 轻量查询（仍返转录，尽量不用）。（设计 §22.2）
 
@@ -29,6 +29,9 @@ description: 本地 HTML 原型设计与维护 skill（零外部依赖、可离
                           - PRD 有问题 → 回 orchestrator S2 修订 PRD（vN 内修订，非升版）→ 再更新原型
                           - 原型需调整 → 回 ③ 派 prototype-builder 实施
                           - 通过 → 冻结
+                          - 设计系统增量确认（v0.54.0）：handoff 含 ds_increment 时并入呈现
+                            [全部确认|逐项确认|暂不处理]；确认项调 design-system iterate
+                            （延迟到 builder 终态后）；不处理记入 pending.md（design-system skill 写）
 ```
 
 详细步骤、子代理派发提示词、收敛检测、设计系统生命周期见 `references/orchestration-flow.md`。
@@ -45,8 +48,10 @@ description: 本地 HTML 原型设计与维护 skill（零外部依赖、可离
 ## 内核（零外部依赖）
 - 自包含 HTML：CSS 进 `<style>`、JS 进 `<script>`，页面内 `<div id="tweaks">` 控件替代云端工具栏。
 - **avoid remote dependencies**：无 CDN、无外部字体/脚本，可完全离线。
-- 设计系统渲染：读取项目 `design-system.md`（9 段 schema + 5 方向调色板 + aliases 别名层 + extensions，v0.18.0 token 四层模型），渲染 token 到 `assets/design-tokens.css`。
-- **种子模板 + 骨架库（v0.18.0）**：builder 从 `references/template.html`（种子）+ `references/layouts.md`（8 个 B 端 section 骨架 + 类清单契约）组合，不从零写 CSS。
+- 设计系统渲染：读取项目 `.team-flow/design-system/<variant>.md` + `base.md`（base 品牌层 + 端特有层合并；9 段 schema + 5 方向调色板 + aliases 别名层 + extensions，v0.18.0 token 四层模型），渲染 token 到 `assets/design-tokens.css`。
+- **种子模板 + 骨架库（v0.18.0）**：builder 从 `references/template.html`（种子）+ `references/layouts.md`（14 个 section 骨架 + 类清单契约）组合，不从零写 CSS。
+- **组件白名单（v0.54.0）**：builder 从 `.team-flow/design-system/primer.md` 提取可用组件白名单（Step 0 gate 校验 digest；primer 缺失/过期按 `governance.contract` 字段 blocked(v1)/WARN(legacy)）；白名单外需求记 `ds_increment`，不自造。
+- **Showcase 模式（v0.54.0，对外契约）**：`prototype-builder` 支持 `mode: showcase`（供 design-system skill 单次派发产出展示板）——gate 豁免 `confirmed_plan`/`prd_path`，产出 flat 单文件，最小交付契约见 `references/builder-methodology.md`。
 - **工艺规则层（v0.18.0）**：`references/checklist.md`（P0/P1/P2）+ `references/craft/`（anti-ai-slop / state-coverage / typography-hierarchy / accessibility-baseline / laws-of-ux），品牌无关，B 端导向。
 - **原型类型方法论（v0.24.0）**：`references/interactive-prototype.md`（交互原型：零依赖状态管理+表单验证+多步导航）+ `references/wireframe.md`（线框图：低保真快速探索+3-5 差异化方案+并排对比），按需加载。
 
@@ -57,10 +62,11 @@ prototype/
 ├── pages/              # 多页面
 ├── components/         # 可复用组件（统一设计系统）
 ├── assets/             # design-tokens.css / design-tokens.js
-├── design-system.md    # 本项目设计系统（config 注入，9 段 schema）
 └── flow.md             # 页面跳转 / 用户流
 ```
 
+> 设计系统**不在此目录**——存于 `.team-flow/design-system/`（v0.19.0 起；base.md + 端变体 + primer.md）。
+
 ## 设计系统生命周期（v0.15.0 新增，v0.19.0 独立化）
 ```
 首次创建 → 引用 → 增量更新（变更履历）
@@ -81,7 +87,7 @@ prototype/
 - 插件层用 `tf runtime config --get <key>` 自读；插件保持通用，不固化任何公司/产品风格。
 
 ## 膨胀防控
-- `components/` 必须复用 `design-system.md` 组件，**禁止页面内联样式漂移**。
+- `components/` 必须复用 `.team-flow/design-system/` 契约表组件，**禁止页面内联样式漂移**。
 - 新增组件先沉淀进 `design-system` 再引用。
 
 ## 分支约定
@@ -91,7 +97,7 @@ prototype/
 
 ## prototype-sync（change 完成回写，release-archivist 自动触发，v0.24.0 升级）
 
-> **触发机制（v0.24.0）**：prototype-sync 由 `release-archivist` closing 流程**自动触发**（`arch-merge → prototype-sync → compound promotion` 顺序执行），不再是手动 SOP。release-archivist Step 5 Report 中 `Prototype sync` 行是必填维度，未执行时 closing 报告不完整。
+> **触发机制（v0.24.0；v0.53.0 补入状态转换位次）**：prototype-sync 由 `release-archivist` closing 流程**自动触发**（`arch-merge → state transition closing → prototype-sync → compound promotion` 顺序执行），不再是手动 SOP。release-archivist Step 5 Report 中 `Prototype sync` 行是必填维度，未执行时 closing 报告不完整。
 >
 > **独立调用**：仍可独立调用（如 change 中途需要预同步），但标准路径是 closing 自动触发。
 
@@ -99,7 +105,7 @@ prototype/
 2. **派 `prototype-builder`（修正/演进模式）**把增量合并进全局 `prototype/`（pages/components/assets/flow.md）——主代理不直接写原型 HTML。
 3. 若涉及设计系统迭代，调用 `/team-flow:design-system`（iterate 模式）合并进 `.team-flow/design-system/` 并记变更履历。
 4. 人工确认增量无误。
-5. **顺序提交**：`arch-merge` → `prototype-sync`（同一 change closing 内）。
+5. **顺序提交**：`arch-merge` → `state transition closing` → `prototype-sync`（同一 change closing 内）。**状态转换必须在 arch-merge 之后、prototype-sync 之前**（v0.53.0 §110 B' 时序前移：`executing→closing` 挂 `arch-merged` 门禁，未回写则转换被拒）。
 
 ## 脚手架
 新建项目：`cp -r references/prototype-scaffold/ <project>/prototype/`，再按 `.team-flow/design-system/` 的设计系统填 token（缺设计系统先用 `/team-flow:design-system` 创建）。

package/skills/prototype/references/builder-methodology.md

@@ -10,9 +10,9 @@
    - CSS 一律进 `<style>`，JS 一律进 `<script>`，页面内 `<div id="tweaks">` 控件替代云端工具栏。
    - 资源仅来自 `prototype/assets/`（本地）。
 2. **复用设计系统 token，禁止内联样式漂移**：
-   - 渲染 `design-system.md` 的 token 到 `assets/design-tokens.css`（CSS 变量），所有页面/组件通过 `var(--token)` 引用。
+   - 渲染 `.team-flow/design-system/` 的 token（base 品牌层 + 端变体合并）到 `assets/design-tokens.css`（CSS 变量），所有页面/组件通过 `var(--token)` 引用。
    - 颜色/间距/字号/圆角等一律走 token，**禁止**在页面里写死 `#hex` / `padding: 13px` 之类非 token 值。
-   - 复用 `components/` 已有组件；新增组件**先沉淀进 design-system 再引用**（如发现 design-system 缺组件，记入 outstanding_questions，不擅自新建漂移组件）。
+   - 复用 `components/` 已有组件；**新增组件必须来自 primer 白名单**（v0.54.0）——白名单外的组件需求记入 `ds_increment`（不擅自新建漂移组件）；新增组件先沉淀进 design-system 再引用。
 3. **遵循 confirmed_plan**：页面清单、组件清单、导航流以确认方案为准，不自行增删页面。
 
 ## Build Process
@@ -20,28 +20,46 @@
 ### Step 0: Precondition Gate（阻断检查）
 
 Before writing anything, verify:
+
 - `design_system_path` exists and is readable → if missing/unreadable, return `status: blocked` (blocker: 设计系统缺失，需先派 design-system-architect).
+- **primer.md 检查（v0.54.0 新增——组件白名单来源）**：
+  1. **primer 存在且可读** → 提取 `available_components` 白名单（Step 1.5/Step 2 只用这些组件）。
+     - **digest 校验**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/gen-primer.mjs <base.md 路径> --check`
+       - exit 0（一致）→ 继续
+       - exit 2（过期：base.md 已变更）→ 读 base.md 的 `governance.contract`：
+         - `contract: v1` → `status: blocked`（blocker: primer 过期，请跑 design-system iterate 重新生成）
+         - `contract: legacy` 或无标记 → WARN + 提示，按现有 primer 继续
+  2. **primer 缺失** → 读 base.md 的 `governance.contract`：
+     - `contract: v1` → `status: blocked`（blocker: 设计系统缺少 primer，请跑 design-system iterate 生成）
+     - `contract: legacy` 或无标记 → **WARN + 降级继续**：
+       - 降级路径：读设计系统目录内任意 `components` 段（**优先变体文件** b-end.md/c-end.md——存量系统的 components 在变体文件，base.md 可能没有该段）
+       - 绘制结束在 handoff 中**强制提示**："请跑 design-system iterate 补契约表并升级 contract: v1"
 - `confirmed_plan` is present and marked confirmed → if absent or explicitly unconfirmed, return `status: blocked` (blocker: 原型方案未确认，需主代理先完成方案评审 + 人工确认).
 - `prd_path` readable → if missing, `status: blocked` (blocker: PRD 缺失).
 
+> **判定口径（v0.54.0 定案）**：blocked/WARN 的判定**只看 `governance.contract` 字段**——`v1` = 新体系（缺失/过期均 blocked）；`legacy` 或无标记 = 存量（WARN + 降级）。
+
 Do NOT proceed past a failed gate.
 
 ### Step 1: Render Design Tokens
 
 1. Read `.team-flow/design-system/<variant>.md` + `base.md`（合并 base 品牌层 + 变体端特有层：9 段 schema + palette 5 方向调色板 + aliases 别名层 + extensions 待提升清单）.
 2. Generate/refresh `assets/design-tokens.css` with CSS custom properties for every token (colors incl. palette 50–900 steps, spacing scale, font scale, radii, shadows, durations, A2 派生状态色, B-slot 别名).
-3. **完整性约束**：design-tokens.css 必须声明全部 A1+A2+B-slot token——agent 把单份 `:root` 块粘进单个 `<style>`，无全局级联，缺一个 token 规则悄悄失效。可运行 `node scripts/guard/design-token-guard.mjs <design-system.md> <design-tokens.css>` 自检。
+3. **完整性约束**：design-tokens.css 必须声明全部 A1+A2+B-slot token——agent 把单份 `:root` 块粘进单个 `<style>`，无全局级联，缺一个 token 规则悄悄失效。可运行 `node ${CLAUDE_PLUGIN_ROOT}/scripts/guard/design-token-guard.mjs <设计系统目录> <design-tokens.css>` 自检。
 
 ### Step 1.5: Seed Composition（种子优先，v0.18.0）
 
 **不从零写 CSS——从种子模板 + 骨架库组合。**
 
-1. 读 `references/template.html`（至少到 `</style>` 结尾）+ 读 `references/layouts.md`（8 个 section 骨架 + 类清单契约 + 页面类型节奏表）。
+1. 读 `references/template.html`（至少到 `</style>` 结尾）+ 读 `references/layouts.md`（14 个 section 骨架 + 类清单契约 + 页面类型节奏表）。
 2. **先选 section 列表再写文案**：按页面类型查节奏表（管理后台列表页 / 表单页 / 仪表盘 / Landing / 文档索引），为每个页面选定 section 组合。选定后**用一句话向主代理报出 section 列表**（写入 `outstanding_questions`，question = "页面 X 计划用 section 组合：hero → log → stats，此刻改向便宜，而不是 200 行 HTML 之后"，default_assumption = 按此组合继续）。
 3. 从 `layouts.md` 粘贴对应骨架到 `<main id="content">`，替换 `[REPLACE]` 槽为 PRD 中的真实、具体文案。
    - **"槽位空着说明选错了布局，换一个，不许编文案。"**
    - 类清单契约：只用 template.html `<style>` 中已定义的类；够不到的类先在页面 `<style>` 定义，绝不凭空发明全局类。
 4. 纪律约束（来自 layouts.md 各骨架）：stats ≤3 个且不编造指标；quote 每页 ≤1 个；accent 每屏 ≤2 处；section 节奏交替（禁止连续同类型）。
+5. **组件白名单约束（v0.54.0）**：只用 Step 0 从 primer 提取的 `available_components` 白名单组件。
+   - 需要白名单外组件时 → **记入 `design_system_increments`**（见下方 Structured Handoff 的 `ds_increment` 字段），用可行 workaround 继续（**判据**：能用 ≥2 个白名单组件组合等价表达 → workaround；否则走 stop-and-resume 由主代理裁决）
+   - **自造组件 = 违反 Hard Constraints**（与"禁止内联样式漂移"同级）
 
 ### Step 2: Build Structure
 
@@ -92,6 +110,37 @@ P1 逐项自查（节奏交替 / 标题 ≤14 词 / CTA 说明动作 / hover 态
 - Keep token reuse; do not introduce new inline drift while fixing.
 - Do not touch unrelated pages.
 
+## Showcase 模式（v0.54.0，对外契约）
+
+> **触发**：design-system skill 在创建/迭代的**草案阶段**做单次派发（`mode: showcase`），产出设计系统展示板。
+> **对外契约声明**：本模式是 prototype skill 的正式对外接口（供 design-system skill 调用）——gate 差异与交付契约见下。
+
+### Gate 差异
+- **豁免** `confirmed_plan` / `prd_path`（showcase 无 PRD）
+- **要求**：showcase-board brief 可读（`skills/design-system/references/showcase-board-{b,c}-end.md`——由派发方传入路径）
+- **要求**：设计系统草案路径可读（含 primer 草案；用草案 base 的 digest 校验，正式 base.md 此时尚不存在）
+
+### 产出差异
+- **flat 单文件**：`b-end.html` / `c-end-website.html` / `c-end-app.html`（不建 `pages/` 目录树、不写 `flow.md`）
+- 写入派发方指定的 scratch 路径（`/tmp/ds-draft-<slug>/showcase/`）；**不移正、不落正式路径**（由 design-system skill 在 Step 6 复制）
+
+### 最小交付契约（返回 `done` 的硬前置）
+1. brief 的全部区块已渲染（对照 brief 的"覆盖清单"逐项勾选）
+2. 无填充文案（grep `lorem|功能[一二三]|示例文本|TODO` = 0）
+3. **P0 grep 通过**（裸 hex / 靛蓝黑名单 / emoji / 填充文案——机械检查，不依赖 PRD）
+4. `<style>` 内 token 全部来自 primer 草案（无自造 token）
+
+> showcase **不跑 prototype-reviewer**（其 D1-D4 依赖 PRD）——P0 grep 是它的最低验证环节。
+
+### Hard Gate 适配
+Deliverable Hard Gate 同样适用，但"核心产物"改为**brief 要求的全部 Board 文件**（如 C 端要 2 个文件则 2 个都要落盘非空）；沿用同样的自检命令：
+```bash
+test -f <scratch>/showcase/b-end.html && test -s <scratch>/showcase/b-end.html && echo OK
+```
+
+### Handoff
+沿用 Structured Handoff 结构；`deliverable` = scratch 内 Board 文件绝对路径清单；组件缺口记入 `outstanding_questions`（`ds_increment`，`increment_kind: missing_component`）——供 Step 5 用户评审时一并裁决（这正是"组件契约可用性验证"的产出）。
+
 ## data-testid Discipline（可选，config 驱动）
 
 When the project enables E2E (`prototype.e2e: true` or stated in the plan):
@@ -107,7 +156,15 @@ When not enabled, do not over-tag.
   status: "done" | "done_with_questions" | "blocked",
   deliverable: <prototype 入口绝对路径 + 页面/组件清单>,
   blockers: [ { question, why_blocking, options[] } ],          # 阻断项：无法继续、必须主代理裁决
-  outstanding_questions: [ { question, default_assumption } ],  # 非阻断：已按默认假设继续，回主代理批量确认
+  outstanding_questions: [
+    { question, default_assumption },                            # 普通非阻断疑问
+    { type: "ds_increment",                                      # 设计系统增量（v0.54.0）
+      increment_kind: "missing_component" | "outdated_token" | "new_variant",
+      target: <组件名或 token 名>,
+      reason: <为什么需要>,
+      workaround: <临时替代方案>,
+      evidence: <页面:行号> }
+  ],
   summary: <3-5 行 gist>
 }
 ```

package/skills/prototype/references/craft/anti-ai-slop.md

@@ -15,7 +15,7 @@ AI 产物中最常见的颜色。黑名单 hex：
 grep -nE '#(6366f1|4f46e5|4338ca|3730a3|8b5cf6|7c3aed|a855f7)' *.html *.css
 ```
 
-accent 必须来自项目设计系统（`design-system.md`）；无设计系统时须选有品牌理由的颜色。
+accent 必须来自项目设计系统（`.team-flow/design-system/`）；无设计系统时须选有品牌理由的颜色。
 
 ### ② 信任渐变
 紫→蓝、蓝→青的线性渐变是 AI 落地页的招牌。无 purple/violet 的 linear-gradient；

package/skills/prototype/references/craft/state-coverage.md

@@ -57,13 +57,19 @@
 | 1s+ | 骨架 + spinner，或转入明确加载态 |
 | 60s+ | 停止等待，转错误态并提供重试 |
 
-## 测试矩阵模板
+## 测试矩阵模板（v0.54.0 收敛版）
 
-每页交付前逐格填写，作为原型验收项：
+每页交付前逐格填写，作为原型验收项。
+
+**粒度规则（收敛）**：
+- 默认**页面粒度**（一行一页）
+- 仅当「**数据承载组件且页面内多实例**」时，为该组件**加子行**——避免全组件展开导致的记账膨胀（6 页 × 5 组件 × 5 状态 = 150 格，超出 builder 输出预算）
+- 数据承载组件 = Table / List / Card 列表 / Form / EmptyState
 
 | 页面/组件 | Loading | Empty | Error | Populated | Edge |
 |----------|---------|-------|-------|-----------|------|
 | 订单列表 | ☐ 骨架屏 | ☐ 插画+创建入口 | ☐ 重试+错误ID | ☐ 47 条 | ☐ 标题 50 字 |
+| — 其中 Table（3 处实例） | ☐ 骨架 | ☐ | ☐ 重试 | ☐ 47条 | ☐ 超长标题 |
 | KPI 仪表盘 | ☐ | ☐ | ☐ | ☐ | ☐ 数字过亿 |
 | 新建表单 | — | — | ☐ 字段级+摘要 | ☐ | ☐ 备注 500 字 |