@xulthekl/team-flow 0.53.0 → 0.54.0

package/scripts/lib/ds-parse.mjs

@@ -0,0 +1,124 @@
+// ds-parse.mjs — 设计系统文档解析（公共模块，v0.54.0）
+//
+// 供 design-token-guard.mjs / gen-primer.mjs 复用（避免多份重复解析）。
+// 纯函数，无副作用。
+
+// 组件契约表分组规则（§4.1.1）：类型 → states 下限（null = 豁免）
+export const COMPONENT_TYPE_MIN_STATES = { '交互': 3, '轻量': 2, '豁免': null };
+
+// 组件数三档（§4.1.1）
+export const COMPONENT_COUNT_PASS = 15;
+export const COMPONENT_COUNT_WARN = 10;
+
+// Collect the lower-cased text of every level-2 ("## ") markdown header.
+export function extractH2Headers(markdown) {
+  return markdown
+    .split('\n')
+    .filter(line => /^##\s+/.test(line) && !/^###/.test(line))
+    .map(line => line.replace(/^##\s+/, '').trim().toLowerCase());
+}
+
+// True when any ## header mentions the given section name.
+export function hasSection(headers, section) {
+  return headers.some(header => header.includes(section));
+}
+
+// Return the raw (case-preserving) body of a section (text between its ##
+// header and the next ## header or EOF); null when the section is absent.
+export function sectionBodyRaw(markdown, section) {
+  const lines = markdown.split('\n');
+  const startIdx = lines.findIndex(
+    line => /^##\s+/.test(line) && !/^###/.test(line) &&
+      line.replace(/^##\s+/, '').trim().toLowerCase().includes(section),
+  );
+  if (startIdx === -1) return null;
+  const body = [];
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i]) && !/^###/.test(lines[i])) break;
+    body.push(lines[i]);
+  }
+  return body.join('\n');
+}
+
+// Lower-cased section body.
+export function sectionBody(markdown, section) {
+  const raw = sectionBodyRaw(markdown, section);
+  return raw === null ? null : raw.toLowerCase();
+}
+
+// Parse a markdown table row into trimmed cells; null when not a data row.
+export function parseTableRow(line) {
+  if (!/^\s*\|/.test(line)) return null;
+  const cells = line.split('|').slice(1, -1).map(c => c.trim());
+  if (cells.length === 0) return null;
+  if (cells.every(c => /^:?-{2,}:?$/.test(c))) return null;
+  return cells;
+}
+
+// Parse the components contract table (§4.1.1):
+// | 组件 | 类型 | variants | sizes | states | 用途 | 禁止 |
+// Returns { rows: [{name, type, variants, sizes, states, statesCount, hasVariants}] } or null.
+export function parseComponentsTable(markdown) {
+  const body = sectionBodyRaw(markdown, 'components');
+  if (!body) return null;
+  const rows = [];
+  for (const line of body.split('\n')) {
+    const cells = parseTableRow(line);
+    if (!cells || cells.length < 5) continue;
+    const name = cells[0];
+    const type = cells[1];
+    if (/^(组件|component)/i.test(name)) continue;
+    if (!Object.prototype.hasOwnProperty.call(COMPONENT_TYPE_MIN_STATES, type)) continue;
+    const variants = cells[2];
+    const sizes = cells[3];
+    const states = cells[4];
+    const stateItems = states
+      .split('/')
+      .map(s => s.trim())
+      .filter(s => s && s !== '—' && s !== '-')
+      .filter(s => !/¹/.test(s));
+    rows.push({
+      name,
+      type,
+      variants,
+      sizes,
+      states,
+      hasVariants: Boolean(variants && variants !== '—' && variants !== '-'),
+      statesCount: stateItems.length,
+    });
+  }
+  return rows.length > 0 ? { rows } : null;
+}
+
+// Parse governance section for the `contract` marker (§4.1.3).
+// Returns 'v1' | 'legacy' | null.
+export function parseContract(markdown) {
+  const body = sectionBodyRaw(markdown, 'governance');
+  if (!body) return null;
+  const m = body.match(/contract\s*[:：]\s*(v1|legacy)/i);
+  return m ? m[1].toLowerCase() : null;
+}
+
+// Parse the A1 identity token block from a token/spec section (for primer 速查).
+// Looks for `--token: value` pairs anywhere in the markdown.
+export function parseA1Tokens(markdown) {
+  const names = ['--bg', '--surface', '--fg', '--muted', '--border', '--accent', '--font-display', '--font-body'];
+  const out = {};
+  for (const name of names) {
+    const re = new RegExp(`${name.replace(/-/g, '\\-')}\\s*[:：]\\s*([^;\\n]+)`, 'i');
+    const m = markdown.match(re);
+    if (m) out[name] = m[1].trim().replace(/\s+$/, '');
+  }
+  return out;
+}
+
+// Extract the anti-patterns section as a list of bullet/numbered items.
+export function parseAntiPatterns(markdown) {
+  const body = sectionBodyRaw(markdown, 'anti-patterns');
+  if (!body) return [];
+  return body
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => /^([-*]|\d+[.、)])\s+\S/.test(l))
+    .map(l => l.replace(/^([-*]|\d+[.、)])\s+/, ''));
+}

package/scripts/token-extract.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+// token-extract.mjs — 逆向建库的确定性证据提取器（v0.54.0，设计 §4.1.6 降级版）
+//
+// 从既有代码目录提取设计 token 证据：8 组正则证据机 → source-tokens.json + 统计报告。
+// **零 LLM、零语义推断**——只给"频次 + 位置分布"证据，语义角色（谁是 primary）由人工策展指定。
+//
+// Usage:
+//   node scripts/token-extract.mjs <代码目录> [--out <source-tokens.json 路径>] [--budget-ms 60000]
+//   node scripts/token-extract.mjs <代码目录> --report     # 只输出统计报告
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, dirname, extname, relative } from 'node:path';
+
+// ── 配置 ──
+
+const SCAN_EXTS = new Set(['.css', '.scss', '.less', '.html', '.htm', '.js', '.jsx', '.ts', '.tsx', '.vue', '.svelte', '.json']);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.cache', 'vendor', '__pycache__', '.turbo', 'out', 'target']);
+const MAX_FILE_SIZE = 512 * 1024;   // 512 KiB——超过只登记不扫描
+const DEFAULT_BUDGET_MS = 60_000;
+
+// ── 证据机（8 组正则，借鉴 open-design token-evidence）──
+
+const EVIDENCE = [
+  { kind: 'color', re: /#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3}\b/g },
+  { kind: 'color', re: /rgba?\(\s*\d+\s*,\s*\d+\s*,\s*\d+[^)]*\)/g },
+  { kind: 'color', re: /hsla?\(\s*[\d.]+\s*,\s*[\d.]+%\s*,\s*[\d.]+%[^)]*\)/g },
+  { kind: 'custom-prop', re: /--[a-zA-Z][\w-]*\s*:\s*([^;{}]+)[;}]/g, captureValue: true, nameCapture: /(--[a-zA-Z][\w-]*)/ },
+  { kind: 'font', re: /font-family\s*:\s*([^;{}]+)[;}]/gi, captureValue: true },
+  { kind: 'spacing', re: /(?:padding|margin|gap|inset|top|right|bottom|left)\s*:\s*([^;{}]+)[;}]/gi, captureValue: true },
+  { kind: 'radius', re: /border(?:-[a-z]+)?-radius\s*:\s*([^;{}]+)[;}]/gi, captureValue: true },
+  { kind: 'shadow', re: /box-shadow\s*:\s*([^;{}]+)[;}]/gi, captureValue: true },
+  { kind: 'tailwind', re: /\b(?:bg|text|border|from|to|via|ring)-(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(?:50|100|200|300|400|500|600|700|800|900|950)\b/g },
+];
+
+// ── 参数 ──
+
+const argv = process.argv.slice(2);
+const REPORT_ONLY = argv.includes('--report');
+const outIdx = argv.indexOf('--out');
+const outArg = outIdx !== -1 ? argv[outIdx + 1] : null;
+const budgetIdx = argv.indexOf('--budget-ms');
+const budgetMs = budgetIdx !== -1 ? Number(argv[budgetIdx + 1]) || DEFAULT_BUDGET_MS : DEFAULT_BUDGET_MS;
+const positional = argv.filter((a, i) => !a.startsWith('--') && !(outIdx !== -1 && i === outIdx + 1) && !(budgetIdx !== -1 && i === budgetIdx + 1));
+const rootArg = positional[0];
+
+if (!rootArg) {
+  console.error('Usage: node scripts/token-extract.mjs <代码目录> [--out <json 路径>] [--budget-ms 60000] [--report]');
+  process.exit(1);
+}
+const root = resolve(rootArg);
+if (!existsSync(root) || !statSync(root).isDirectory()) {
+  console.error(`目录不存在或不可读：${root}`);
+  process.exit(1);
+}
+
+// ── 走树（迭代式，预算控制）──
+
+const started = Date.now();
+const files = [];
+const skipped = [];
+const queue = [root];
+while (queue.length > 0) {
+  if (Date.now() - started > budgetMs) {
+    skipped.push({ reason: 'budget-exceeded', remaining: queue.length });
+    break;
+  }
+  const dir = queue.shift();
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { skipped.push({ path: dir, reason: 'unreadable' }); continue; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isSymbolicLink()) { skipped.push({ path: full, reason: 'symlink' }); continue; }
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) { skipped.push({ path: full, reason: 'directory-skiplist' }); continue; }
+      queue.push(full);
+      continue;
+    }
+    if (!SCAN_EXTS.has(extname(e.name).toLowerCase())) continue;
+    let size = 0;
+    try { size = statSync(full).size; } catch { continue; }
+    if (size > MAX_FILE_SIZE) { skipped.push({ path: full, reason: 'large-file', size }); continue; }
+    files.push(full);
+  }
+}
+
+// ── 证据采集 ──
+
+const evidence = new Map();   // key: `${kind}:${normalizedValue}` → { kind, value, count, sources[], usage:Set }
+
+function record(kind, value, file, line) {
+  const v = String(value).trim().replace(/\s+/g, ' ');
+  if (!v || v.length > 120) return;
+  const key = `${kind}:${v.toLowerCase()}`;
+  let e = evidence.get(key);
+  if (!e) { e = { kind, value: v, count: 0, sources: [], usage: new Set() }; evidence.set(key, e); }
+  e.count += 1;
+  if (e.sources.length < 20) e.sources.push(`${relative(root, file)}:${line}`);
+  e.usage.add(relative(root, file));
+}
+
+let scanned = 0;
+for (const file of files) {
+  if (Date.now() - started > budgetMs) { skipped.push({ reason: 'budget-exceeded-during-scan' }); break; }
+  let content;
+  try { content = readFileSync(file, 'utf-8'); } catch { continue; }
+  scanned += 1;
+  const lines = content.split('\n');
+  // 逐行扫（拿行号）
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const ev of EVIDENCE) {
+      ev.re.lastIndex = 0;
+      let m;
+      while ((m = ev.re.exec(line)) !== null) {
+        if (ev.captureValue) {
+          const raw = m[1] !== undefined ? m[1] : m[0];
+          // 多值（如 padding: 8px 16px）拆开逐项
+          for (const part of raw.split(/[\s,]+/)) {
+            const t = part.trim();
+            if (!t || t === '0' || t === 'auto' || t === 'inherit' || t === 'initial') continue;
+            if (ev.kind === 'custom-prop') {
+              const nameM = line.match(ev.nameCapture);
+              record(ev.kind, `${nameM ? nameM[1] : '--?'}=${t}`, file, i + 1);
+            } else {
+              record(ev.kind, t, file, i + 1);
+            }
+          }
+        } else {
+          record(ev.kind, m[0], file, i + 1);
+        }
+        if (m.index === ev.re.lastIndex) ev.re.lastIndex += 1;   // 防零宽死循环
+      }
+    }
+  }
+}
+
+// ── 值归一化 + 相似聚类（确定性）──
+
+function normalizeHex(v) {
+  const m = v.match(/^#([0-9a-fA-F]{3})$/);
+  if (m) return '#' + m[1].split('').map(c => c + c).join('').toLowerCase();
+  const m6 = v.match(/^#([0-9a-fA-F]{6})$/);
+  if (m6) return '#' + m6[1].toLowerCase();
+  return v.toLowerCase();
+}
+
+function hexToRgb(hex) {
+  const h = normalizeHex(hex).replace('#', '');
+  if (h.length !== 6) return null;
+  return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+
+// 距离近似（RGB 欧氏；ΔE≈2 量级约为 RGB 距离 ~12）
+function rgbDistance(a, b) {
+  return Math.sqrt((a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2);
+}
+
+function cluster(list, isSimilar) {
+  const sorted = [...list].sort((x, y) => y.count - x.count);
+  const clusters = [];
+  for (const item of sorted) {
+    const target = clusters.find(c => isSimilar(c.representative, item));
+    if (target) {
+      target.members.push(item);
+      target.count += item.count;
+      for (const s of item.sources) if (target.sources.length < 20) target.sources.push(s);
+      for (const u of item.usage) target.usage.add(u);
+    } else {
+      clusters.push({ representative: item, members: [item], count: item.count, sources: [...item.sources], usage: new Set(item.usage) });
+    }
+  }
+  return clusters;
+}
+
+const allTokens = [...evidence.values()];
+
+// 颜色：hex 归并（ΔE<2 ≈ RGB 距离 <12）
+const colorTokens = allTokens.filter(t => t.kind === 'color' && hexToRgb(t.value));
+const nonHexColors = allTokens.filter(t => t.kind === 'color' && !hexToRgb(t.value));
+const colorClusters = cluster(colorTokens, (a, b) => {
+  const ra = hexToRgb(a.value), rb = hexToRgb(b.value);
+  return ra && rb && rgbDistance(ra, rb) < 12;
+});
+
+// 尺寸类：±1px 归并
+const sizeKinds = ['spacing', 'radius'];
+const sizeClusters = {};
+for (const kind of sizeKinds) {
+  const items = allTokens.filter(t => t.kind === kind);
+  sizeClusters[kind] = cluster(items, (a, b) => {
+    const na = parseFloat(a.value), nb = parseFloat(b.value);
+    if (!Number.isFinite(na) || !Number.isFinite(nb)) return a.value === b.value;
+    const ua = a.value.replace(/[\d.\s-]/g, ''), ub = b.value.replace(/[\d.\s-]/g, '');
+    return ua === ub && Math.abs(na - nb) <= 1;
+  });
+}
+
+const passthrough = ['font', 'shadow', 'custom-prop', 'tailwind'];
+const passthroughTokens = {};
+for (const kind of passthrough) {
+  passthroughTokens[kind] = allTokens.filter(t => t.kind === kind).sort((a, b) => b.count - a.count);
+}
+
+// ── 输出 ──
+
+const sourceTokens = {
+  scan: { root, filesDiscovered: files.length, filesScanned: scanned, generatedAt: new Date().toISOString(), budgetMs },
+  tokens: {
+    color: colorClusters.map(c => ({
+      value: c.representative.value,
+      count: c.count,
+      mergedFrom: c.members.length > 1 ? c.members.map(m => m.value) : undefined,
+      sources: c.sources,
+      usage: [...c.usage].slice(0, 20),
+    })),
+    colorRaw: nonHexColors.sort((a, b) => b.count - a.count).map(t => ({ value: t.value, count: t.count, sources: t.sources })),
+    spacing: sizeClusters.spacing.map(c => ({ value: c.representative.value, count: c.count, sources: c.sources })),
+    radius: sizeClusters.radius.map(c => ({ value: c.representative.value, count: c.count, sources: c.sources })),
+    ...Object.fromEntries(passthrough.map(k => [k, passthroughTokens[k].map(t => ({ name: t.value, count: t.count, sources: t.sources.slice(0, 5) }))])),
+  },
+  skipped,
+};
+
+const colorCount = sourceTokens.tokens.color.length;
+const spacingCount = sourceTokens.tokens.spacing.length;
+const radiusCount = sourceTokens.tokens.radius.length;
+const fontCount = sourceTokens.tokens.font.length;
+
+// 统计报告（stdout）
+const report = [];
+report.push('=== Token 提取报告（确定性，零 LLM）===');
+report.push(`根目录：${root}`);
+report.push(`发现文件：${files.length} | 已扫描：${scanned}${skipped.length ? ` | 跳过：${skipped.length}` : ''}`);
+report.push('');
+report.push(`颜色：${colorCount} 个聚类（归并 ${colorTokens.length - colorCount} 个近似值）`);
+for (const c of sourceTokens.tokens.color.slice(0, 8)) {
+  report.push(`  ${c.value.padEnd(10)} ×${String(c.count).padStart(4)}${c.mergedFrom ? `  (含 ${c.mergedFrom.length - 1} 个近似写法)` : ''}`);
+}
+report.push('');
+report.push(`间距：${spacingCount} 个聚类 | 圆角：${radiusCount} 个 | 字体栈：${fontCount} 个`);
+for (const c of sourceTokens.tokens.spacing.slice(0, 5)) report.push(`  spacing ${c.value} ×${c.count}`);
+for (const c of sourceTokens.tokens.radius.slice(0, 4)) report.push(`  radius  ${c.value} ×${c.count}`);
+report.push('');
+report.push('⚠️ 以上仅为「频次 + 位置」证据——语义角色（哪个是 primary / border / font-display）**需要人工策展指定**，');
+report.push('   本工具不做自动推断（设计 §4.1.6：避免"垃圾设计系统 + 满分审计"）。');
+report.push('');
+report.push('下一步：将本报告与 source-tokens.json 呈交用户，由用户指定主色/中性色/语义色/字体后，');
+report.push('   由 design-system skill 的 create-from-code 流程补齐 A1/A2/B-slot 并落盘。');
+
+console.log(report.join('\n'));
+
+if (!REPORT_ONLY) {
+  const outPath = outArg ? resolve(outArg) : join(root, '.team-flow', 'token-extract', 'source-tokens.json');
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, JSON.stringify(sourceTokens, null, 2), 'utf-8');
+  console.log(`\nsource-tokens.json 已写入：${outPath}`);
+}

package/skills/design-system/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: design-system
 description: >-
-  设计系统独立创建与维护 skill。通过用户主导的交互流程（LLM 推荐+用户确认）创建
-  项目级 design-system（base 品牌共享层 + B端/C端变体），产出确定性 token 体系 +
-  预览画廊。支持独立调用或 prototype skill 内部编排调用。当用户需要创建设计系统、
-  迭代设计系统、或原型流程发现设计系统缺失时使用。
+  设计系统独立创建与维护 skill，产出落 .team-flow/design-system/（base 品牌共享层 +
+  B端/C端变体 + primer + 预览画廊）。三条创建入口：交互式（LLM 推荐+用户确认）、
+  从内置模板库导入（registry.json 8 个参考）、从既有代码逆向建库（create-from-code）。
+  支持独立调用或 prototype skill 内部编排调用。当用户需要创建设计系统、迭代设计系统、
+  刷新 primer 组件白名单、或原型流程发现设计系统缺失时使用。
   不适用于：原型绘制（用 prototype）、纯架构设计（用 architecture-design）。
 ---
 
@@ -23,6 +24,19 @@ Do NOT invoke for:
 
 ## 交互创建流程（6 步）
 
+### Step 0: 起点选择（v0.54.0）
+
+若 `.team-flow/design-system/` 不存在（无设计系统），先询问起点：
+
+- **从模板库选择**：展示 `${CLAUDE_PLUGIN_ROOT}/templates/design-systems/registry.json`（8 个参考：linear-app / stripe / vercel / supabase / sentry / posthog / notion / claude）→ 用户选定后运行 `node ${CLAUDE_PLUGIN_ROOT}/scripts/design-system-import.mjs <reference.md> --out .team-flow/design-system/base.md` 转换 → **续跑 Step 5 评审 → Step 6 落盘**（落盘动作含 primer 生成 + guard 校验；primer 缺失会让 prototype Step 0 对 `contract: v1` 系统 blocked）
+- **逆向建库**：走 **create-from-code** 模式（见下方「逆向建库模式」）——从既有代码提取
+- **从零创建**：直接进 Step 1（交互式 6 步）
+- **已有设计系统** → 走 iterate 模式
+
+> B 类参考（如 linear-app）转换为**自动提取配色**，须提示用户人工核对（转换器会输出该警告）。
+
+> **风格种子（styles.json）**：`${CLAUDE_PLUGIN_ROOT}/templates/design-systems/styles.json` 提供 57 个风格型设计系统的配色/字体元数据（如"想要 X 风格"）——Step 1 需求收集时可作为 mood/品牌主色的参考依据，用户选定后以 `brand_color` 传入（不扩充 5 维封闭词汇，保持核心交互稳定）。
+
 ### Step 1: 需求收集（≤5 个预填推荐问题）
 用 AskUserQuestion 收集 5 个维度（预填 LLM 推荐值，用户原样确认或调整）：
 1. 品牌调性（封闭词汇：professional_minimal / warm_approachable / technical_dense / editorial / brutalist）
@@ -42,23 +56,55 @@ Do NOT invoke for:
 ### Step 4: 预览生成
 生成 `preview.html`（自包含 HTML 画廊：色板+排版+间距+组件+明暗切换）。用 `references/preview-template.html` 模板填充 token 值。
 
+### Step 4.5: Design Showcase（可选，v0.54.0）
+询问用户是否产出**基准原型**（判断设计系统实际效果）：派 `prototype-builder`（`mode: showcase`）用内置车企 brief（`references/showcase-board-{b,c}-end.md`，按 target）产出 1-3 页 Board 到 scratch。产出前明示预估耗时；可跳过。详见 `references/creation-flow.md` Step 4.5。
+
 ### Step 5: 用户评审 + 确认
-呈现：token 摘要表 + 预览路径 + 默认值透明报告。AskUserQuestion：确认 / 调整 / 重新来。
+呈现：token 摘要表 + 预览路径 + **showcase 路径（如产出）** + 默认值透明报告。AskUserQuestion：确认 / 调整 / 重新来。
 
 ### Step 6: 落盘 + guard 校验
-写入 `.team-flow/design-system/`，运行 `scripts/guard/design-token-guard.mjs` 校验。
+写入 `.team-flow/design-system/`（base + 变体 + **primer**（`${CLAUDE_PLUGIN_ROOT}/scripts/gen-primer.mjs`）+ preview + **showcase 从 scratch 复制**），运行 `node ${CLAUDE_PLUGIN_ROOT}/scripts/guard/design-token-guard.mjs <设计系统目录>`（v0.54.0：硬校验 + 六层审计；传目录会自动合并 base + 端变体再断言 9 段——base 品牌层本身不含 typography/spacing/layout/motion）。**target=both 时按端各跑一次**（`--variant b-end` / `--variant c-end`）——合并断言掩盖单端残缺。
 
 ## 存储位置
 ```
 .team-flow/design-system/
-├── base.md          # 品牌共享层
-├── b-end.md         # B 端变体（可选）
+├── base.md          # 品牌共享层（含组件契约表/principles/governance）
+├── b-end.md         # B 端变体（可选，components 段只写端特有差异）
 ├── c-end.md         # C 端变体（可选）
-└── preview.html     # token 预览画廊
+├── primer.md        # AI 约束入口（scripts/gen-primer.mjs 生成，含 digest）
+├── preview.html     # token 预览画廊
+├── showcase/        # 展示板（v0.54.0，可选：b-end.html / c-end-*.html）
+├── variants/        # 主题变体（如 dark.md）
+└── pending.md       # 增量待办（v0.54.0，单写者 = 本 skill）
 ```
 
+## pending.md（设计系统待办，v0.54.0）
+
+原型阶段用户"暂不处理"的增量暂存（`ds_increment` 的落点）。
+- **单写者 = design-system skill**——本 skill 的 iterate 流程负责增删；主代理与 release-archivist **只读**
+- 条目格式：`{描述} | 来源: <change-id 或 s2-prototype> | 时间: <ISO>`
+- **清理规则**：用户确认 → iterate 落盘时移除该条；用户拒绝 → 直接删除（重复发现就重复问）；用户自行解决 → 下次 iterate 按同义条目清理
+- iterate 时检查 pending.md：有待办则提示用户"是否一并处理"
+
 ## 迭代模式（iterate）
 已有 design-system → 读取 → 合并增量 → 变更履历 → 预览 → 确认 → 写入。
+增量来源：① 原型阶段确认的 `ds_increment`（⑥ 路由）② **pending.md 累积待办** ③ change closing 二级确认项。
+落盘后重新生成 primer（`${CLAUDE_PLUGIN_ROOT}/scripts/gen-primer.mjs`）+ 跑 guard；涉及 token/契约变更时**可选**重新生成 showcase（用户可跳过）。
+
+## 逆向建库模式（create-from-code，v0.54.0）
+
+**场景**：企业已有符合规范的原型代码 → 基于它建立设计系统。**确定性提取 + 人工策展**（不做自动语义推断——避免"垃圾设计系统 + 满分审计"）。
+
+**入口**：`/team-flow:design-system create-from-code --source <代码目录>`（多仓库可传多值或指向 repo_layout 清单）
+
+**流程（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 合并（需用户确认）。
 
 ## 迁移兼容
 检测旧 `prototype/design-system.md` → 提示迁移到 `.team-flow/design-system/base.md`（一次性）。

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

@@ -1,5 +1,3 @@
-**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`.
 
 ### 文件结构：base + variant
@@ -33,15 +31,49 @@ 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；存量升级时由 iterate 置 v1）+ version + 负责人 + 弃用策略 + changelog |
 | `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 +83,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,8 +97,11 @@ 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）**：`contract: v1`（新建固定 v1）+ version + 负责人 + 弃用策略 + changelog。
+   - **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 = 正式路径。
@@ -84,7 +119,9 @@ When the project has no `.team-flow/design-system/base.md`:
 When prototype-sync (or a change) introduces new components / tokens / anti-patterns:
 
 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`.
+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. 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，**不写正式路径**。
@@ -98,7 +135,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)