figma-cache-toolchain 2.0.2 → 2.0.4

package/cursor-bootstrap/examples/ui-execution-template.strict.md

@@ -0,0 +1,13 @@
+# UI 执行模板（strict）
+
+适用：主干发布、关键路径页面、高保真验收。
+
+1. `npm run figma:ui:preflight`
+2. `npm run figma:ui:audit -- --target=<component-path> --min-score=92`
+3. `npm run figma:ui:report:aggregate`
+4. `npm run figma:ui:gate:main`
+
+建议：
+- `FIGMA_UI_PROFILE=strict`
+- preflight warning 视为阻断
+- audit 必须提供 `--target`

package/cursor-bootstrap/examples/ui-override.template.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "scope": "node",
+  "description": "Node-level override for exceptional visual/interaction differences.",
+  "tokenMappings": [
+    {
+      "id": "node.token.override.example",
+      "figmaToken": "Example/Primary",
+      "figmaValue": "#305AFE",
+      "required": false,
+      "projectBinding": {
+        "type": "literal",
+        "value": "#305AFE",
+        "notes": "Only use when this node truly differs from global contract."
+      }
+    }
+  ],
+  "stateMappings": {
+    "select": {
+      "requiredStates": ["default", "expanded", "selected", "unselected"]
+    }
+  },
+  "layoutRules": [],
+  "typographyRules": [],
+  "interactionRules": []
+}

package/cursor-bootstrap/figma-cache.config.example.js

@@ -1,4 +1,4 @@
-/**
+/**
  * 项目级 Figma 缓存扩展（示例模板，**不绑定任何 UI 框架**）。
  *
  * 安装本 npm 包并执行 `npx figma-cache cursor init` 后，项目根会出现 **AGENT-SETUP-PROMPT.md**：
@@ -6,7 +6,7 @@
  *
  * 若你已有 `figma-cache.config.js`，可由 Agent 合并而非覆盖。
  *
- * 加载顺序见 `figma-cache/figma-cache.js`：FIGMA_CACHE_PROJECT_CONFIG → figma-cache.config.js → .figmacacherc.js
+ * 加载顺序见 `figma-cache/figma-cache.js`：FIGMA_CACHE_PROJECT_CONFIG -> figma-cache.config.js -> .figmacacherc.js
  */
 
 const fs = require("fs");
@@ -45,6 +45,21 @@ const ADAPTER_DOC_CACHE_REL =
 const ADAPTER_DOC_WRITE_POLICY =
   process.env.FIGMA_CACHE_ADAPTER_DOC_WRITE_POLICY || "if-missing";
 
+/**
+ * 全局 UI adapter contract 目标路径（相对项目根）。
+ * 该 contract 作为「设计 token/state -> 项目实现」的单一真源。
+ */
+const ADAPTER_CONTRACT_REL =
+  process.env.FIGMA_CACHE_ADAPTER_CONTRACT ||
+  "figma-cache/adapters/ui-adapter.contract.json";
+
+/**
+ * contract 模板来源（相对项目根，通常来自 cursor-bootstrap）。
+ */
+const ADAPTER_CONTRACT_TEMPLATE_REL =
+  process.env.FIGMA_CACHE_ADAPTER_CONTRACT_TEMPLATE ||
+  "cursor-bootstrap/examples/ui-adapter.contract.template.json";
+
 /**
  * 人类可读的「流程 / 需求总览」骨架路径（相对项目根）。仅本示例写入；可在业务项目中改路径或删除相关逻辑。
  * @type {string}
@@ -99,13 +114,14 @@ function writeTextByPolicy(absPath, content) {
  * @returns {string}
  */
 function buildCacheRootHint(ctx) {
-  return `# Figma 缓存 → UI 实现（目录级提示）
+  return `# Figma 缓存 -> UI 实现（目录级提示）
 
 本文件由示例 \`postEnsure\` 生成，默认放在 **figma-cache 目录级**，用于避免“每个节点重复生成同一提示”。
 
 - **默认来源优先级**：先用 \`raw.json\` / \`spec.md\` / \`meta.json\` / \`state-map.md\`，仅在缺口或冲突时再读 \`mcp-raw/*\`
 - **证据约束**：同一设计事实只保留一个主证据来源，避免重复引用
 - **命中检查**：先查本地缓存命中与字段覆盖，再决定是否需要 MCP 补齐
+- **全局映射契约**：先读取 \`${ADAPTER_CONTRACT_REL}\`，将 token/state 映射到项目实现；未映射项禁止猜测
 
 可选模式（环境变量）：
 - \`FIGMA_CACHE_ADAPTER_DOC_MODE=cache-root\`（默认）
@@ -122,7 +138,7 @@ function buildCacheRootHint(ctx) {
  */
 function buildNodeHint(ctx) {
   const nodeLabel = ctx.nodeId == null ? "" : String(ctx.nodeId);
-  return `# Figma 缓存 → UI 实现（节点提示）
+  return `# Figma 缓存 -> UI 实现（节点提示）
 
 本文件由示例 \`postEnsure\` 生成。若你希望减少重复，可改用目录级模式：\`FIGMA_CACHE_ADAPTER_DOC_MODE=cache-root\`。
 
@@ -130,6 +146,7 @@ function buildNodeHint(ctx) {
 - cacheKey: \`${ctx.cacheKey}\`
 - fileKey: \`${ctx.fileKey}\`
 - nodeId: \`${nodeLabel}\`
+- 全局映射契约：\`${ADAPTER_CONTRACT_REL}\`
 
 **流程 / 交互总览（可选）**：若使用本示例默认钩子，项目根下另有 **\`${FLOW_README_REL}\`**，随每次 \`ensure\` 追加节点小节，便于与 \`index.json\` 里的 \`flows\` 互补（人读 md，机读索引）。
 `;
@@ -155,6 +172,26 @@ function writeAdapterHint(ctx) {
   writeTextByPolicy(cacheRootTarget, buildCacheRootHint(ctx));
 }
 
+/**
+ * 保证项目存在全局 adapter contract（单一真源）。
+ * 默认仅在缺失时写入，避免覆盖项目已定制内容。
+ * @param {object} ctx
+ */
+function ensureAdapterContract(ctx) {
+  const targetAbs = path.resolve(ctx.root, ADAPTER_CONTRACT_REL);
+  if (fs.existsSync(targetAbs)) {
+    return;
+  }
+
+  const templateAbs = path.resolve(ctx.root, ADAPTER_CONTRACT_TEMPLATE_REL);
+  if (!fs.existsSync(templateAbs)) {
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(targetAbs), { recursive: true });
+  fs.copyFileSync(templateAbs, targetAbs);
+}
+
 /**
  * 在单文件里维护「已缓存节点」登记（按 cacheKey 幂等追加），与 index.json / flows 互补：适合评审与新人阅读。
  * @param {object} ctx
@@ -164,13 +201,13 @@ function appendFlowReadmeRegistry(ctx) {
   const marker = `<!-- cache-node:${ctx.cacheKey} -->`;
   const specRel = normalizePosixPath(path.relative(ctx.root, path.resolve(ctx.root, ctx.paths.spec)));
   const metaRel = normalizePosixPath(path.relative(ctx.root, path.resolve(ctx.root, ctx.paths.meta)));
-  const completeness = Array.isArray(ctx.completeness) && ctx.completeness.length ? ctx.completeness.join(", ") : "—";
+  const completeness = Array.isArray(ctx.completeness) && ctx.completeness.length ? ctx.completeness.join(", ") : "-";
   const block =
     `\n${marker}\n` +
     `### \`${ctx.cacheKey}\`\n\n` +
-    `- **Figma**: ${ctx.url || "—"}\n` +
-    `- **syncedAt**: ${ctx.syncedAt || "—"}\n` +
-    `- **source**: ${ctx.source || "—"}\n` +
+    `- **Figma**: ${ctx.url || "-"}\n` +
+    `- **syncedAt**: ${ctx.syncedAt || "-"}\n` +
+    `- **source**: ${ctx.source || "-"}\n` +
     `- **completeness**: ${completeness}\n` +
     `- **spec**: \`${specRel}\` · **meta**: \`${metaRel}\`\n` +
     `- **提示**: 像素级还原以 \`spec.md\` / \`raw.json\` 为准；用户路径请维护 \`flows\` 后把 \`npm run figma:cache:flow mermaid\` 输出贴到下方「流程总览」。\n`;
@@ -219,16 +256,21 @@ module.exports = {
   ADAPTER_DOC_MODE,
   ADAPTER_DOC_CACHE_REL,
   ADAPTER_DOC_WRITE_POLICY,
+  ADAPTER_CONTRACT_REL,
+  ADAPTER_CONTRACT_TEMPLATE_REL,
   FLOW_README_REL,
   appendFlowReadmeRegistry,
+  ensureAdapterContract,
 
   hooks: {
     /**
-     * 默认实现：目录级 adapter 提示（避免节点重复）+ 项目根下「流程/需求」总览骨架（单文件、幂等追加节点块）。
+     * 默认实现：目录级 adapter 提示（避免节点重复）+ 全局 adapter contract（缺失时自动落地）
+     * + 项目根下「流程/需求」总览骨架（单文件、幂等追加节点块）。
      * 用 Agent 生成业务方案后，可整体替换本模块逻辑。
      */
     postEnsure(ctx) {
       try {
+        ensureAdapterContract(ctx);
         writeAdapterHint(ctx);
         appendFlowReadmeRegistry(ctx);
       } catch (err) {

package/cursor-bootstrap/managed-files.json

@@ -0,0 +1,41 @@
+{
+  "managedFiles": [
+    {
+      "from": "rules/00-output-token-budget.mdc",
+      "to": ".cursor/rules/00-output-token-budget.mdc"
+    },
+    {
+      "from": "rules/01-figma-cache-core.mdc",
+      "to": ".cursor/rules/01-figma-cache-core.mdc"
+    },
+    {
+      "from": "rules/02-figma-stack-adapter.mdc",
+      "to": ".cursor/rules/02-figma-stack-adapter.mdc"
+    },
+    {
+      "from": "rules/03-figma-ui-implementation-hard-constraints.mdc",
+      "to": ".cursor/rules/03-figma-ui-implementation-hard-constraints.mdc"
+    },
+    {
+      "from": "rules/04-ui-baseline-governance.mdc",
+      "to": ".cursor/rules/04-ui-baseline-governance.mdc"
+    },
+    {
+      "from": "rules/figma-local-cache-first.mdc",
+      "to": ".cursor/rules/figma-local-cache-first.mdc"
+    },
+    {
+      "from": "skills/figma-mcp-local-cache/SKILL.md",
+      "to": ".cursor/skills/figma-mcp-local-cache/SKILL.md"
+    },
+    {
+      "from": "skills/figma-ui-dual-mode-execution/SKILL.md",
+      "to": ".cursor/skills/figma-ui-dual-mode-execution/SKILL.md"
+    }
+  ],
+  "retiredFiles": [
+    ".cursor/skills/ui-baseline-governance/SKILL.md",
+    ".cursor/rules/04-command-execution-anti-regression.mdc",
+    ".cursor/rules/commit-conventions.mdc"
+  ]
+}

package/cursor-bootstrap/rules/02-figma-stack-adapter.mdc

@@ -1,32 +1,22 @@
----
-description: 栈占位：由 Agent 按项目 UI 技术栈生成 02-figma-<stack>-adapter.mdc 后再实现业务 UI（本文件可删除或 alwaysApply 保持 false）
+---
+description: 栈占位模板（仅生成期使用）：生成完成后删除本文件与 AGENT-SETUP-PROMPT.md
 alwaysApply: false
 ---
 
-# Figma → UI Stack Adapter（占位）
-
-本文件是 **通用脚手架**，不绑定 Vue / React / 任何组件库。若你已有具体栈的 Adapter 规则（例如 `02-figma-vuetify2-adapter.mdc`、`02-figma-react-mui-adapter.mdc`），可将本文件删除，或在 Cursor 设置中不再引用本文件。
-
-## 第一步：用 Agent 生成栈专属规则
-
-在项目根执行 `npx figma-cache cursor init` 后，打开 **`AGENT-SETUP-PROMPT.md`**，在 Cursor 里 **`@AGENT-SETUP-PROMPT.md`** 或整篇粘贴给 Agent，让其按文档顺序执行（含推断栈、生成配置、删除本占位文件）。若你更习惯手写，也可自行新建 `02-figma-<栈>-adapter.mdc` 与 `figma-cache.config.js`，再删除本文件。
-
-生成后，**01-figma-cache-core** 仍只负责缓存与校验；**表现层**仅由你的 `02-figma-*-adapter` 约束。
-
-## 与 01 的固定边界
-
-- **单一事实来源**：实现 UI 时只从 `raw.json`、`spec.md`、`state-map.md`、`meta.json` 取数；不在这些通用文件里写入框架专有代码或路由名。
-- **仅当任务包含「写/改业务 UI」且缓存可读**时，才应用具体栈的 Adapter；纯缓存维护、只跑 CLI，不触发表现层规则。
-
-## React 直复用（选用规则）
+# Figma -> UI Stack Adapter（占位模板）
 
-仅当 Agent 识别目标项目为 **React 栈**（如 React + Tailwind / React + CSS Modules / React + styled-system）时启用：
+本文件仅用于生成阶段引导，非长期规则。
 
-- 优先复用节点目录下 `mcp-raw-get-design-context.txt` 的 React 参考代码作为起稿。
-- 在此基础上仅做必要微调：项目 token 映射、组件替换、状态/交互逻辑、数据绑定、可访问性与响应式。
-- 若项目非 React 栈，禁止直接复用该 React 代码，应按目标栈 Adapter 规则转换实现。
-- 复用时优先保持结构与视觉一致性；改动应聚焦“接入项目规范”而非重写布局。
+## 生成流程（强制）
+1. 基于项目栈生成 `.cursor/rules/02-figma-<stack>-adapter.mdc`。
+2. 验证新 adapter 可用（语法 + 最小执行验证）。
+3. 删除临时模板文件：
+   - `.cursor/rules/02-figma-stack-adapter.mdc`
+   - `AGENT-SETUP-PROMPT.md`
 
-## 参考实现（非默认）
+## 边界
+- `01-figma-cache-core` 仅负责缓存与校验。
+- 业务 UI 实现约束由新生成的 `02-figma-<stack>-adapter.mdc` + `03/04` 规则承接。
 
-安装本包后，示例路径为 **`node_modules/figma-cache-toolchain/cursor-bootstrap/examples/vue2-vuetify2-adapter.reference.mdc`**（Vue 2 + Vuetify 2 全文参考），需时由 Agent 读入并改写为你的 `.cursor/rules/02-figma-...`。
+## 说明
+- 若用户明确要求保留任务书或占位模板，可不删除，并在汇报中说明原因。

package/cursor-bootstrap/rules/03-figma-ui-implementation-hard-constraints.mdc

@@ -1,91 +1,58 @@
----
-description: Figma 缓存驱动的 UI 实现硬约束（严格 1:1）
-alwaysApply: true
----
-
-# Figma UI 实现硬约束（Hard Mode）
-
-边界：本规则仅约束业务 UI 实现阶段（已具备可读缓存数据后），不负责 MCP 拉取与缓存写入。
-
-## 0. 目标（强制）
-
-- 首版必须 1:1 还原缓存事实。
-- 禁止“贴近”“近似”“经验值补全”。
-- 若信息冲突或不足，先停下澄清，不得猜测实现。
-
-## 1. 首版必读数据源（强制）
-
-实现前必须读取并建立事实对齐清单，缺一不可：
-
-1. `spec.md`
-2. `raw.json`
-3. `state-map.md`
-4. `mcp-raw-get-design-context.txt`（首版强制必读）
-
-补充说明：
-
-- `mcp-raw-manifest.json` 用于确认证据完整性与来源一致性。
-- `mcp-raw-get-variable-defs.txt` 用于 token 变量补充。
-
-## 2. 数据职责与裁决顺序（强制）
-
-- `spec.md`：结构化布局/文案/token 概览。
-- `raw.json`：覆盖度与完整性约束。
-- `state-map.md`：状态与交互映射。
-- `mcp-raw-get-design-context.txt`：首版视觉与结构落地的一手细节依据。
-
-当 `spec.md` / `raw.json` / `state-map.md` 信息抽象、缺失、或相互冲突时：
-
-- 必须回到 `mcp-raw-get-design-context.txt` 裁决。
-- 仍无法裁决时，必须停止实现并向用户确认。
-- 禁止凭经验补齐。
-
-## 3. 视觉 1:1 规则（强制）
-
-- 颜色：必须使用缓存 token 或明确值，禁止近似替换。
-- 文本：字号/字重/行高/字距逐项对齐，禁止“近似 class”替代。
-- 几何：圆角/边框/背景/间距逐项对齐，不做推测。
-- 盒模型：统一 `box-border`（或等效策略）并保持全组件一致。
-- 状态切换不得引发布局占位变化（避免抖动/超宽/变窄）。
-
-## 4. 标签与语义规则（强制）
-
-- 布局与展示优先使用安全标签：`div` / `span` / `p` / `img`。
-- 不禁用功能标签（如 `button` / `input` / `select` / `ul` / `li`），但使用时必须：
-  - 明确其语义必要性，或来自本地封装组件复用。
-  - 完整接管默认样式（基础态 + hover/focus/active/selected）。
-  - 保证视觉结果与设计事实 1:1，不受浏览器默认样式干扰。
-- 禁止“为了方便”滥用功能标签。
-
-## 5. 结构与尺寸一致性（强制）
-
-- 首版必须先确定单一宽度策略（固定值或自适应），同组件内不得混用。
-- 左右对齐策略必须统一；同类块（如双下拉）必须同构实现。
-- 默认禁止横向滚动；非设计明确要求不得出现横向滚动条。
-- 文本溢出必须显式处理（如 `min-w-0` + `truncate`）。
-
-## 6. 状态与交互还原（强制）
-
-- 必须覆盖缓存声明状态：`default / expanded / selected / unselected`（若存在）。
-- 每个状态必须映射背景/边框/文本/图标样式。
-- 交互行为（展开、收起、选择、Esc、outside click）按缓存或用户要求实现。
-- 禁止新增未请求交互；禁止删除已声明交互。
-
-## 7. 执行节奏（强制）
-
-- 每轮只允许改一个维度：结构 / 颜色 / 尺寸 / 交互。
-- 禁止“顺手”捆绑多维改动，除非用户明确要求整包改。
-- 变更后必须做改动文件 lint 校验。
-
-## 8. 失败判定（任一命中即失败）
-
-- 未读取 `mcp-raw-get-design-context.txt` 就开始实现。
-- 使用“近似值”替代缓存明确值。
-- 状态样式未完整覆盖或与缓存定义不一致。
-- 出现横向滚动、尺寸漂移、对齐不一致且无设计依据。
-
-## 9. 失败反馈格式（固定）
-
-1. 失败原因（违反哪条硬约束）
-2. 定位信息（文件 + 样式/结构项）
-3. 修复动作（如何回到 1:1）
+---
+description: Figma 缓存驱动 UI 实现硬约束（统一版：含一次性交付与证据映射）
+alwaysApply: true
+---
+
+# Figma UI 实现硬约束（统一版）
+
+边界：仅约束缓存可读后的业务 UI 实现，不负责 MCP 拉取。
+
+## 0) 压缩级别（先选）
+- L0 严格：高保真/复杂交互/历史漂移（完整对齐 + 全状态 + 强校验）。
+- L1 标准（默认）：精简事实清单 + 核心状态 + lint。
+- L2 快速：仅“先看效果”场景，先静态后补交互。
+
+## 1) 首版必读（强制）
+- `spec.md` / `raw.json` / `state-map.md` / `mcp-raw-get-design-context.txt`
+
+## 2) 裁决顺序（强制）
+- 信息冲突：回到 `mcp-raw-get-design-context.txt`。
+- 仍无法裁决：先问用户，禁止猜测。
+
+## 3) 视觉与布局（强制）
+- 颜色/字体/几何/间距使用明确值，不用近似值。
+- 默认 `box-border`，文本溢出显式处理。
+- 禁止无依据横向滚动与布局抖动。
+
+## 4) 标签与控件（最新口径）
+- 默认优先：`div` / `span` / `img`。
+- 默认禁用：`p` / `ul` / `li` / `ol` / `h1-h6`（除非用户明确要求）。
+- 可直接使用：`input` / `select` / `textarea` / `a`。
+- 原生 `button` 默认禁用；仅封装按钮或 UI 库按钮可用。
+- `role` / `aria-*` 默认不强制。
+
+## 5) 元数据策略
+- `data-node-id` / `data-name` 默认不输出到最终业务代码。
+- 仅在调试映射模式下临时保留。
+
+## 6) 状态与交互（强制）
+- 覆盖缓存声明状态（至少 `default / expanded / selected / unselected`，若存在）。
+- 仅实现缓存声明或用户要求交互，不私增。
+
+## 7) 一次性交付判定（强制）
+- 信息充分（结构/文案/token/状态交互无关键缺口）时：必须一次性完成结构、样式、状态、基础响应式与可访问性，并同轮完成至少一项核心校验。
+- 信息不足时：必须一次性列出“缺失字段 + 影响范围 + 最小补充需求”，并标注“受限还原”。
+
+## 8) 证据映射（强制）
+- 交付说明至少覆盖：布局结构、核心文案、主要颜色/字体 token、状态/交互判断。
+- 每项实现事实必须给一个主来源（`raw.json/spec.md/state-map.md/mcp-raw-get-design-context.txt`）。
+- 若引用 `mcp-raw`，仅用于补缺口/消歧，不重复主来源事实。
+- 若 `raw/spec` 与 `mcp-raw` 冲突，先报告冲突再给采用依据。
+
+## 9) 验收与失败反馈
+- 每轮至少执行改动文件 lint。
+- 声称“1:1 完成”前，至少补一项构建/类型/核心测试。
+- 失败反馈固定三段：
+  1. 失败原因
+  2. 定位信息（文件 + 项）
+  3. 修复动作

package/cursor-bootstrap/rules/04-ui-baseline-governance.mdc

@@ -1,86 +1,35 @@
----
-description: UI 全局基线治理（新项目与老项目双轨），并约束组件生成行为
-alwaysApply: false
----
-
-# UI Baseline Governance（生成约束）
-
-边界：本规则只约束“全局样式基线与组件生成策略”，不替代 `01-figma-cache-core.mdc` 与具体栈 Adapter。
-
-## 0. 目标（强制）
-
-- 在不破坏现有页面的前提下，建立可复用的 UI 默认基线。
-- 将“新项目一次性定标”与“老项目渐进治理”统一到同一执行模型。
-- 将基线策略约束到 Agent 的组件生成行为，降低返工。
-
-## 1. 双轨策略（强制）
-
-### 1.0 项目类型判定（机械启发式，强制先判再改）
-
-> 目的：减少主观判断；**拿不准时一律按老项目**（安全默认）。
-
-在动手改全局样式前，Agent 必须完成一次快速扫描并输出「判定结论 + 命中证据（路径或计数）」。
-
-**老项目（走 §1.2 分层分批）**，满足**任一**即判定为老项目：
-
-- **存量页面信号**：`src/`（无 `src` 则看项目约定的主源码根）下 `*.vue` / `*.tsx` / `*.jsx` 文件数 **≥ 40**。
-- **已有全局 reset / normalize**：入口或样式目录存在或引入命中以下之一（文件名或 import 字符串）：`normalize`、`reset`、`preflight`、`@unocss/reset`、`sanitize`。
-- **已接入成熟 UI 框架**：`package.json` 的 `dependencies` 命中其一：`element-plus`、`ant-design-vue`、`vuetify`、`naive-ui`、`@mui/material`、`@chakra-ui/react` 等。
-- **全局样式覆盖风险**：根样式或全局入口中存在通配选择器（如 `* {`、`html, body` 大包）、或抽样可见大量 `!important` 与深度选择器混用（仅作辅助信号，命中则偏老项目）。
-
-**新项目（可走 §1.1 一次性全局基线）**，需**同时**满足：
-
-- 上述「老项目」四条**均未**命中。
-- 且 `*.vue` / `*.tsx` / `*.jsx` 计数 **< 15**（或主业务目录下可数的页面级组件极少）。
-
-**不确定**：凡计数落在 **15～39** 之间、或仅有弱信号时，**按老项目处理**，仅允许局部基线或单模块试点，禁止首轮全量全局 reset。
-
-### 1.1 新项目（无历史负担）
-
-- 可一次性启用全局基线（推荐）。
-- 首版建议最小集合：
-  - `box-sizing: border-box`（含 `*::before/*::after`）
-  - 常见标签 margin/padding reset
-  - 媒体元素 `display:block` 与 `max-width:100%`
-  - 统一字体基线（family/size/line-height）
-  - 焦点可见策略（`focus-visible`）
-
-### 1.2 老项目（已有线上页面）
-
-- 禁止直接全量覆盖全局 reset。
-- 采用“分层 + 分阶段 + 可回滚”：
-  1. 新增 `baseline layer`（仅声明基线，不改业务样式）。
-  2. 先对“新页面/新组件”生效（范围隔离或入口分批）。
-  3. 用视觉回归与缺陷工单推进存量页迁移。
-  4. 每轮迁移可独立回滚。
-
-## 2. 生成时行为约束（强制）
-
-- 未显式声明前，生成组件默认假设 `border-box`。
-- 在 `flex` 文本容器中必须显式处理溢出：`min-w-0` + `truncate`（或等效策略）。
-- 弹层/下拉必须“锚定触发器”，禁止页面坐标硬定位。
-- 图标优先复用项目图标系统；若缺失，用本地 `inline svg`，禁止运行时依赖 Figma 临时资产 URL。
-- 默认覆盖 `default/hover/focus/active/selected/disabled`（按设计需求裁剪）。
-- 禁止为“临时对齐”引入无意义嵌套；结构必须最小可读。
-
-## 3. 老项目安全闸（强制）
-
-- 当检测到项目未完成 reset 或存在历史样式冲突：
-  - 先输出“风险清单”（组件、影响面、回滚点）再改。
-  - 优先局部基线（页面容器或组件命名空间）而非全局覆盖。
-  - 不得在同一轮同时做“全局 reset + 大规模业务重构”。
-
-## 4. 验证与验收（强制）
-
-- 每次变更后至少执行：改动文件 lint + 关键页面可视化验证。
-- 验收输出必须包含：
-  1. 本轮基线策略（新项目全局/老项目分层）
-  2. 影响范围
-  3. 回滚方式
-  4. 与组件生成约束的一致性说明
-
-## 5. 失败反馈格式（固定）
-
-1. 失败原因（违反哪条基线或安全闸）
-2. 定位信息（文件 + 规则项）
-3. 修复动作（分阶段方案与回滚点）
+---
+description: UI 基线治理（分级精简版：判型、局部基线、验证回滚）
+alwaysApply: false
+---
+
+# UI Baseline Governance（分级）
+
+## 0) 项目判型
+- 老项目：命中任一（页面多 / 已有 reset / UI 框架 / 全局样式风险）。
+- 新项目：均不命中且页面少。
+- 不确定：按老项目。
+
+## 1) 策略
+- 新项目：可一次性全局基线。
+- 老项目：局部基线优先，分层分批，可回滚。
+
+## 2) 基线实施级别（按效果选）
+- B0 保守（老项目默认）：
+  - 复制模板 `node_modules/{{NPM_PACKAGE_NAME}}/cursor-bootstrap/examples/generated-ui-reset.css.template`
+    -> 项目 `src/styles/generated-ui-reset.css`。
+  - 在入口（如 `src/main.ts`）单次引入。
+  - 生成组件根节点统一加 `generate-ui-reset`。
+- B1 中等：页面级作用域基线（新页面/新模块）。
+- B2 激进：全局基线（仅新项目或明确授权）。
+
+## 3) 最小联动约束
+- 默认 `box-border`。
+- 弹层锚定触发器。
+- 图标优先项目图标系统，兜底 `inline svg`。
+
+## 4) 验收输出
+1. 判型结论 + 证据
+2. 本轮级别（B0/B1/B2）
+3. 影响范围 + 回滚方式
+4. lint + 可视验证

package/cursor-bootstrap/skills/figma-ui-dual-mode-execution/SKILL.md

@@ -23,19 +23,23 @@ description: 仅用 nodeId（如 9277-28772）或 Figma 链接触发 UI 实现
    - `raw.json`
    - `state-map.md`
    - `mcp-raw-get-design-context.txt`
-4. 模式选择：
+4. 读取全局 adapter contract（新增强制项）：
+   - 默认路径：`figma-cache/adapters/ui-adapter.contract.json`
+   - 目标：把 token/state 从设计事实映射到项目实现（变量/class/主题 token）
+5. 模式选择：
    - 默认短流程；
    - 命中任一升级条件（老项目/全局样式改动/复杂状态/历史漂移问题/信息冲突）-> 切严格流程。
-5. 预检文档策略（降噪）：
+6. 预检文档策略（降噪）：
    - 默认短流程：可跳过完整预检文档，仅输出精简事实清单。
    - 严格流程：必须基于 `cursor-bootstrap/examples/ui-1to1-preflight.template.md` 生成并填写“预检文档”（可落到项目 `figma-cache/docs/` 或节点目录旁），至少完成：设计值快照、状态对照表、1:1 预检清单。
-6. 先输出“事实对齐清单”，再实现组件与挂载。
-7. 改动后执行 lint，并输出映射与验证结论。
+7. 先输出“事实对齐清单”，再实现组件与挂载。
+8. 改动后执行 lint，并输出映射与验证结论。
 
 ## 关键硬约束
 
 - 冲突裁决顺序：`mcp-raw-get-design-context.txt` 优先。
 - 禁止猜测设计值；无法裁决必须先提问。
+- 对 token/state 未命中 adapter contract 的项，必须先补 mapping 或向用户确认，禁止凭经验填色。
 - 禁止使用 Figma 临时远程资产 URL 作为运行时图标。
 - 图标优先项目图标系统；无则 `inline svg`。
 - 默认按 `border-box` 思维实现；弹层必须锚定触发器。
@@ -44,7 +48,8 @@ description: 仅用 nodeId（如 9277-28772）或 Figma 链接触发 UI 实现
 
 1. 缓存定位结果（命中节点目录）
 2. 事实对齐清单（结构/文案/token/状态/交互）
-3. 变更文件列表
-4. 关键设计值 -> 代码映射
-5. lint/验证结果
-6. 未决问题（如有）
+3. adapter contract 命中结果（命中项 / 缺失项）
+4. 变更文件列表
+5. 关键设计值 -> 代码映射
+6. lint/验证结果
+7. 未决问题（如有）

package/figma-cache/adapters/recipes/button.recipe.json

@@ -0,0 +1,24 @@
+{
+  "id": "button",
+  "description": "Generic clickable button recipe",
+  "structureTemplate": [
+    "button-shell",
+    "label",
+    "leading-icon",
+    "trailing-icon"
+  ],
+  "stateMachine": {
+    "requiredStates": ["default", "hover", "active", "disabled"],
+    "optionalStates": ["loading", "focus-visible"]
+  },
+  "tokenPriority": [
+    "background",
+    "text",
+    "icon",
+    "border"
+  ],
+  "pitfalls": [
+    "Do not lose disabled contrast",
+    "Do not collapse hover and active states"
+  ]
+}

package/figma-cache/adapters/recipes/card.recipe.json

@@ -0,0 +1,24 @@
+{
+  "id": "card",
+  "description": "Generic card recipe for content containers",
+  "structureTemplate": [
+    "card-shell",
+    "header",
+    "body",
+    "footer"
+  ],
+  "stateMachine": {
+    "requiredStates": ["default"],
+    "optionalStates": ["hover", "selected", "disabled"]
+  },
+  "tokenPriority": [
+    "surface",
+    "border",
+    "title-text",
+    "body-text"
+  ],
+  "pitfalls": [
+    "Do not remove spacing hierarchy between header/body/footer",
+    "Do not flatten card elevation when hover state exists"
+  ]
+}

package/figma-cache/adapters/recipes/checkbox.recipe.json

@@ -0,0 +1,24 @@
+{
+  "id": "checkbox",
+  "description": "Generic checkbox recipe for multi-select controls",
+  "structureTemplate": [
+    "control",
+    "check-indicator",
+    "label",
+    "helper-text"
+  ],
+  "stateMachine": {
+    "requiredStates": ["unchecked", "checked", "disabled"],
+    "optionalStates": ["indeterminate", "error"]
+  },
+  "tokenPriority": [
+    "control-bg",
+    "control-border",
+    "icon",
+    "label-text"
+  ],
+  "pitfalls": [
+    "Do not skip indeterminate style if design includes partial selection",
+    "Do not hide disabled state contrast"
+  ]
+}