figma-build

figma-build

将代码或描述转化为 Figma 设计，使其看起来像是文件中原有的一部分：复用已有的组件、变量和样式，只构建真正缺少的内容。 这是 figma-codegen 的镜像——秉持相同的“复用优于重新生成／引用设计令牌而非字面值”理念，只是面向画布而非代码库。此文件是路由器；详细内容位于 references/ 中——执行到相关步骤时再加载对应的参考文档。

你操作的是已连接的 Figma 文件（插件的当前会话）。无法通过 URL 获取文件；用户必须先打开目标文件。开始构建前，确认插件已连接（ping）。

适用场景

• 用户希望根据代码或描述在 Figma 中创建或更新内容——例如屏幕、视图、模态框／对话框／抽屉／侧边栏／面板、单个组件或设计系统资源。
• 不适用于将 Figma 设计转换为代码——这应使用 figma-codegen。

同时打开多个 Figma 文件

适用时，每个工具结果都会提示，因此无需预先检查：如果连接了两个或更多文件，且未指定任何文件，结果中会显示一个列出文件名称的 MORE THAN ONE FIGMA FILE IS OPEN 区块。这很重要，因为否则调用会使用用户最近操作的文件，而用户切换标签页时，这个文件也会改变——因此，任务可能从一个文件读取、向另一个文件写入，却仍报告成功。

看到该提示时，先指定文件，再进行任何操作：list_files 会列出所有已连接的文件；use_file({ fileName }) 会为此会话指定一个文件（如果两个打开的文件同名，则使用 use_file({ sessionId })——Figma 允许这种情况，x (Copy) 就是这样产生的）。此后，无论哪个文件处于前台，所有调用都会访问指定的文件，包括该文件的标签页处于后台时。如果用户没有说明要使用哪个文件，请先询问，不要根据文件名猜测。

首先了解环境，然后构建（提供方优先）

这是 codegen 中 grounding 的写入端镜像，也是最重要的习惯：构建结果看起来不对劲，几乎总是因为编造了值或想当然地套用了约定。因此，先了解这位用户的实际环境，再在其中构建——绝不要套用通用模板。没有唯一“正确”的技术栈；只有_他们的_技术栈。创建任何内容之前，先查看两端：

• Figma 文件——其现有设计系统，你将复用并绑定到该系统：
  1. get_variable_defs → 文件中的变量（颜色 / 间距 / 圆角 / 字体排版），包含名称、值和 hex。这些是你要绑定的 token。
  2. scan_components / get_local_components → 现有组件，应当创建实例而非重建。将源 UI 模式（卡片、列表行、导航、按钮）匹配到对应组件。
  3. get_styles → 要应用的共享填充 / 文本 / 效果样式。
  4. 存在于已发布资源库中的设计系统——这些读取操作只会列出该文件_自身_的定义。如果结果为空或很少，但文件基于团队资源库构建（其组件是资源库实例，或用户明确说明这一点），那么 token 就在资源库文件中：在那里读取对应键，并导入要绑定的内容。不要据此断定“没有 token”并硬编码值。 → references/write-rules.md，“来自已发布资源库的 Token”。
• 交给你的源文件——如果是代码，确认使用了_哪种_技术栈和样式系统（Tailwind / Chakra / MUI / CSS modules / vanilla …），以及是否包含 config / theme / tokens 文件。真实值就在这些文件中——从中读取，不要假定默认值。

然后开始构建，按优先顺序追溯每个值的来源：复用现有组件 / 变量 / 样式；否则，采用源代码中的精确值——提供方优先，并将其使用的样式系统解析为实际的 px / hex 值（CSS 按字面值读取； Tailwind / Chakra / UnoCSS / … 通过其 config 或比例尺解析），绝不凭目测；只有两者都不存在时，才从一致的比例尺中自行确定。完整说明和数值解析方法见 references/write-rules.md。

两项任务——都遵循写入规则

每次构建都遵循相同的通用规则——以来源为依据确定值（设计系统 → 源代码 → 比例尺），引用 token（颜色通过 bind_variable_to_paint 绑定，标量通过 bind_variable_to_node 绑定，共享外观通过 apply_style_to_node 应用），为相关子节点使用自动布局（仅顶层放置使用绝对定位），通过 set_layout_props 设置 HUG/FILL/FIXED 尺寸（让布局计算尺寸——不要硬编码宽度 / 高度），并使用真实字体（新建 TEXT 节点默认使用 Inter）。→ references/write-rules.md。

• 使用现有内容组装屏幕 / 组件（最常见的情况）：识别 UI 模式， create_instance 匹配的组件，绑定 token，逐步构建，并在每一步截图验证。→ references/assemble-screens.md。
• 创建新的设计系统资源（仅当 grounding 后发现没有等效内容时）：创建 变量 / 集合、填充 / 文本样式，或组件 + 变体集，然后切换回复用路径。→ references/author-design-system.md。

动效（动画）

如果源文件包含动画——CSS @keyframes / transition、Framer Motion、GSAP、Vue/Svelte transition——应将其创建为你所构建画框上的 Figma Motion（测试版），而不是直接忽略：每个属性使用 apply_animation_style（从 get_motion_styles 获取预设）或 apply_manual_keyframe_track，使用 set_timeline_duration 设置时长。错落排列的行应使用一个包含多个 apply_animation_style 操作的原子 batch，并逐渐增加 config.timelineOffset——不要分 N 次调用。Motion 仅适用于 Figma-Design，且关键帧会附加到顶层画框的图层上，因此要先构建画框。 → references/motion.md。

目视验证（闭环）

对构建好的节点调用 get_screenshot，修正差异并重新截图——这与代码生成采用的渲染并比对流程相同，只是方向相反。既要对照源意图，也要检查客观的设计质量（即使你是根据模糊描述构建、没有源可供对照，也能发现问题）：没有裁切或溢出，边缘对齐，间距一致（使用同一套尺度），字体层级清晰。empty: true 导出结果表示节点没有渲染任何内容（已隐藏／位于画布之外）。

规则

• 先了解环境，再开始构建。 创建任何内容前，先阅读文件的设计系统，以及源文件的技术栈／样式系统——没有唯一正确的技术栈，只有「它们自己的」。所有取值都要有依据（设计系统 → 代码自身的取值 → 合理的尺度），切勿凭空设定。
• 优先复用，而不是重新生成。 实例化现有组件；绑定现有变量／样式。仅在系统缺少所需内容时才创建，并使其命名／结构与现有规范一致。
• 引用令牌，而非字面值。 通过 bind_variable_to_paint 设置颜色，通过 bind_variable_to_node 设置标量值，通过 apply_style_to_node 应用共享样式——只要存在令牌，就绝不硬编码十六进制颜色／像素值（get_variable_defs 可查询令牌）。
• 代码中的颜色采用 sRGB——明确注明。 写入颜色时，在 r/g/b 旁注明 space: "SRGB"；否则 Display P3 文件渲染出的颜色会比代码中的颜色更饱和（references/write-rules.md）。
• 相关子节点使用自动布局，绝对坐标仅用于顶层定位。通过父节点的对齐属性（primaryAxisAlignItems / counterAxisAlignItems）居中；对齐方式不同的子节点应使用独立的包装框架，切勿通过调整 x/y 实现居中。对于没有布局的节点，align_nodes 可对齐／分布节点；set_text_properties 支持 textAlignHorizontal / textAlignVertical。操作方法、形状（create_shape、boolean_nodes、flatten_nodes）以及工具仍无法绘制的内容，见 references/write-rules.md 中的「居中与对齐」。
• 一次创建调用，完成全部样式设置。 create_frame、create_rectangle、create_ellipse、create_shape 和 create_text 支持 fills、strokes、layoutSizing*（frame 和 rectangle 还支持 cornerRadius；frame 还支持 autoLayout 和 clipsContent；text 还支持包括 textAlignHorizontal 在内的排版属性）——这些属性的含义与对应的 set_* 工具相同。使用这些参数一次完成创建和样式设置，避免先创建再连续调用其他工具。
• ok: true 不代表成功。 通过截图或回读确认会影响布局的写入，并说明工具无法表达的内容，不要声称已完成。
• 渐进式构建并验证（截图）——识别 UI 模式，并使用对应组件组装，不要用基础图形重新绘制。
• 遵循文件自身的规范——包括命名、结构以及设计系统的固有模式，就像代码生成会沿用项目现有代码风格一样。