apply-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Connect A Design To A Design System

将设计关联到设计系统

Use this skill for an existing Figma design that should reuse a published design system instead of detached layers, local wrappers, or one-off components.

This skill supports two entry modes:

```
review-then-apply
```
: the user wants a broad pass, but the exact offending sections are not yet identified
```
apply-known-scope
```
: the user already knows which sections or clusters should be brought onto the design system

Load these capabilities first:

Figma MCP read access for tools such as

get_metadata

get_screenshot

, and

search_design_system

a
```
figma-use
```
-style helper before any
```
use_figma
```
call, when your environment requires one
a screen-building companion workflow, when available, if you are reconnecting a full screen or page

Do not use this skill as the default follow-up to a single

audit-design-system

finding. For one targeted issue, use fix-design-system-finding so the write scope stays narrow.

本技能适用于需复用已发布设计系统的现有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以确保修改范围保持精准。

Core Rule

核心规则

Do not treat a section as "connected" just because it contains a few design-system buttons or icons.

This skill is for multi-section reconciliation. If the task can be satisfied by fixing one specific reviewed node, the narrower finding-fix skill is the better choice.

Classify each section into exactly one bucket:

```
already-connected
```
: the section itself is a library instance or a composition the user explicitly accepts as already canonical
```
exact-swap
```
: a published library component or variant can replace the section directly
```
compose-from-primitives
```
: no single library component exists, but the section can be rebuilt from published library primitives
```
blocked
```
: the library does not expose the needed components, imports fail, or the section is intentionally bespoke

不能仅因某区域包含几个设计系统按钮或图标，就认定该区域已“关联”到设计系统。

本技能用于多区域协调。若任务仅需修复单个特定检查节点，更适合使用范围更窄的问题修复技能。

将每个区域精确归类到以下类别之一：

```
already-connected
```
：该区域本身是库实例，或用户明确认可为标准规范的组合组件
```
exact-swap
```
：可直接用已发布的库组件或变体替换该区域
```
compose-from-primitives
```
：不存在单个匹配的库组件，但可使用已发布的库基础组件重新构建该区域
```
blocked
```
：库未提供所需组件、导入失败，或该区域为特意定制的组件

Required Workflow

必备工作流

1. Determine Scope First

1. 先确定范围

Before gathering replacement candidates, decide whether the screen needs an initial audit.

If scope is not already identified:

Run audit-design-system or perform an equivalent internal audit pass.
Collapse the review output into section-sized work packages instead of treating every micro-finding as a separate rewrite task.
If the review produces only one narrow finding, switch to fix-design-system-finding instead of continuing here.

If scope is already identified, continue directly.

Do not skip component discovery just because a review already exists. Review identifies drift; this skill still has to choose the actual replacement primitives and variants.

在寻找替代组件前，先判断是否需要对屏幕进行初始审核。

若范围未明确：

运行audit-design-system或执行等效的内部审核流程。
将审核输出整合为区域级工作包，而非将每个细微问题视为单独的重写任务。
若审核仅得出一个范围狭窄的问题，请切换至fix-design-system-finding，而非继续使用本技能。

若范围已明确，请直接继续。

即便已有审核结果，也请勿跳过组件发现步骤。审核仅能识别偏差，本技能仍需选择实际的替换基础组件和变体。

2. Capture the Current State

2. 记录当前状态

Before writing:

Get the target frame metadata with
```
get_metadata
```
.
Get a screenshot with
```
get_screenshot
```
.
If you need
```
get_design_context
```
and Figma asks the Code Connect question, ask the user exactly as instructed by the tool before proceeding.

For this skill, prefer

get_metadata

plus

use_figma

for structure discovery.

get_design_context

is optional unless it unlocks missing context.

在进行修改前：

使用
```
get_metadata
```
获取目标框架元数据。
使用
```
get_screenshot
```
获取截图。
若需要
```
get_design_context
```
且Figma询问Code Connect相关问题，请严格按照工具指示询问用户后再继续。

对于本技能，优先使用

get_metadata

搭配

use_figma

进行结构发现。

get_design_context

为可选操作，除非它能补充缺失的上下文信息。

3. Back Up the Target Screen

3. 备份目标屏幕

Before destructive edits, duplicate the frame or page and place the backup to the right.

Name it clearly, for example:

```
Backup - Start
```
```
Backup - Mobile dashboard
```

Do this in its own

use_figma

call and return the created node ID.

在进行破坏性编辑前，复制框架或页面，并将备份放置在右侧。

清晰命名备份，例如：

```
Backup - Start
```
```
Backup - Mobile dashboard
```

在单独的

use_figma

调用中完成此操作，并返回创建的节点ID。

4. Inventory the Existing Screen

4. 盘点现有屏幕

Inspect the target frame before searching the library.

Use

use_figma

to gather:

top-level section instances
each section's
```
mainComponent
```
whether that component is local, remote, or missing
nested published components already used inside each local wrapper
exposed text and variant properties when present

Prefer exact keys over names. Names are only hints.

Useful read-only inventory pattern:

(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);
  }
})()

在搜索库之前，检查目标框架。

使用

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. Build a Component Map From the Design System

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

Prefer authoritative sources in this order:

Existing screens in the same library or workfile that already use the system
Known library pages inspected directly with
```
use_figma
```
```
search_design_system
```
as a fallback only

When using

search_design_system

, remember:

results may include unrelated team or community libraries
broad queries are useful for discovery, but do not trust them without verifying the actual file or page
once the right library is known, prefer direct inspection of that file over repeated search calls

For each candidate, capture:

component or component-set key
exact variant name
whether the section is a one-to-one swap or a composition
text property keys or nested instance properties needed for overrides

Do not default blindly to the library's primary or default variant.

Before choosing a variant, inspect the original node for:

semantic cues from the name, copy, and usage context
visual cues such as fills, strokes, effects, corner radius, and typography treatment
existing variant-like traits already visible in the screen, such as primary vs secondary button treatment

Then compare those cues against the available component-set variants and choose the closest match. If the family is correct but the variant match is ambiguous, call that out instead of silently using the default variant.

优先按以下顺序使用权威来源：

同一库或工作文件中已使用该系统的现有屏幕
使用
```
use_figma
```
直接检查的已知库页面
仅在万不得已时使用
```
search_design_system
```
作为备选

使用

search_design_system

时，请记住：

结果可能包含无关的团队或社区库
宽泛的查询有助于发现组件，但未经实际文件或页面验证请勿轻信
一旦确定正确的库，优先直接检查该文件，而非重复调用搜索功能

为每个候选组件记录：

组件或组件集的键
精确的变体名称
该区域是一对一替换还是组合构建
覆盖所需的文本属性键或嵌套实例属性

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

选择变体前，请检查原始节点：

名称、文案和使用场景中的语义线索
视觉线索，如填充、描边、效果、圆角和排版处理
屏幕中已有的类似变体特征，如主要按钮与次要按钮的处理方式

然后将这些线索与可用的组件集变体进行比较，选择最匹配的变体。若组件家族正确但变体匹配存在歧义，请明确指出，而非默认使用默认变体。

6. Decide Section Strategy

6. 确定区域策略

Use these heuristics:

```
exact-swap
```
if a library component matches the section's job and structure closely enough that
```
swapComponent()
```
or a direct replacement preserves intent.
```
compose-from-primitives
```
if the section is really a container around library pieces such as avatar, badge, buttons, metrics, or nav items.
```
blocked
```
if the design system lacks the composite, the library is not published, imports fail, or the section should remain bespoke.

Common patterns:

Header summary blocks are often
```
compose-from-primitives
```
, not one component.
Alerts and metrics often have strong
```
exact-swap
```
candidates.
Appointment or patient cards often require composition unless the system explicitly ships those domain cards.
Bottom nav bars are frequently custom containers built from nav-item primitives.

使用以下启发式规则：

若库组件与该区域的功能和结构足够匹配，使用
```
swapComponent()
```
或直接替换即可保留设计意图，则归类为
```
exact-swap
```
。
若该区域实际上是围绕库组件（如头像、徽章、按钮、指标或导航项）的容器，则归类为
```
compose-from-primitives
```
。
若设计系统缺少该复合组件、库未发布、导入失败，或该区域需保持定制化，则归类为
```
blocked
```
。

常见模式：

头部摘要区块通常为
```
compose-from-primitives
```
，而非单个组件。
提示框和指标通常有明确的
```
exact-swap
```
候选组件。
预约或患者卡片通常需要组合构建，除非系统明确提供此类领域卡片。
底部导航栏通常是使用导航项基础组件构建的自定义容器。

7. Update One Section At A Time

7. 一次更新一个区域

Never rewrite the entire screen in one script.

For each section:

Read the current node IDs.
Import or locate the library component.
Match the closest variant to the original section before swapping or rebuilding.
Detect whether the parent uses auto-layout.
Create or swap only that section.
Return all mutated node IDs.
Validate with
```
get_screenshot
```
.

Prefer

swapComponent()

when the existing node is already an instance of a compatible family and you want to preserve overrides.

Prefer rebuilding beside the original when:

the old section is a local wrapper around mixed content
you need to compare the result visually before replacing the original
you are composing from multiple primitives

When the parent is not auto-layout, treat replacement as a layout-risk operation.

For non-auto-layout parents:

preserve
```
x
```
and
```
y
```
explicitly
preserve width and height explicitly when the replacement should occupy the same footprint
do not assume the new instance will inherit the old node's position or size
warn the user that absolute-positioned or grouped parents can cause drift after swaps or rebuilds
suggest converting the parent to auto-layout only when the user wants structural cleanup, not as the default move

切勿在单个脚本中重写整个屏幕。

针对每个区域：

读取当前节点ID。
导入或定位库组件。
在替换或重建前，为原始区域匹配最接近的变体。
检测父容器是否使用自动布局。
仅创建或替换该区域。
返回所有修改的节点ID。
使用
```
get_screenshot
```
验证结果。

若现有节点已属于兼容组件家族的实例，且需保留覆盖属性，优先使用

swapComponent()

。

在以下情况中，优先在原始区域旁重建：

旧区域是混合内容的本地包装器
需要在替换原始区域前直观比较结果
正在使用多个基础组件进行组合构建

若父容器未使用自动布局，替换操作存在布局风险。

针对非自动布局父容器：

明确保留
```
x
```
和
```
y
```
坐标
若替换组件需占据相同空间，明确保留宽度和高度
请勿假设新实例会继承旧节点的位置或尺寸
警告用户：绝对定位或分组的父容器在替换或重建后可能导致布局偏移
仅在用户需要结构清理时，才建议将父容器转换为自动布局，而非默认操作

8. Handle Import Failures Explicitly

8. 明确处理导入失败

importComponentSetByKeyAsync()

importComponentByKeyAsync()

fails or times out:

Stop.
Do not continue making unrelated edits and pretend the section is connected.
Check whether exact component keys already exist elsewhere in the target file.
If the library file is accessible, verify the exact component key there.
Try importing the exact component key instead of the component-set key.
If imports still fail, mark the section
```
blocked
```
and report the blocker clearly.

Treat these as real blockers:

published key exists in the library but import times out
```
search_design_system
```
finds the family, but the target file cannot import it
only nested primitives can be imported, not the intended composite

若

importComponentSetByKeyAsync()

或

importComponentByKeyAsync()

失败或超时：

停止操作。
请勿继续进行无关编辑并假装该区域已关联。
检查目标文件中是否已存在精确的组件键。
若可访问库文件，验证其中的精确组件键。
尝试导入精确的组件键，而非组件集键。
若导入仍失败，将该区域标记为
```
blocked
```
并清晰报告阻塞原因。

以下情况视为真实阻塞：

库中存在已发布的键，但导入超时
```
search_design_system
```
找到组件家族，但目标文件无法导入
仅能导入嵌套基础组件，无法导入预期的复合组件

9. Validate What Actually Changed

9. 验证实际修改内容

After each section:

screenshot the changed section, not only the full frame
confirm placeholder text is gone
confirm the instance is really linked to a library component
confirm spacing did not regress

At the end, validate the full screen screenshot as well.

每个区域修改完成后：

截取修改后区域的截图，而非仅截取完整框架
确认占位文本已移除
确认实例确实链接到库组件
确认间距未出现倒退

最后，也需验证完整屏幕的截图。

Writing Rules

编写规则

Work incrementally and preserve a backup.
Prefer direct library inspection over noisy search results.
Prefer exact component keys over names.
Match the variant to the original visual treatment, not just the correct component family.
Preserve position and size explicitly when replacing content inside non-auto-layout parents.
Use imperative evidence in the report: node names, keys, component families, and whether the final node is local or library-backed.
Do not claim full reconnection when the result is still a local shell around a few shared children.
If a section must remain bespoke, say so and explain why.

增量式工作并保留备份。
优先直接检查库，而非依赖嘈杂的搜索结果。
优先使用精确组件键而非名称。
为变体匹配原始视觉处理方式，而非仅匹配正确的组件家族。
在非自动布局父容器内替换内容时，明确保留位置和尺寸。
在报告中使用客观证据：节点名称、键、组件家族，以及最终节点是本地组件还是库关联组件。
若结果仍为包含少量共享子组件的本地外壳，请勿声称已完全关联。
若某区域必须保持定制化，请明确说明并解释原因。

Deliverable Format

交付格式

When closing the task, report:

```
Swapped
```
: sections replaced directly with library instances
```
Composed
```
: sections rebuilt from library primitives
```
Already connected
```
: sections that were already valid
```
Blocked
```
: sections that could not be connected, with the concrete reason

If everything is blocked, say that plainly and include the exact failure mode instead of a vague summary.

完成任务时，请报告：

```
Swapped
```
：直接用库实例替换的区域
```
Composed
```
：使用库基础组件重建的区域
```
Already connected
```
：已有效的区域
```
Blocked
```
：无法关联的区域及具体原因

若所有区域均被阻塞，请直接说明，并包含精确的失败模式，而非模糊的总结。