figma-pixel-implement

Figma 像素实现

将 Figma 节点中的 UI 实现到目标代码库中，并提供忠实还原导出的素材、屏幕 × 状态清单，以及保存在目标仓库中的持久化动态规范，供 figma-pixel-verify 进行测量对照。

完成边界：此技能到“已实现 + 可测量的契约”为止（代码 + 清单、规范和素材部分的文件路径）。仅存在于当前会话中的表格不算完成。对于已实现的可见图形，如果素材部分缺少对应条目，则实现尚未完成。如果项目有组件工作台，则覆盖范围内清单（状态 × 上下文）中的 Story 覆盖情况也属于实现完成的一部分（工作流 9）。像素对齐由 figma-pixel-verify 负责，本次运行将继续执行该步骤。面向用户的结果是该技能整体通过。迭代在本次运行中完成。

此技能与平台无关（Claude Code / Cursor / OpenCode / 其他平台）。它需要Figma 设计上下文能力，不要求使用某个特定 Agent 的技能 ID。

**视觉事实来源：**指定的 Figma 节点。与当前节点冲突的演示或 QA 记录应作为备注/遗留项记录，不得取代 expected。

前置条件

1. 具备 Figma 设计上下文能力（硬性门槛） — 确认 Agent 能获取节点的结构化设计数据（设计上下文、元数据、截图、环境所支持的素材导出）。如果缺少此渠道或授权失败，请停止：告知用户如何为其 Agent 启用 Figma MCP / 插件 / 等效功能。不要编造唯一固定的安装方式。不要仅凭 URL 虚构 UI。
2. 可选：平台专用的 Figma→代码指南 — 如果此 Agent 已附带官方 Figma 设计→代码技能或指南（名称因产品而异；figma-design-to-code 是一个 Cursor 插件示例），则在可用时加载，并遵循其中的 URL 解析 / Code Connect / 适配规则。缺少该命名技能并非阻碍——继续使用 Figma MCP（或等效功能）和此技能的保真度规则。不要要求 Claude Code、OpenCode 或其他 Agent 使用仅适用于 Cursor 的技能 ID。
3. Figma URL 或节点 — 优先使用 figma.com 设计/制作 URL，或明确提供 fileKey + nodeId。如果缺少，请按澄清问题的规范询问一次。

工作流（按顺序）

1. 解析目标 — 提取 fileKey / nodeId（将 node-id=1-2 转换为 1:2）。记录画框名称，用于规格表。
2. 获取设计上下文 — 完成 Prerequisites 步骤后，调用环境的设计上下文工具。将输出视为待适配的参考，而非可直接粘贴的最终代码。
3. 大型画框 — 如果载荷被截断，或画框明显包含多个分区：先获取元数据/结构，然后获取并实现每个可见子分区。实现每个可见分区时，将其清单和规格行追加到持续更新的产物中。未获取的可见分区意味着实现尚未完成。优先使用变量/令牌，而非猜测字面值。遇到设计渠道速率限制时，暂停并报告未完成的分区。
4. 屏幕 × 状态清单 — 在规格表之前，列出设计中的屏幕/分区 × 视觉状态（组件变体名称、会映射到外观的原型交互，以及可读的注释/评论/适配说明）。默认 / 悬停 / 按下 / 禁用 / 已选中等有文档记录的状态应列为清单条目。可读说明应列为清单行（按实际情况归入 blocked、视觉状态或 out-of-scope: behavior）。不属于计算样式行的原型或产品行为（窗口拖动、自动跟随滚动、鼠标滚轮翻页）仍须列出为 out-of-scope: behavior。如果设计没有 Hover（或等效）变体，记录 no-variant-in-design——不要根据说明臆造悬停颜色或尺寸。如果说明与具名节点的结构化值冲突，保留节点上的 expected，并记录该冲突。如果组件的宿主容器可能变化（宽度可调整、窄宽挤压），则在清单中添加 context 轴：产品宽度下限、预设检查点和挤压压力应列为清单行，或放入可选的 context 列。
5. 检测主题结构 — 确定设计如何表达主题：包含多种模式（如 light / dark）的变量集合，或按主题拆分的画框/变体。**如果文件有多种模式，或项目已支持主题切换（data-theme、令牌文件、prefers-color-scheme），则主题属于范围。**记录主题清单（模式名称或按主题划分的画框 nodeId）。如果文件和项目都没有第二种主题，则仅使用请求的画框/变体。
6. 构建持续更新的规格 — 在目标仓库中确定一个稳定路径：如果项目已有 Figma 文档目录，优先使用；否则使用 docs/figma/<safe-frame-name>.md。在该路径下创建 Inventory、Spec 和必需的 Assets 小节（将 Verify 留空，供 figma-pixel-verify 使用）。清单之后，写入可测量的行——必须根据获取的节点树机械展开，不能抽样。每个获取的可见节点都必须包含其位置（相对于父节点或分区的 x/y）和尺寸行；每个文本节点还必须包含完整的排版属性（font-size、weight、line-height、color、alignment），并在多行文本时记录行数；每个容器还必须包含 padding、gap、radius、shadow，以及每个子节点相对于画框原点的累计绝对偏移；兄弟节点间距须记录，并用 basis 标明关系。获取的节点必须由规格行覆盖，或说明为 out-of-scope 并给出原因——无声遗漏会导致规格不完整。最低限度的列：node / role、state、property、expected（Figma 精确值）、unit、basis（数值相对于哪个父节点或兄弟节点）、token / class in repo、source（variable、MCP field、metadata 或 Code Connect component）、primitive（project-component | custom-layout | platform-control）。**填充归属：**如果节点没有可读的填充，则 Spec 中的 expected 为透明 / none——周围颜色的截图不代表该节点拥有该填充。**文本颜色：**将文本节点自身可读的 Figma 变量用作 token / source；如果没有，则记录 raw-only。截图仅作视觉参考，不能作为数值的唯一来源。如果主题属于范围，则为随主题变化的属性添加 mode 列（或每种模式各一行）：从设计本身解析各模式的值（如果渠道提供 valuesByMode，则使用变量中的值；否则切换文件/画框模式或通过按主题划分的画框重新获取）。共享值保持为单行。会话说明仅为草稿——文件实际存在（包括 Assets）之前，实现均视为未完成。**参考导出：**从设计源导出每个范围内画框的栅格图像，存入目标仓库，并在持续更新的产物中记录 node id、本地路径和导出比例。figma-pixel-verify 会将这些图像用作差分扫描基准；范围内画框缺少参考导出意味着实现尚未完成。模板：reference.md。
7. 映射到项目 — 复用现有组件、令牌和布局基元。如果项目已有设计系统变量，优先使用，避免硬编码；标记未绑定的一次性值；为了保证还原度而必须硬编码时，在规格表中记录预期值。**可测量布局的控件：**如果节点公开了明确的宽度和高度，那么控件在实际产品使用的父容器中完成布局后，必须保留该尺寸。没有父容器、单独布局控件的探测不算。优先选择布局后尺寸与规格一致的项目组件。如果所有现成平台控件布局后的尺寸都不同，则构建自定义控件，并在该次布局过程中分配轨道、滑块和标签的框（primitive: custom-layout）。只有在对现成实例进行布局探测并确认尺寸与规格框一致后，才可使用 platform-control。扁平化载荷（仅包含外框）仍须将该外框绑定到匹配的项目组件或 custom-layout。内部尺寸须来自结构化子节点获取结果，或引用设计节点的现有规格行。
8. Assets（硬性规则） — 请参阅 reference.md 中的白名单/黑名单。将真实图像/SVG 字节导出到项目（或获批的动态来源）中。每个可见图标/徽标都应从外层实例裁切为一个文件（不能使用层叠的叶节点路径）。还原该实例的宽度、高度和偏移量——除非实例本身采用通用的 16/20/24 外框，否则不要套用这种尺寸。根据可读的实例层级还原重叠和浮动图层。除非设计要求拉伸，否则保留 SVG 宽高比。使用 <img> / 框架图像 / 保留导出的 SVG。禁止使用手工编写的路径占位符、CSS mask / mask-image + fill/currentColor 重新着色，或在仅有浅色导出时臆造蒙版主题效果（优先进行第二次导出，或记录待处理项）。主题属于范围时，按主题导出设计提供的资源（从各模式或按主题划分的画框导出）——禁止仅使用一种主题的导出再自行重新着色。在 Assets 小节中记录每个范围内的图形（节点、本地路径、格式）。
9. Stories 与组件测试 — 当目标项目有 Storybook 或类似的组件工作台（现有 story 配置、工作台配置或脚本）时：编写覆盖每个范围内 Inventory 行（状态 × 上下文）的 stories，并通过 Agent 之后可驱动的声明式入口（test id、控件或自动操作）呈现每种状态，同时遵循项目现有的 story 约定。在持续更新的产物中添加 Stories 小节，映射 story → 覆盖的清单行 → 入口（模板：reference.md）。如果项目已配置测试，则编写锁定关键 Spec 值（几何、颜色、令牌映射）的组件测试；如果没有测试配置，则记录建议，不要搭建测试框架（仅供参考，不构成阻塞）。如果没有组件工作台，只记录一次引入建议（隔离、可观察、可由 Agent 测试的表面）——测量改用 figma-pixel-verify 的渠道梯级。
10. 主题映射 — 保持忠实于设计，使用请求的画框/变体颜色。主题属于范围时，将随主题变化的变量映射到项目的主题机制（CSS 自定义属性 / 设计令牌 / data-theme 或 prefers-color-scheme 切换），而不是为每种主题复制硬编码字面值。
11. 交接 — 提供持续更新产物的路径（其中须包含 Inventory + Spec + Assets；如果有工作台，还须包含 Stories）。在同一次运行中，加载 figma-pixel-verify 并遵循其流程。对于未通过的行，该技能会在用户看到结果前修复并重新测量。面向用户的结果应为整体 PASS，或指出无法运行的测量命令的 FAIL。没有路径 = 实现尚未完成。

工具意图（与平台无关）

描述目标；让 Agent 选择原生工具：

意图	Agent 可采用的方式示例
结构化设计载荷	Figma MCP 设计上下文／元数据工具
视觉参考	截图或画布捕获工具
资源下载	MCP 资源下载或导出 API
代码／可执行规范编辑	原生编辑／写入工具（规范文件位于目标仓库中）

不要要求只能通过指定的 MCP 服务 ID 或 CLI 完成。

与其他技能的关系

能力	边界
Agent 原生的 Figma→代码指导（可选，名称各异）	如果存在，加载它以规范 MCP 使用；绝不能硬性依赖某个产品的技能 ID
Figma MCP／设计上下文工具	结构化获取的硬性门槛
figma-pixel-verify	负责测量并判定通过／失败；在同一制品（或 Spec 源文件旁的文件）中编写 Verify 部分
宿主 PDCA 工作流	如果没有持久化路径，则实现不完整；缺少 Verify 部分会导致其验证阶段失败
design-approval-gate	宿主工作流中的实现前审批——彼此独立

常见陷阱

• 将仅适用于 Cursor 的技能名称视为每个 Agent 的必需项。
• 不经项目适配就将 MCP 代码视为最终成果。
• 没有 figma-pixel-verify 却声称“像素级完美”。
• 对 Figma 导出为扁平资源的图标使用 CSS 遮罩重新着色。
• 跳过规范表，导致验证没有可测量的内容。
• 将仅限会话的表格视为实现完成（没有持久化路径）。
• 采样大型画面的外框，却声称实现完成。
• 臆造设计未提供的悬停状态或深色主题数值。
• 当主题属于范围内时：只实现请求的主题，却手动编写其他主题的数值或资源，而不是从设计中解析出来。
• 当设计关系是“到同级元素 X 的距离”时，使用节点自身的内边距作为 expected。
• 对 out-of-scope: behavior 条目声称像素检查通过。
• 仅因截图看起来有填充，就在节点没有可读取填充的情况下绘制纯色填充。
• 从叶级路径片段或通用的 16/24 包装器重新拼装图标。
• 用自行编造的语义别名替换可读取的 Figma 文本变量。
• 没有 Assets 子节，却将实现视为完成。
• 存在组件工作台，但故事未覆盖范围内的清单行，却仍宣布实现完成。
• 编写故事／测试时断言聊天或演示笔记中的数值，而不是规范表中的 expected。
• 只将“关键数值”采样到规范表中，而不是机械地展开每个已获取的节点——缺少行会导致下游无法测量（未知的未知）。
• 交接时没有逐帧参考导出——差异扫描没有基准。