Figwright 接地工具深度解析：component_map、token_map、icon_map 如何让 AI 复用你已有的组件与 Token

Figwright 是一款免费的、双向的 Figma MCP 服务器，可以让 Claude Code、Cursor、Codex 等任意 MCP 客户端直接读写 Figma 画布。它的三个接地（Grounding）工具——component_map、token_map、icon_map——负责把 Figma 设计里的组件、设计 Token 和图标，逐一映射到你项目里已经存在的代码资产，让 AI 生成代码时直接复用你已有的组件与 Token，而不是一味地重新造轮子、硬编码颜色。

先认识问题：AI 生成的代码为什么会"水土不服"

把 Figma 设计丢给 AI 生成代码，最常见的结果是"能看，但不能用"：

• AI 给每个按钮、卡片都重新写了一份新组件，而你项目里明明有封装好的 <Button>、<Card>；
• 颜色全部写成 #4F46E5 这样的十六进制字面量，而不是项目里定义的 --color-primary-500 或 bg-primary-500；
• 设计里用到的图标被 AI 重新导出成一遍又一遍的重复 SVG。

Figwright 的答案不是"换一个更聪明的编译器"，而是接地（Grounding）：先生成一份忠实、去重后的设计上下文（get_design_context），再用三个映射工具把设计资产和项目资产"连起来"。这三件套全部运行在你自己的机器上，源码位于 packages/mcp/src/join/ 目录。

工具	设计侧输入	项目侧输入	产出的复用信号
component_map	Figma 组件实例及变体属性	AST 扫描出的本地代码组件	candidate.filePath + 置信度 + matchedProps
token_map	Figma 变量 / 共享颜色样式	CSS 自定义属性、Tailwind/UnoCSS 配置、SCSS 变量	candidate.ref（如 bg-primary-500）
icon_map	Figma 图标节点	仓库里的 .svg 文件 + 已装图标库	文件路径 + 颜色契约 + 换色方式

component_map：让 AI 复用你已有的组件

component_map 是三个工具中最复杂的一个（packages/mcp/src/join/component-map.ts）。它的任务是把 Figma 里每个组件实例，匹配到项目里真实存在的代码组件。

它怎么做模糊匹配？

• 名称相似度：用字符二元组 Dice 系数对 Figma 名称与扫描出的组件名做确定性模糊匹配，且能剥掉 Figma 常见的装饰——Button/Primary 可以匹配到 Button，纯变体名（Size=Large, State=Hover）则被识别并丢弃，避免误配；
• 变体属性加分：如果 Figma 实例的变体轴（如 Size、State）在候选组件上恰好是已存在的 props，会获得小幅加分，让"名字差不多、接口也对得上"的组件胜出；
• 显式映射文件覆盖：项目根目录的 docs/figma-component-map.md 里每一行 | FigmaName | code/path | 都是最高优先级——一旦记录，后续每次运行都以置信度 1 命中，不再重新猜测。

结果里最值得关注的字段：

• candidate.matchedProps：Figma 变体轴中组件已有的 props，生成时直接接线；
• candidate.unmatchedProps：组件缺少的 props（例如设计里的"必填"开关），会被明确标记为"组件扩展 TODO"，而不是被静默丢弃或随手伪造；
• candidate.ambiguousWith：当两个组件名得分接近、模糊匹配无法自信抉择时，会列出备选并要求你确认——因为错误的复用是一个无声的视觉 Bug；
• staleOverrides：映射文件里指向已删除/重命名文件的"过期行"会被单独报告并自动降级为模糊匹配，保持映射文件可自愈。

token_map：让颜色与间距不再硬编码

token_map（packages/mcp/src/join/token-map.ts）把 Figma 变量和项目设计 Token 连起来，几个细节很见功力：

1. 分档感知的名称匹配。Token 名会被拆成"词干 + 档位"：Primary/500 → 词干 primary + 档位 500。词干做模糊匹配，档位必须相等——否则 Primary/50 会因为前缀相似而错误吸附到 primary-500。它还内置同义词表，把 rounded/lg 与 --radius-lg、line-height/* 与 --leading-* 视为同一标尺；
2. 颜色值精确匹配做二次确认。名字漂移也不怕：只要项目里某个 Token 的色值与 Figma 完全一致，就会被强烈信任。若多个 Token 同色（--white / --background / --card 都是 #FFFFFF），名字能区分就区分，区分不了就降低置信度并通过 ambiguousWith 列出同色兄弟，提示你按语义确认；
3. 框架内置标尺不算缺口。在 Tailwind/UnoCSS 项目里，spacing/4、line-height/7、weight/Bold 这类变量即使没有对应的项目 Token，也会被标记为 framework-builtin 并给出可直接组合的工具类（p-4、leading-7、font-bold），而不是一声不吭地报"缺失"；
4. 主题感知。Light/Dark 多模式变量会携带 figmaModes（每个主题下的取值）——AI 必须让生成的代码保持主题切换能力，而不是只写死默认模式的颜色；
5. 与组件映射一样，支持 docs/figma-token-map.md 显式记录，过期行同样通过 staleOverrides 报告。

icon_map：图标复用最谨慎的一个

icon_map（packages/mcp/src/join/icon-map.ts）把 Figma 图标节点匹配到仓库里已有的 .svg 文件，但它故意"宁缺毋滥"：

• 近似精确匹配：只有置信度达到 0.85 才允许复用文件。原因是方向错了的图标（上箭头配成下箭头）是无声的视觉 Bug，而"没匹配上"顶多重新导出一次正确的图标——精确性优先于召回率；
• 颜色契约：读取出匹配 SVG 的着色方式（currentColor / 固定色 / 多色），并结合项目导入 SVG 的方式给出具体的换色建议——甚至能提前指出"通过 <img> 引用时 currentColor 会失效"这类坑；
• 不编造 import 语句：它只给出文件路径、加载器形式和颜色契约，实际 import 写法由 AI 参照项目现有风格来写，因为别名路径取决于各项目各自的配置；
• iconLibraries 字段：检测项目里已安装的 lucide / heroicons / iconify 等图标库，作为未匹配图标的替代复用路线。

读懂置信度：high / medium / low / unmapped

三个工具共用同一套状态分桶（packages/mcp/src/join/status.ts），规则简单清晰：

状态	含义	默认阈值下的判定
high	放心复用	置信度 ≥ 0.85
medium	复用，但建议核对	≥ 0.7（threshold 默认值）
low	有候选，自行判断	≥ 0.5
unmapped	没有可靠候选	< 0.5，需要新建

high 和 medium 对 AI 的含义都是"复用它，别重写"；low 与 unmapped 的边界则是你通过 threshold 参数自定义的"可靠线"——调高它只会降级、不会升级任何映射，适合作为踩过一次错误复用之后的保险。

确认过的映射，写回项目沉淀

每次运行时匹配都是从零推导的，所以 Figwright 提供了一个"越用越准"的闭环：当你验证过某个映射确实正确（复用后渲染与设计一致），就把它追加到 docs/figma-component-map.md 或 docs/figma-token-map.md。下次运行，这条记录就是最高优先级的 ground truth，不再重复猜测。官方技能文档明确建议：只记录你证明过的、且原本不确定的映射——一条自信的错误记录比没有记录更糟（详见 skills/figma-codegen/SKILL.md）。

实际工作流：四步接地，再生成

在 figma-codegen 技能里，这三个工具是生成代码前的标准动作：

1. get_design_context（detail: full）——拿到布局、排版与 Token 绑定的结构树，作为事实来源；
2. component_map——决定哪些节点直接 import 已有组件、哪些要新建；
3. token_map——把颜色、间距、圆角换成 candidate.ref，而不是十六进制字面量；
4. icon_map——复用设计师整理好的 .svg，避免重复导出。

整个过程中每次工具调用都会在 Figma 插件面板里实时可见，包括发给模型的原始 payload，方便你审查 AI 到底拿到了什么上下文：

小结

component_map、token_map、icon_map 是 Figwright "provider-first" 理念的核心：工具不替你编译设计，而是把"你项目里已经有什么"诚实地交给模型，让生成结果长得像项目里其余的代码。三个工具各有性格——组件匹配讲灵活、Token 匹配讲确认、图标匹配讲保守，再通过两个 map 文件把人工确认沉淀为持久映射，让第 N 次生成永远比第 N-1 次更准。