Figma Component Mapper：设计稿和开发组件映射

在现实的设计工作中，我们总会遇到很多稿子图层没命名、组件被 detach、没有 auto layout，甚至中文文案和英文组件库结构混在一起的情况，这种设计稿别说 AI，就连我们人看起来都是灾难的级别。

Agent 如果只看图层名或视觉表面，很容易直接堆 div、span 和 CSS，最后页面看起来像，但工程结构已经偏离组件库了。

所以我想做的不是一个“看到按钮就生成按钮样式”的工具，而是一层更靠前的判断：先问清楚这到底是什么组件、属于什么页面区域、应该优先复用组件库的什么能力。比如一个描边按钮，不能因为它看起来和默认按钮不一样，就立刻写 border、color、padding 覆盖；它可能只是 Button 的 appearance=outline。

figma-component-mapper 的核心动机就是把设计输入先归一成稳定的工程语义。它站在设计稿和代码实现之间，帮助 Agent 先做映射，再做实现。

这个 Skill 能干什么

它可以接收 Figma 链接、node-id、截图、原型描述等视觉输入，然后产出一份结构化的 Mapping Report。这个报告会说明当前识别的是整页、区块还是单组件，每个关键区域最可能映射成什么组件或业务结构，哪些判断是高置信度，哪些仍然需要组件库 provider 继续确认。

• 识别页面模式：例如列表页、表单页、弹窗、筛选区、表格区、分页区。

• 识别组件语义：例如 Button、Input、Select、DatePicker、Dialog、Table、Pagination、FormField。

• 识别组件能力：优先判断 props、variants、slots、tokens、composition、state patterns，而不是直接写样式覆盖。

• 处理不规范设计稿：图层未命名、命名混乱、组件 detach、没有 auto layout、老稿子只有视觉结构，也要能先给出可解释判断。

• 处理 icon 场景：先判断图标角色和宿主组件，再给语义候选和资产候选，避免直接按图层名硬猜图标名。

• 和组件库 provider 协作：Skill 负责“通用语义”，组件库 Skill 或 MCP provider 负责“真实组件名、API、token、图标资产、版本差异”。

page_pattern:
interaction_summary:
provider_source:
regions:
  - name:
    target:
    mapping_status:
    confidence:
    evidence:
library_api_mapping:
capability_resolution_attempts:
uncertain_points:
fallback_notes:
implementation_plan:

这份结构化输出的价值在于：它让 Agent 的判断过程可检查。不是一句“我已经按设计还原了”，而是清楚说明为什么这里是 Button、为什么这里是 dialog footer、为什么这里还不能确定真实图标资产。

Skill 原理

我先把目标拆成两层：第一层是 figma-component-mapper 负责的“设计语义映射”；第二层是组件库 provider 负责的“真实组件库落地”。这个拆分很重要，因为 mapper 不应该假装自己知道所有组件库的真实 API。它可以判断 target_component: Button，但具体叫 Button、EButton、EsButton，或者项目里有二次封装组件，必须由组件库信息来确认。

接着我在 SKILL.md 里定义了触发条件、第一原则和标准工作流。最关键的一条是：先映射，后实现。只要任务来自 Figma、截图、设计稿、原型或视觉参考，第一步都要先产出 Mapping Report，再进入代码实现。

然后我把容易出错的判断拆进 references 目录，做成可复用的规则文档。比如 strict-mapping-workflow 负责约束不要跳过映射，confidence-and-fallback 负责处理置信度和降级，icon-recognition 负责图标识别，component-library-handshake 负责定义 Skill / MCP / hybrid provider 的协作边界。

最后我给 provider 做了一个握手约定：如果组件库以 MCP 形态提供结构化事实，就优先查询 MCP；如果 MCP 不足以回答项目策略、封装习惯或经验性规则，再由 Skill provider 补充。两者同时存在时，就按 hybrid provider 处理。

验证效果和不断改进

我验证时重点看它有没有阻止 Agent 走捷径。比如遇到按钮视觉偏差时，是否先检查组件库现有 variants、props、tokens，而不是直接写样式；遇到 Dialog 时，是否继续拆出 dialog-header、dialog-body、dialog-footer，而不是把 body 写成一个黑盒“内容区”；遇到 icon 时，是否先判断角色和宿主，而不是直接猜资产名。

迭代过程中，我把很多容易混淆的场景沉淀成 case study：比如描边按钮应该走组件能力而不是 CSS 覆盖，弹窗 body 不能只做黑盒识别，弹窗 footer 的主次按钮要回到语义和区域判断，图标名称不一致时不能只依赖图层名。

这类 Skill 的改进不是一次性写完规则，而是不断把“Agent 容易犯错的地方”变成显式约束。每新增一个规则，目标都不是让输出更复杂，而是让它更少胡猜、更能解释、更贴近工程真实落地。

获取方式

这个项目已经开源在 GitHub，仓库地址如下：

如果你也在做设计稿到代码、Figma 到组件库、或者让 Agent 更稳定理解设计稿的工作，可以直接参考这个仓库里的 SKILL.md 和 references 目录。它目前更像一个通用映射层：先把视觉输入变成组件语义，再和你的组件库 Skill 或 MCP provider 一起完成最终落地。