apply-design-system

将设计连接到设计系统

当现有的 Figma 设计应复用已发布的设计系统，而不是使用脱离系统的图层、本地封装或一次性组件时，请使用此技能。

此技能支持两种进入模式：

• review-then-apply：用户希望进行全面检查，但尚未确定具体需要处理的问题区域
• apply-known-scope：用户已知道哪些区域或组件组应接入设计系统

请先加载以下能力：

• Figma MCP 读取权限，以使用 get_metadata、get_screenshot 和 search_design_system 等工具
• 如果环境要求，在调用 use_figma 之前先使用 figma-use 风格的辅助工具
• 如果有可用的屏幕构建配套工作流，且你正在重新连接整个屏幕或页面，请加载该工作流

不要将此技能作为单个 audit-design-system 问题的默认后续处理方式。对于单个目标问题，请使用 fix-design-system-finding，以保持写入范围足够小。

核心规则

不要仅仅因为某个区域包含几个设计系统按钮或图标，就将其视为“已连接”。

此技能用于跨多个区域进行协调。如果通过修复一个特定的已审查节点就能满足任务要求，更适合使用范围更窄的问题修复技能。

将每个区域准确归入以下一个类别：

• already-connected：该区域本身就是一个库实例，或是用户明确认可的规范组合
• exact-swap：已发布的库组件或变体可以直接替换该区域
• compose-from-primitives：没有单个库组件可用，但可以使用已发布的库基础组件重建该区域
• blocked：库未提供所需组件、导入失败，或该区域有意采用定制设计

必需工作流

1. 先确定范围

在收集替换候选项之前，先判断屏幕是否需要初步审查。

如果尚未确定范围：

1. 运行 audit-design-system，或执行同等的内部审查。
2. 将审查结果合并为以区域为单位的工作包，不要把每个细小问题都当作单独的重写任务。
3. 如果审查只发现一个范围较窄的问题，请改用 fix-design-system-finding，不要继续使用此技能。

如果范围已确定，请直接继续。

不要因为已有审查结果就跳过组件发现。审查用于识别偏离；此技能仍需选出实际替换所用的基础组件和变体。

2. 捕获当前状态

写入之前：

1. 使用 get_metadata 获取目标画板的元数据。
2. 使用 get_screenshot 获取截图。
3. 如果需要 get_design_context，且 Figma 询问 Code Connect 相关问题，请严格按照工具的指示向用户提问，然后再继续。

对于此技能，优先使用 get_metadata 和 use_figma 来发现结构。除非需要它来补充缺失的上下文，否则 get_design_context 为可选项。

3. 备份目标屏幕

进行破坏性编辑之前，复制画板或页面，并将备份放在右侧。

请使用清晰的名称，例如：

• Backup - Start
• Backup - Mobile dashboard

请在独立的 use_figma 调用中完成此操作，并返回创建的节点 ID。

4. 清点现有屏幕

在搜索库之前，先检查目标画板。

使用 use_figma 收集：

• 顶层区域实例
• 每个区域的 mainComponent
• 该组件是本地、远程还是缺失
• 每个本地封装内部已使用的嵌套已发布组件
• 存在时公开的文本属性和变体属性

优先使用精确键，而不是名称。名称仅供参考。

可用的只读清点模式：

(async () => {
  try {
    await figma.setCurrentPageAsync(figma.root.children.find(p => p.id === "PAGE_ID"));
    const frame = await figma.getNodeByIdAsync("FRAME_ID");
    const sections = frame.findAll(n => n.type === "INSTANCE").map(inst => {
      const mc = inst.mainComponent;
      const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
      return {
        instanceId: inst.id,
        instanceName: inst.name,
        componentName: mc?.name ?? null,
        componentKey: mc?.key ?? null,
        componentSetName: cs?.name ?? null,
        componentSetKey: cs?.key ?? null,
      };
    });
    figma.closePlugin(JSON.stringify({ createdNodeIds: [], mutatedNodeIds: [], sections }));
  } catch (e) {
    figma.closePluginWithFailure(e.message);
  }
})()

5. 根据设计系统构建组件映射

按以下顺序优先选择权威来源：

1. 同一库或工作文件中已使用该系统的现有界面
2. 使用 use_figma 直接检查已知的库页面
3. 仅在必要时将 search_design_system 用作备选

使用 search_design_system 时，请记住：

• 结果可能包含无关的团队库或社区库
• 宽泛的查询有助于发现资源，但未经核实实际文件或页面前，不要轻信结果
• 确认正确的库后，优先直接检查该文件，而不是反复搜索

对于每个候选项，记录：

• 组件或组件集的键
• 精确的变体名称
• 该区块是直接替换，还是由多个部分组合而成
• 覆盖所需的文本属性键或嵌套实例属性

不要盲目默认使用库的主要变体或默认变体。

选择变体前，先检查原始节点中的：

• 名称、文案和使用情境所体现的语义线索
• 填充、描边、效果、圆角和字体样式等视觉线索
• 界面中已有的类似变体特征，例如主按钮与次按钮的样式

然后将这些线索与可用的组件集变体进行比较，并选择最匹配的变体。如果组件系列正确，但无法明确判断哪个变体最匹配，请明确指出，而不要默默使用默认变体。

6. 确定区块策略

使用以下启发式规则：

• 如果库组件与区块的用途和结构足够接近，使用 swapComponent() 或直接替换即可保留原有意图，则选择 exact-swap。
• 如果区块实际上是由头像、徽章、按钮、指标或导航项等库组件构成的容器，则选择 compose-from-primitives。
• 如果设计系统缺少复合组件、库尚未发布、导入失败，或该区块应保持为定制设计，则选择 blocked。

常见模式：

• 标题摘要区块通常适合 compose-from-primitives，而非单个组件。
• 提醒和指标通常有较匹配的 exact-swap 候选项。
• 预约卡片或患者卡片通常需要组合，除非系统明确提供这些领域专用卡片。
• 底部导航栏通常是由导航项基础组件构建的自定义容器。

7. 一次更新一个区块

切勿在一个脚本中重写整个界面。

对于每个区块：

1. 读取当前节点 ID。
2. 导入或定位库组件。
3. 替换或重建前，先为原始区块匹配最合适的变体。
4. 检查父级是否使用自动布局。
5. 仅创建或替换该区块。
6. 返回所有已修改的节点 ID。
7. 使用 get_screenshot 验证。

如果现有节点已经是兼容组件系列的实例，且希望保留覆盖设置，优先使用 swapComponent()。

以下情况优先在原区块旁边重建：

• 旧区块是由混合内容构成的本地包装器
• 需要在替换原区块前对结果进行视觉比较
• 需要由多个基础组件组合而成

如果父级未使用自动布局，请将替换视为存在布局风险的操作。

对于未使用自动布局的父级：

• 明确保留 x 和 y
• 如果替换后的区块应占据相同的空间，请明确保留宽度和高度
• 不要假设新实例会继承旧节点的位置或尺寸
• 提醒用户，绝对定位或分组的父级可能会在替换或重建后导致布局偏移
• 仅当用户希望清理结构时，才建议将父级转换为自动布局；不要将其作为默认做法

8. 明确处理导入失败

如果 importComponentSetByKeyAsync() 或 importComponentByKeyAsync() 失败或超时：

1. 停止。
2. 不要继续进行无关编辑，并假装该部分已连接。
3. 检查目标文件中的其他位置是否已存在完全相同的组件键。
4. 如果可以访问库文件，请在那里验证确切的组件键。
5. 尝试导入确切的组件键，而不是组件集键。
6. 如果导入仍然失败，将该部分标记为 blocked，并清楚说明阻塞原因。

以下情况应视为实际阻塞：

• 已发布的键存在于库中，但导入超时
• search_design_system 找到了该组件系列，但目标文件无法导入
• 只能导入嵌套基础组件，无法导入预期的复合组件

9. 验证实际发生的更改

每个部分完成后：

• 截取已更改部分的屏幕截图，而不只是完整画框的截图
• 确认占位文本已消失
• 确认实例确实关联到库组件
• 确认间距没有退化

最后，也要验证整个屏幕的截图。

编写规则

• 逐步操作并保留备份。
• 优先直接检查库，而不是依赖嘈杂的搜索结果。
• 优先使用确切的组件键，而不是名称。
• 根据原始视觉效果匹配变体，而不只是选择正确的组件系列。
• 替换非自动布局父级中的内容时，明确保留位置和尺寸。
• 在报告中提供明确证据：节点名称、键、组件系列，以及最终节点是本地节点还是由库支持的节点。
• 如果结果仍是仅包含少数共享子项的本地外壳，不要声称已完全重新连接。
• 如果某个部分必须保持定制实现，请说明这一点并解释原因。

交付格式

结束任务时，请报告：

• Swapped：直接替换为库实例的部分
• Composed：使用库基础组件重建的部分
• Already connected：已正确连接的部分
• Blocked：无法连接的部分及具体原因

如果所有部分都受阻，请明确说明，并列出确切的失败模式，不要含糊概述。