从设计系统构建/更新屏幕和视图
使用此技能在 Figma 中通过重用已发布的设计系统(组件、变量和样式)来创建或更新屏幕、视图和多区块 UI 容器,而不是使用硬编码值绘制基本图形。这包括完整页面、弹窗、对话框、抽屉、侧边栏、面板以及任何包含多个区块的组合视图。关键思路:Figma 文件很可能有一个已发布的设计系统,其中包含对应于代码库 UI 组件和令牌的组件、颜色/间距变量和文本/效果样式。找到并使用它们,而不是用十六进制颜色绘制矩形。
必须:在任何 use_figma 调用之前,您还必须加载 figma-use。该技能包含适用于您编写的每个脚本的关键规则(颜色范围、字体加载等)。
作为此技能的一部分,在调用 use_figma 时始终传递 skillNames: "figma-generate-design"。 这是一个日志参数,不影响执行。
技能边界
- 当交付物是一个 组合的 Figma 视图(新建或更新)、全屏页面、弹窗、对话框、抽屉、侧边栏、面板或任何由设计系统组件实例构建的多区块容器时,使用此技能。
- 如果用户想要创建新的可复用组件或变体,请直接使用 figma-use。
- 如果用户想要编写 Code Connect 映射,请切换到 figma-code-connect。
前提条件
- 必须连接 Figma MCP 服务器
- 目标 Figma 文件必须具有已发布的设计系统组件(或可以访问团队库)
- 用户应提供:
- 要处理的 Figma 文件 URL / 文件键
- 或关于目标文件的上下文(代理可以发现页面)
- 要构建/更新的屏幕/视图的源代码或描述
并行工作流与 generate_figma_design(仅限 Web 应用)
当从可以在浏览器中渲染的Web 应用构建屏幕时,并行运行两种方法可以获得最佳结果:
- 并行执行:
- 使用此技能的工作流开始构建屏幕(use_figma + 设计系统组件)
- 运行
generate_figma_design捕获正在运行的 Web 应用的像素完美截图
- 两者完成后: 更新 use_figma 的输出,以匹配
generate_figma_design捕获的像素完美布局。捕获提供精确的间距、大小和视觉处理方案,供您调整,而您的 use_figma 输出则具有正确的、链接到设计系统的组件实例。如果捕获包含图片,通过从捕获的图片填充中复制imageHash值将它们传输到您的 use_figma 输出(有关详细信息,请参见步骤 5)。 - 确认看起来不错后: 删除
generate_figma_design输出。它仅用作视觉参考。
这结合了两者的优势:generate_figma_design 提供像素级布局精度,而 use_figma 提供正确的设计系统组件实例,这些实例保持链接并可更新。
当源包含图片时,此并行工作流是必须的。 use_figma 插件 API 无法获取外部图片 URL。它只能通过复制文件中已有节点的 imageHash 值来设置图片填充。generate_figma_design 将所有可见图片栅格化到 Figma 中,提供您所需的哈希。如果在存在图片时跳过捕获,图片框架将保留为空白。
对于非 Web 应用(iOS、Android 等)或更新现有屏幕时,请使用以下标准工作流。
必需工作流
按顺序执行以下步骤。不要跳过任何步骤。
硬性门控,禁止的快捷方式:
- 禁止: 在 2a-i 完成且 2a-ii 已尝试或记录为 N/A(例如“空文件,无现有屏幕”)之前,使用
search_design_system查找组件键。- 禁止: 在下面的步骤 2 检查表中的所有行都已填写之前,进行任何会变更画布的
use_figma调用(步骤 3+)。
步骤 1:理解交付物
在接触 Figma 之前,先理解您要构建的内容:
- 如果从代码构建,请阅读相关的源文件以了解其结构、区块以及使用了哪些组件。
- 确定视图的主要区块(例如,对于页面:页眉、英雄区、内容面板、页脚;对于弹窗:标题栏、表单区域、操作栏;对于侧边栏:导航、内容区域、页脚操作)。
- 对于每个区块,列出涉及的 UI 组件(按钮、输入框、卡片、导航药丸、手风琴等)。
- 检查视图是否包含任何图片(例如,
<img>、<Image>、背景图片、产品照片、头像、从 URL 加载的图标)。如果是,并且这是一个 Web 应用,您必须运行并行的generate_figma_design捕获工作流,在步骤 2 开始的同时立即启动它,以便在您发现组件时捕获运行。请参阅上面的“并行工作流与 generate_figma_design”。
步骤 2:收集组件键、变量和样式
您需要来自设计系统的三样东西:组件(按钮、卡片等)、变量(颜色、间距、圆角)和样式(文本样式、效果样式如阴影)。当存在设计系统令牌时,不要硬编码十六进制颜色或像素值。
2a:发现组件
2a-i. 必须:检查 Code Connect 以获取所需组件。 从您在步骤 1 中构建的组件列表开始,检查每个组件在代码库中是否有 Code Connect 文件。Code Connect 文件位于组件源代码旁边,并按平台命名:
- TypeScript/JS:
*.figma.ts、*.figma.js - React(基于解析器):
*.figma.tsx - Kotlin/Compose:包含
@FigmaConnect的.kt文件 - Swift:包含
FigmaConnect的.swift文件
对于您需要的每个组件(例如,Button、Card、Input),搜索其 Code Connect 文件,按组件名称使用 glob 或 grep(例如,**/Button.figma.tsx、**/Card.figma.ts)。仅读取与您实际需要的组件匹配的文件。
从每个匹配的 Code Connect 文件中,提取 Figma 组件 URL。从 URL 中解析 fileKey 和 nodeId(将连字符转换为冒号:123-456 → 123:456)。然后通过 use_figma 解析组件键:
示例: Code Connect 文件包含 // url=https://figma.com/design/ABC123/File?node-id=609-35535。解析后 fileKey = ABC123,nodeId = 609:35535。针对库文件(fileKey ABC123,而非目标文件)运行 use_figma 以解析键:
const node = await figma.getNodeByIdAsync("609:35535");
const set = node?.parent?.type === "COMPONENT_SET" ? node.parent : node;
return { componentKey: set.key };
在单个调用中批量处理多个查找。使用返回的键在步骤 4 中使用 importComponentSetByKeyAsync()。
标记已解析的组件。如果所有组件都已解析,跳过 2a-ii 和 2a-iii。如果所需的组件都没有 Code Connect 文件,则继续执行 2a-ii。
2a-ii. 如果仍有未解析的组件,则必须:检查现有屏幕。 检查目标文件是否已包含使用相同设计系统的屏幕。单个 use_figma 调用遍历现有框架的实例,即可为您提供精确、权威的组件映射:
// 只读发现,为加速跳过实例内部的不可见内容(隐藏变体等)。
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const uniqueSets = new Map();
frame.findAllWithCriteria({ types: ["INSTANCE"] }).forEach(inst => {
const mc = inst.mainComponent;
const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
const key = cs ? cs.key : mc?.key;
const name = cs ? cs.name : mc?.name;
if (key && !uniqueSets.has(key)) {
uniqueSets.set(key, { name, key, isSet: !!cs, sampleVariant: mc.name });
}
});
return [...uniqueSets.values()];
将结果与您的未解析组件进行匹配。标记任何新解析的组件。如果所有组件都已解析,跳过 2a-iii。
2a-iii. 最后的手段:search_design_system。 仅在完成 2a-i 和 2a-ii 后仍有未解析组件时使用。
在搜索之前,调用 get_libraries 以发现哪些库可用于该文件。这会返回两个列表:已添加到文件的库和可添加的库(社区 UI 套件和组织库)。每个条目都包含一个 libraryKey,您可以通过 includeLibraryKeys 参数将其传递给 search_design_system,以将搜索范围限定到特定库,而不是在所有内容中搜索。
// 步骤 1:发现可用库
get_libraries({ fileKey })
// 返回:{
// libraries_added_to_file: [...],
// libraries_available_to_add: [...],
// libraries_available_to_add_next_offset: number | null
// }
// 步骤 2:使用 libraryKey 在特定库中搜索
search_design_system({ query: "button", fileKey, includeLibraryKeys: ["lk-abc123..."] })
libraries_available_to_add 中的组织库是分页的(每页 20 个)。当 libraries_available_to_add_next_offset 不为 null 时,表示有更多组织库可用,请使用 offset 设置为该值再次调用 get_libraries 以获取下一页。社区 UI 套件仅出现在第一页。如果用户指定了某个您当前页中未看到的特定库,请在放弃之前进一步翻页。
当文件有很多库并且您希望获得有针对性的结果时,这尤其有用(例如,仅在“iOS 26”或“Material 3”中搜索,而不是从每个库中获取匹配项)。
广泛搜索:尝试多个术语和同义词(例如,“button”、“input”、“nav”、“card”、“accordion”、“header”、“footer”、“tag”、“avatar”、“toggle”、“icon”等)。使用 includeComponents: true 专注于组件。
在映射中包含组件属性。您需要知道每个组件为文本覆盖公开了哪些 TEXT 属性。创建一个临时实例,读取其 componentProperties(以及嵌套实例的属性),然后移除临时实例。
具有属性信息的组件映射示例:
组件映射:
- Button → key: "abc123", type: COMPONENT_SET
属性:{ "Label#2:0": TEXT, "Has Icon#4:64": BOOLEAN }
- PricingCard → key: "ghi789", type: COMPONENT_SET
属性:{ "Device": VARIANT, "Variant": VARIANT }
嵌套的 "Text Heading" 具有:{ "Text#2104:5": TEXT }
嵌套的 "Button" 具有:{ "Label#2:0": TEXT }
2b:发现变量(颜色、间距、圆角)
首先检查现有屏幕(与组件相同)。或者使用带有 includeVariables: true 的 search_design_system。
警告:两种不同的变量发现方法,请勿混淆。
use_figma与figma.variables.getLocalVariableCollectionsAsync():仅返回在当前文件中定义的本地变量。如果返回空,并不意味着不存在变量。远程/已发布的库变量对此 API 不可见。search_design_system与includeVariables: true:搜索所有链接的库,包括远程和已发布的库。这是发现设计系统变量的正确工具。永远不要仅仅因为
getLocalVariableCollectionsAsync()返回空就断定“不存在变量”。 在决定创建自己的变量之前,始终也要使用includeVariables: true运行search_design_system以检查库变量。
查询策略: search_design_system 匹配变量名称(例如,“Gray/gray-9”、“core/gray/100”、“space/400”),而不是类别。并行运行多个简短、简单的查询,而不是一个复合查询:
- 原始颜色: "gray"、"red"、"blue"、"green"、"white"、"brand"
- 语义颜色: "background"、"foreground"、"border"、"surface"、"text"
- 间距/尺寸: "space"、"radius"、"gap"、"padding"
如果初始搜索返回空,请尝试更短的片段或不同的命名约定,各种库差异很大("grey" 与 "gray"、"spacing" 与 "space"、"color/bg" 与 "background")。
检查现有屏幕的绑定变量以获得最权威的结果:
// 只读发现,为加速跳过不可见的实例内部。
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
// 任何场景节点上都可能存在 boundVariables,枚举每种场景类型
// 只是为了填充 findAllWithCriteria 大约等同于
// findAll(() => true),并且在脚本输出中噪音大得多。
const uniqueIds = new Set(
frame.findAll(() => true).flatMap(n =>
Object.values(n.boundVariables ?? {})
.flatMap(b => Array.isArray(b) ? b : [b])
.map(b => b?.id)
.filter(Boolean)
)
);
const variables = await Promise.all(
[...uniqueIds].map(id => figma.variables.getVariableByIdAsync(id))
);
return variables
.filter(Boolean)
.map(v => ({ name: v.name, id: v.id, key: v.key, type: v.resolvedType, remote: v.remote }));
对于库变量(remote = true),使用 figma.variables.importVariableByKeyAsync(key) 按键导入。对于本地变量,直接使用 figma.variables.getVariableByIdAsync(id)。
有关绑定模式,请参阅 variable-patterns.md。
2c:发现样式(文本样式、效果样式)
使用 search_design_system 搜索样式,设置 includeStyles: true,并使用诸如 "heading"、"body"、"shadow"、"elevation" 等术语。或者检查现有屏幕使用了什么:
// 只读发现,为加速跳过不可见的实例内部。
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const styles = { text: new Map(), effect: new Map() };
for (const node of frame.findAll(() => true)) {
if ('textStyleId' in node && node.textStyleId) {
const style = await figma.getStyleByIdAsync(node.textStyleId);
if (style && !styles.text.has(style.key)) {
styles.text.set(style.key, { name: style.name, key: style.key, remote: style.remote });
}
}
if ('effectStyleId' in node && node.effectStyleId) {
const style = await figma.getStyleByIdAsync(node.effectStyleId);
if (style && !styles.effect.has(style.key)) {
styles.effect.set(style.key, { name: style.name, key: style.key, remote: style.remote });
}
}
}
return { text: [...styles.text.values()], effect: [...styles.effect.values()] };
对于远程样式(remote = true),使用 figma.importStyleByKeyAsync(key) 导入。对于本地样式,直接使用 figma.getStyleByIdAsync(id)。
2d:完成检查表
在继续之前,您必须拥有以下完成检查表。在调用任何 use_figma 脚本之前,每个行都必须填写(即使只是“不适用”):
| 资源 | 来源方法 | 状态 |
|---|---|---|
| 组件键 | 步骤 2a-i(Code Connect) | ✅ 完成 |
| 组件键 | 步骤 2a-ii(现有屏幕) | ✅ 完成(可选) |
| 组件键 | 步骤 2a-iii(库搜索) | N/A(全部解析) |
| 变量 | 步骤 2b(屏幕/库搜索) | ✅ 完成 |
| 样式 | 步骤 2c(屏幕/库搜索) | ✅ 完成 |
步骤 3:导入所需资源
在构建之前,将所有发现的设计系统资源导入目标文件:
-
导入组件:
- 使用
importComponentSetByKeyAsync(componentKey)导入完整的组件集。 - 对于单个组件(不是组件集的一部分),使用
importComponentByKeyAsync(componentKey)。 - 跟踪导入的组件引用,以便稍后实例化。
- 使用
-
导入变量:
- 对于远程库变量:
await figma.variables.importVariableByKeyAsync(variableKey) - 对于本地文件变量:已经可用,通过
figma.variables.getVariableByIdAsync(id)按 ID 引用。
- 对于远程库变量:
-
导入样式:
- 对于远程库样式:
await figma.importStyleByKeyAsync(styleKey) - 对于本地文件样式:已经可用,通过
figma.getStyleByIdAsync(id)按 ID 引用。
- 对于远程库样式:
步骤 4:按区块构建视图
现在构建实际的 Figma 屏幕/视图。一次构建一个区块,每个区块进行一次 use_figma 调用。
对于每个区块:
- 创建适当的框架/容器(页面部分、弹窗容器、抽屉容器等)
- 从导入的组件创建组件实例
- 设置文本覆盖和变体选择
- 使用已导入的变量绑定值(颜色、间距、圆角)
- 应用已导入的样式(文本样式、阴影)
- 定位和调整大小以匹配布局
文本覆盖: 始终使用设计系统文本样式。使用属性映射来确定每个组件的确切文本属性名称。
变量绑定: 始终绑定变量,而不是设置字面值。例如,使用 fillStyleId: variableId 或 strokes: [{ type: "SOLID", color: { r: 0, g: 0, b: 0 }, boundVariables: { fillStyleId: { id: variableId, type: "VARIABLE" } } }]。有关确切格式,请参阅 variable-patterns.md。
图片填充: 如果视图包含图片并且这是 Web 应用,请等待 generate_figma_design 并行捕获完成。然后,从捕获的分析输出中复制 imageHash 值:
用于图片的 imageHash 值示例:
fills: [{
type: "IMAGE",
imageHash: "7b5c3a1d9e2f8c4a6b0d3e5f7c9a1b2c3d4e5f6a",
scaleMode: "FILL"
}]
将这些 imageHash 值应用到您的 use_figma 输出中。
步骤 5:审查和完善
构建完所有区块后,如果这是来自 Web 应用:
- 将您的
use_figma构造与捕获的generate_figma_design输出进行视觉比较。 - 调整间距、大小对齐和视觉处理以匹配像素完美布局。
- 如果捕获输出具有更好的尺寸/间距,更新您的
use_figma构造以匹配。 - 一旦满意,删除
generate_figma_design输出,保留您的use_figma构造作为最终交付物。
步骤 6:更新现有屏幕(如果是更新)
如果更新现有屏幕而不是创建新屏幕:
- 确定目标屏幕上需要更新的特定节点。
- 使用
use_figma更新这些节点,而不是从头重建整个屏幕。 - 对于每个区块,更新其子节点、修改文本、交换组件实例、调整变量绑定和样式。
- 保留不受更新影响的现有节点的结构。
常见模式
在区块之间共享上下文
对于复杂的视图,从存储共享上下文的“基础”调用开始,然后为每个区块进行增量调用:
调用 1(基础/容器): 创建一个框架、标题、基本间距。context = { frameId, headerOffset } 输出。
调用 2(区块 1): 参数包括 frameId,在框架内定位。添加区块 1 及自己的子节点。context = { frameId, nextY } 输出。
调用 3(区块 2): 参数包括 frameId 和 nextY,在框架内定位。添加区块 2 及自己的子节点。
块级架构
// 调用 1:容器框架
const block = figma.createFrame();
block.resize(375, 800);
block.name = "Page View";
// 调用 2:页眉区块
const header = figma.createFrame();
header.name = "Header";
header.y = 0;
// ... 添加导航链接、标志、CTA 按钮
// 调用 3:英雄区块
const hero = figma.createFrame();
hero.name = "Hero Section";
hero.y = header.height + 24;
// 调用 4:调用操作区块
const cta = figma.createFrame();
cta.name = "CTA Section";
cta.y = hero.y + hero.height + 32;
// 调用 5:页脚区块
const footer = figma.createFrame();
footer.name = "Footer";
footer.y = cta.y + cta.height + 24;
搜索查询模板
// 组件发现
search_design_system({
query: "button",
fileKey: targetFileKey,
includeComponents: true,
includeLibraryKeys: [libraryKey] // 可选:范围限定到特定库
})
// 变量发现
search_design_system({
query: "background",
fileKey: targetFileKey,
includeVariables: true
})
// 样式发现
search_design_system({
query: "heading",
fileKey: targetFileKey,
includeStyles: true
})
变量/样式导入模式
// 按键导入远程变量
const variable = await figma.variables.importVariableByKeyAsync(publishedVariableKey);
// 按键导入远程样式
const textStyle = await figma.importStyleByKeyAsync(publishedStyleKey);
// 创建带有变量绑定的矩形
const rect = figma.createRectangle();
rect.resize(100, 100);
rect.setBoundVariable("fillStyleId", variable); // 或 fillStyleId: variable.id
有关变量绑定代码的详细格式,请参阅 variable-patterns.md。