• Use this skill when the deliverable is a Figma screen (new or updated) composed of design system component instances.
• If the user wants to generate code from a Figma design, switch to figma-implement-design.
• If the user wants to create new reusable components or variants, use figma-use directly.
• If the user wants to write Code Connect mappings, switch to figma-code-connect-components.

• Figma MCP server must be connected
• The target Figma file must have a published design system with components (or access to a team library)
• User should provide either:
  • A Figma file URL / file key to work in
  • Or context about which file to target (the agent can discover pages)
• Source code or description of the screen to build/update

1. In parallel:
   • Start building the screen using this skill's workflow (use_figma + design system components)
   • Run

     generate_figma_design

     to capture a pixel-perfect screenshot of the running web app
2. Once both complete: Update the use_figma output to match the pixel-perfect layout from the

   generate_figma_design

   capture. The capture provides the exact spacing, sizing, and visual treatment to aim for, while your use_figma output has proper component instances linked to the design system.
3. Once confirmed looking good: Delete the

   generate_figma_design

   output — it was only used as a visual reference.

generate_figma_design

generate_figma_design

1. If building from code, read the relevant source files to understand the page structure, sections, and which components are used.
2. Identify the major sections of the screen (e.g., Header, Hero, Content Panels, Pricing Grid, FAQ Accordion, Footer).
3. For each section, list the UI components involved (buttons, inputs, cards, navigation pills, accordions, etc.).

search_design_system

includeVariables: true

WARNING: Two different variable discovery methods — do not confuse them.

• use_figma

  with

  figma.variables.getLocalVariableCollectionsAsync()

  — returns only local variables defined in the current file. If this returns empty, it does not mean no variables exist. Remote/published library variables are invisible to this API.

• search_design_system

  with

  includeVariables: true

  — searches across all linked libraries, including remote and published ones. This is the correct tool for discovering design system variables.

Never conclude "no variables exist" based solely on

getLocalVariableCollectionsAsync()

returning empty. Always also run

search_design_system

with

includeVariables: true

to check for library variables before deciding to create your own.

search_design_system

• Primitive colors: "gray", "red", "blue", "green", "white", "brand"
• Semantic colors: "background", "foreground", "border", "surface", "text"
• Spacing/sizing: "space", "radius", "gap", "padding"

const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const varMap = new Map();
frame.findAll(() => true).forEach(node => {
  const bv = node.boundVariables;
  if (!bv) return;
  for (const [prop, binding] of Object.entries(bv)) {
    const bindings = Array.isArray(binding) ? binding : [binding];
    for (const b of bindings) {
      if (b?.id && !varMap.has(b.id)) {
        const v = await figma.variables.getVariableByIdAsync(b.id);
        if (v) varMap.set(b.id, { name: v.name, id: v.id, key: v.key, type: v.resolvedType, remote: v.remote });
      }
    }
  }
});
return [...varMap.values()];

figma.variables.importVariableByKeyAsync(key)

figma.variables.getVariableByIdAsync(id)

get_screenshot

use_figma

• Cropped/clipped text — line heights or frame sizing cutting off descenders, ascenders, or entire lines
• Overlapping content — elements stacking on top of each other due to incorrect sizing or missing auto-layout
• Placeholder text still showing ("Title", "Heading", "Button")
• Truncated content from layout sizing bugs
• Wrong component variants (e.g., Neutral vs Primary button)

1. Use

   get_metadata

   to inspect the existing screen structure.
2. Identify which sections need updating and which can stay.
3. For each section that needs changes:
   • Locate the existing nodes by ID or name
   • Swap component instances if the design system component changed
   • Update text content, variant properties, or layout as needed
   • Remove deprecated sections
   • Add new sections
4. Validate with

   get_screenshot

   after each modification.

// Example: Swap a button variant in an existing screen
const existingButton = await figma.getNodeByIdAsync("EXISTING_BUTTON_INSTANCE_ID");
if (existingButton && existingButton.type === "INSTANCE") {
  // Import the updated component
  const buttonSet = await figma.importComponentSetByKeyAsync("BUTTON_SET_KEY");
  const newVariant = buttonSet.children.find(c =>
    c.name.includes("variant=primary") && c.name.includes("size=lg")
  ) || buttonSet.defaultVariant;
  existingButton.swapComponent(newVariant);
}
return { success: true, mutatedNodeIds: [existingButton.id] };

• component-patterns.md — importing by key, finding variants, setProperties, text overrides, working with instances
• variable-patterns.md — creating/binding variables, importing library variables, scopes, aliasing, discovering existing variables
• text-style-patterns.md — creating/applying text styles, importing library text styles, type ramps
• effect-style-patterns.md — creating/applying effect styles (shadows), importing library effect styles
• gotchas.md — layout pitfalls (HUG/FILL interactions, counterAxisAlignItems, sizing order), paint/color issues, page context resets

1. STOP on error — do not retry immediately.
2. Read the error message carefully to understand what went wrong.
3. If the error is unclear, call

   get_metadata

   or

   get_screenshot

   to inspect the current file state.
4. Fix the script based on the error message.
5. Retry the corrected script — this is safe because failed scripts are atomic (nothing is created if a script errors).

• Always search before building. The design system likely has the component, variable, or style you need. Manual construction and hardcoded values should be the exception, not the rule.
• Search broadly. Try synonyms and partial terms. A "NavigationPill" might be found under "pill", "nav", "tab", or "chip". For variables, search "color", "spacing", "radius", etc.
• Prefer design system tokens over hardcoded values. Use variable bindings for colors, spacing, and radii. Use text styles for typography. Use effect styles for shadows. This keeps the screen linked to the design system.
• Prefer component instances over manual builds. Instances stay linked to the source component and update automatically when the design system evolves.
• Work section by section. Never build more than one major section per

  use_figma

  call.
• Return node IDs from every call. You'll need them to compose sections and for error recovery.
• Validate visually after each section. Use

  get_screenshot

  to catch issues early.
• Match existing conventions. If the file already has screens, match their naming, sizing, and layout patterns.