Figma Use

use_figma — Figma Plugin API Skill

Execute JavaScript in Figma files via the Plugin API. Always pass `skillNames: "figma-use"` when calling `use_figma` (logging parameter, doesn't affect execution).

If the task involves building or updating a full page, screen, or multi-section layout in Figma from code, also load figma-generate-design. It provides the workflow for discovering design system components via search_design_system, importing them, and assembling screens incrementally. Both skills work together: this one for the API rules, that one for the screen-building workflow.

If the task involves creating or building a component in Figma (even a single component), also load figma-generate-library. It owns the component-creation workflow — variable foundations first, variant sets, then design token bindings — that figma-use alone doesn't cover. Build the token/variable foundation before the component, then bind the component's fills/cornerRadius/spacing to those variables rather than inlining literals where a token exists.

IMPORTANT: Whenever you work with design systems, start with working-with-design-systems/wwds.md to understand the key concepts, processes, and guidelines for working with design systems in Figma. Then load the more specific references for components, variables, text styles, and effect styles as needed.

$fig — the plan-based builder API (ALL NODE CREATION MUST USE THIS)

$fig is a global that is responsible for all node creation. It auto-flushes at script end (no $fig.done() needed), handles font preloading, batches mutations, and orders property assignment correctly. Use it for all node creation and mutation operations. Never use figma.createFrame(), figma.createText() or any figma.create* methods. They do not exist in this environment.

Copy these patterns

Build an auto-layout frame with children — single call:

$fig.autoLayout(
  // fixed width; omit height to hug vertically
  { name: 'Todo List', layoutMode: 'VERTICAL', width: 480 },
  ['item 1', 'item 2', 'item 3'].map((item) =>
    $fig.autoLayout(
      // Set `layoutSizingHorizontal` to FILL since auto-layout is hug x hug by default
      { name: 'Todo Item', layoutSizingHorizontal: 'FILL' },
      [$fig.text({ characters: item, fontName: { family: 'Inter', style: 'Bold' } })],
    ),
  ),
).screenshot() // Screenshot new node trees to verify. Prefer `.screenshot()` over `get_screenshot` call after `use_figma`.

N parallel items for repeated small UI elements like swatches, list items, etc.:

const ITEMS = [
  { name: 'A', bg: hex('#ffffff'), accent: hex('#0969da') },
  { name: 'B', bg: hex('#fff8f1'), accent: hex('#bf5af2') },
  // ...add more here
]
ITEMS.forEach((v, i) => $fig.autoLayout({ name: v.name, x: i * 410, width: 390, fills: [{ type:'SOLID', color: v.bg }] }, [
  $fig.text({ characters: v.name, fills: [{ type:'SOLID', color: v.accent }] }),
]))

Update existing nodes — by query or by id:

$fig.query('FRAME[name=Header] TEXT[name=Title]').set({ characters: 'New Title', fontSize: 24 })
$fig.get('1:42').set({ opacity: 0.8, cornerRadius: 12 })

Add a node inside an existing node

$fig.get('1:42').append($fig.autoLayout({ name: 'New Frame' }))

Create a component with a few different variants

const SIZES = ['Small', 'Medium', 'Large']
$fig.variants({ name: 'Button' }, SIZES.map((size) => $fig.component({ name: `Size=${size}`, layoutMode: 'HORIZONTAL', /** other props */ })))

⚠️ $fig.variants does not position the variants — they stack at (0,0) and the set renders as one collapsed, overlapping element. You must grid the variants and resize the set afterward. See `fig-builder.md` for the required follow-up recipe.

Building a component — even a single one? Binding tokenized values is part of finishing the job, not a preference. A component is not complete while any value that has a corresponding design token — one that already exists in the file, or that you created from the source — is still a hardcoded literal. When a token exists for a fills color / cornerRadius / padding / itemSpacing, bind it: build a $fig.varCollection (primitive tier + semantic tier aliased to it) and pass the variable handle straight into the property. Anti-pattern to avoid: do NOT copy resolved token values into local JS constants (e.g. const VARIANTS = [{ bg: '#2c2c2c' }]) and paint with hex(...) — that silently bypasses variables even though the source defines tokens. This applies to a single component as much as a full design system. Only bind values that actually have a token — values with genuinely no token (one-off geometry, icon pixel sizes, static 1px dividers) correctly stay literal; don't invent tokens to bind. If you create the variables in one `use_figma` call and build the component in a later one, rehydrate the handles first ($fig.getVar(id) or figma.variables.getVariableByIdAsync using the IDs you returned) — a handle from a previous call isn't in scope. Worked recipe: fig-builder.md → Building a component with bound variables.

Create an instance of a component

// First arg can be a node ID ('1:2') OR a library asset key
// from `search_design_system` results (the `componentKey` field).
$fig.instance('1:2', { name: 'Cancel Btn', props: { label: 'Cancel'}})

Consume styles/variables

$fig.autoLayout({ name: 'Card', itemSpacing: spacingVar, fills: fillStyle })

// Looked up by asset key from `search_design_system` (the `key` field)
$fig.autoLayout({ fills: $fig.getStyle(BG_STYLE_KEY) })
$fig.rectangle({ fills: [{ type: 'SOLID', color: $fig.getVar(BRAND_VAR_KEY) }] })

Use design-system assets by key (from `search_design_system`)

search_design_system returns componentKey for components and component sets, and key for styles and variables. Pass these straight into the unified $fig lookup — the plan queues the library import automatically, so you don't need a separate await figma.importComponentByKeyAsync(...) / importStyleByKeyAsync(...) / importVariableByKeyAsync(...) step.

// One call site, many input shapes — node IDs, real variable/style ids,
// AND 40-char asset keys (e.g. '49c8754d4b898e176148650df612a47998a8c4a1')
const btn        = $fig.get(BUTTON_KEY)                    // component / component set
const instance   = $fig.instance(BUTTON_SET_KEY, {         // create an instance from a set
  props: { Size: 'md', Variant: 'primary' },
})
const heading    = $fig.getStyle(HEADING_TEXT_STYLE_KEY)   // paint / text / effect / grid style
const brand      = $fig.getVar(BRAND_COLOR_VAR_KEY)        // variable

$fig.text({ characters: 'Hello', textStyle: heading })
$fig.rectangle({ fills: [{ type: 'SOLID', color: brand }] })

Discover a set's variant props from its key — search_design_system returns a set's componentKey, not its variant properties. This is two `use_figma` calls: call 1 returns the set's property definitions and its variants so their props come back to you in the tool result; then, knowing the valid props, call 2 instantiates the variant you want.

const setHandle = $fig.get(BUTTON_SET_KEY)
await $fig.done()
const set = setHandle.node
if (!set || set.type !== 'COMPONENT_SET') {
  throw new Error(`Key ${BUTTON_SET_KEY} is not a COMPONENT_SET`)
}
return {
  componentPropertyDefinitions: set.componentPropertyDefinitions,
  variants: set.children
    .filter((c) => c.type === 'COMPONENT')
    .map((c) => ({ name: c.name, variantProperties: c.variantProperties })),
}