figma-cache-toolchain 2.0.3 → 2.0.5

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

@@ -1,41 +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"
-  ]
+{
+  "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/skills/figma-ui-dual-mode-execution/SKILL.md

@@ -1,37 +1,55 @@
----
-name: figma-ui-dual-mode-execution
-description: 仅用 nodeId 或 Figma 链接触发 UI 实现，支持 L0/L1/L2 压缩级别，并内置基线判型与 B0/B1/B2 选择。
----
-
-# Figma UI Dual Mode Execution（分级）
-
-## 执行步骤（固定）
-1. 规范化 nodeId 并命中缓存目录。
-2. 读取 `spec/raw/state-map/design-context`。
-3. 选择压缩级别：L0/L1/L2（默认 L1）。
-4. 输出事实对齐清单并实现挂载。
-5. lint 验证并输出映射结论。
-
-## 压缩级别
-- L0：高保真严格流程（预检文档 + 完整状态）。
-- L1：标准流程（精简清单 + 核心状态）。
-- L2：快速看效果（先静态后补交互）。
-
-## 基线治理（并入）
-- 项目判型：新项目 / 老项目 / 不确定（不确定按老项目）。
-- 基线级别：B0/B1/B2（老项目默认 B0）。
-- B0（默认）：
-  - 复制模板到 `src/styles/generated-ui-reset.css`
-  - 入口单次引入
-  - 生成组件根节点加 `generate-ui-reset`
-- B1：仅新页面/模块范围启用作用域基线。
-- B2：全局基线，仅新项目或明确授权。
-- 若与规则冲突，以 `.cursor/rules/04-ui-baseline-governance.mdc` 为准。
-
-## 标签口径
-- 默认 `div/span/img`
-- 默认禁 `p/ul/li/ol/h1-h6`
-- `input/select/textarea/a` 允许
-- 原生 `button` 默认禁用（封装/UI 库按钮除外）
-- `role/aria-*` 默认不强制
-- `data-node-id/data-name` 默认不输出
+---
+name: figma-ui-dual-mode-execution
+description: 仅用 nodeId（如 9277-28772）或 Figma 链接触发 UI 实现，自动在短流程与严格流程间切换。
+---
+
+# Figma UI Dual Mode Execution
+
+本 Skill 用于：用户仅提供节点线索（节点目录名、nodeId、或带 node-id 的 Figma 链接）时，自动完成“定位缓存 -> 判定模式 -> 实现与验证”。
+
+## 支持输入
+
+- 节点目录名：如 `9277-28772`
+- nodeId：如 `9277:28772`
+- Figma 链接：`...node-id=9277-28772`（需转换为 `9277:28772`）
+
+## 执行步骤（强制）
+
+1. 规范化节点标识：
+   - `9277-28772` -> `9277:28772`
+2. 在 `figma-cache/index.json` 查命中并定位节点目录。
+3. 读取四份必读文件：
+   - `spec.md`
+   - `raw.json`
+   - `state-map.md`
+   - `mcp-raw-get-design-context.txt`
+4. 读取全局 adapter contract（新增强制项）：
+   - 默认路径：`figma-cache/adapters/ui-adapter.contract.json`
+   - 目标：把 token/state 从设计事实映射到项目实现（变量/class/主题 token）
+5. 模式选择：
+   - 默认短流程；
+   - 命中任一升级条件（老项目/全局样式改动/复杂状态/历史漂移问题/信息冲突）-> 切严格流程。
+6. 预检文档策略（降噪）：
+   - 默认短流程：可跳过完整预检文档，仅输出精简事实清单。
+   - 严格流程：必须基于 `cursor-bootstrap/examples/ui-1to1-preflight.template.md` 生成并填写“预检文档”（可落到项目 `figma-cache/docs/` 或节点目录旁），至少完成：设计值快照、状态对照表、1:1 预检清单。
+7. 先输出“事实对齐清单”，再实现组件与挂载。
+8. 改动后执行 lint，并输出映射与验证结论。
+
+## 关键硬约束
+
+- 冲突裁决顺序：`mcp-raw-get-design-context.txt` 优先。
+- 禁止猜测设计值；无法裁决必须先提问。
+- 对 token/state 未命中 adapter contract 的项，必须先补 mapping 或向用户确认，禁止凭经验填色。
+- 禁止使用 Figma 临时远程资产 URL 作为运行时图标。
+- 图标优先项目图标系统；无则 `inline svg`。
+- 默认按 `border-box` 思维实现；弹层必须锚定触发器。
+
+## 固定输出
+
+1. 缓存定位结果（命中节点目录）
+2. 事实对齐清单（结构/文案/token/状态/交互）
+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"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "id": "input",
+  "description": "Generic text-input recipe for form controls",
+  "structureTemplate": [
+    "label",
+    "input-shell",
+    "prefix-or-suffix",
+    "helper-text"
+  ],
+  "stateMachine": {
+    "requiredStates": ["default", "focused", "error", "disabled"],
+    "optionalStates": ["readonly", "success"]
+  },
+  "tokenPriority": [
+    "border",
+    "text",
+    "placeholder",
+    "background"
+  ],
+  "pitfalls": [
+    "Do not merge error state into default style",
+    "Do not ignore focused outline or border token"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "id": "modal",
+  "description": "Generic modal/dialog recipe for overlay interactions",
+  "structureTemplate": [
+    "overlay",
+    "container",
+    "header",
+    "content",
+    "actions"
+  ],
+  "stateMachine": {
+    "requiredStates": ["closed", "open"],
+    "optionalStates": ["loading", "confirming"]
+  },
+  "tokenPriority": [
+    "overlay",
+    "surface",
+    "text",
+    "action"
+  ],
+  "pitfalls": [
+    "Do not remove overlay semantics when modal opens",
+    "Do not skip action button hierarchy in footer"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "id": "radio",
+  "description": "Generic radio recipe for single-select controls",
+  "structureTemplate": [
+    "control",
+    "dot-indicator",
+    "label"
+  ],
+  "stateMachine": {
+    "requiredStates": ["unselected", "selected", "disabled"],
+    "optionalStates": ["error"]
+  },
+  "tokenPriority": [
+    "control-border",
+    "control-fill",
+    "dot",
+    "label-text"
+  ],
+  "pitfalls": [
+    "Do not mix selected/unselected semantics",
+    "Do not remove keyboard focus style"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "id": "select",
+  "description": "Generic select/dropdown recipe for UI generation",
+  "structureTemplate": [
+    "trigger",
+    "panel",
+    "option",
+    "selected-indicator"
+  ],
+  "stateMachine": {
+    "requiredStates": ["default", "expanded", "selected", "unselected"],
+    "optionalStates": ["disabled", "loading"]
+  },
+  "tokenPriority": [
+    "background",
+    "text",
+    "icon",
+    "border"
+  ],
+  "pitfalls": [
+    "Do not hardcode selected style without state linkage",
+    "Do not drop unselected state when selected exists"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "id": "table",
+  "description": "Generic data-table recipe for tabular views",
+  "structureTemplate": [
+    "table-shell",
+    "header-row",
+    "body-rows",
+    "empty-state",
+    "pagination"
+  ],
+  "stateMachine": {
+    "requiredStates": ["default", "row-hover", "row-selected"],
+    "optionalStates": ["loading", "empty", "error"]
+  },
+  "tokenPriority": [
+    "header",
+    "row-bg",
+    "row-text",
+    "divider"
+  ],
+  "pitfalls": [
+    "Do not collapse row-selected and row-hover style",
+    "Do not remove empty-state when data is unavailable"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "id": "tabs",
+  "description": "Generic tabs recipe for segmented navigation",
+  "structureTemplate": [
+    "tab-list",
+    "tab-item",
+    "active-indicator",
+    "tab-panel"
+  ],
+  "stateMachine": {
+    "requiredStates": ["default", "active"],
+    "optionalStates": ["hover", "disabled"]
+  },
+  "tokenPriority": [
+    "active-text",
+    "inactive-text",
+    "indicator",
+    "panel-bg"
+  ],
+  "pitfalls": [
+    "Do not render tab-panel without matching active tab state",
+    "Do not drop active indicator for selected tab"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "id": "tooltip",
+  "description": "Generic tooltip recipe for contextual hints",
+  "structureTemplate": [
+    "trigger",
+    "bubble",
+    "arrow",
+    "content"
+  ],
+  "stateMachine": {
+    "requiredStates": ["hidden", "visible"],
+    "optionalStates": ["delayed", "pinned"]
+  },
+  "tokenPriority": [
+    "bubble-bg",
+    "text",
+    "shadow",
+    "arrow"
+  ],
+  "pitfalls": [
+    "Do not show tooltip persistently in hidden state",
+    "Do not detach arrow color from bubble color"
+  ]
+}