/apply-design-system

name: apply-design-system
description: Review an existing design and connect it to design system components.

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](../fix-design-system-finding/SKILL.md) so the write scope stays narrow.

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

Required Workflow

1. Determine Scope First

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

If scope is not already identified: 1. Run [audit-design-system](../audit-design-system/SKILL.md) or perform an equivalent internal audit pass. 2. Collapse the review output into section-sized work packages instead of treating every micro-finding as a separate rewrite task. 3. If the review produces only one narrow finding, switch to [fix-design-system-finding](../fix-design-system-finding/SKILL.md) 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.

2. Capture the Current State

Before writing: 1. Get the target frame metadata with `get_metadata`. 2. Get a screenshot with `get_screenshot`. 3. 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.

3. Back Up the Target Screen

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.

4. Inventory the Existing Screen

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

5. Build a Component Map From the Design System

Prefer authoritative sources in this order: 1. Existing screens in the same library or workfile that already use the system 2. Known library pages inspected directly with `use_figma` 3. `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 th