use_figma — <Your DS> Design System Skill

Context for using the use_figma MCP tool with <Your Org>'s <Your DS> design system. The figma-use skill provides the foundational Plugin API rules (return-as-output, 0–1 colors, font loading, page switching, incremental workflow, atomic errors). Load both together — this skill is the what (<Your DS> libraries, tokens, components, conventions); figma-use is the how (the API surface).

MANDATORY: load figma-use before any use_figma call. If the task is a full screen/view, also load figma-generate-design; if it is new components or a design-system build, also load figma-generate-library. Those workflow skills tell you how to assemble screens / components; this skill tells you which <Your DS> assets to assemble them from.

Always include figma-use-design-system in the comma-separated skillNames parameter when calling use_figma as part of this skill. If this skill was loaded via an MCP resource, you MUST prefix the name with resource: (e.g. resource:figma-use-design-system). This is a logging parameter — it does not affect execution.

1. The Three <Your DS> Libraries

<Your DS> ships as three published Figma libraries. These are the authoritative source of truth — never recreate their tokens, styles, or components by hand.

| Library | What it provides | File key | |---|---|---| | Variables | Design tokens, primitives, semantic variables, theming (collections + modes) | <variables-file-key> | | UI Kit | Foundations, components, patterns, text styles, effect/elevation styles, layout guides | <ui-kit-file-key> | | Icons | Icon set + symbols (stroke default; fill only for critical/warning/success) | <icons-file-key> |

> These are file keys, not per-asset publish keys. The keys you pass to importComponentSetByKeyAsync / importVariableByKeyAsync / importStyleByKeyAsync are resolved at runtime from these files — see Appendix A — Libraries & Discovery for the resolution recipe.

2. Core Rules

1. Tokens over hardcoded values — always. Every color, spacing, sizing, radius, and shadow in <Your DS> has a variable or style. Bind to it. Hardcoded hex / px is a defect, not a shortcut. See Appendix B — Tokens.
2. Prefer semantic tokens over global primitives. Use --ds-background-color-*, --ds-content-color-*, --ds-border-color-*, --ds-base-color-* — not raw --ds-color-grey-900. The global palette is used sparingly, only when no correct semantic mapping exists.
3. Instance components from the UI Kit — never rebuild them. Buttons, tables, modals, inputs, etc. already exist as components. Import and instance them; override via component properties. See Appendix D — Components.
4. Apply elevation as effect styles, not raw shadows. Use the --ds-shadow-{none,low,mid,high} effect styles from the UI Kit. They carry the correct light and dark box-shadow values. See Appendix C — Foundations → Elevations.
5. Type through text styles. Apply <Your DS> text styles (ds-heading-01..05, ds-body, ds-body-small, ds-caption, ds-code) via node.textStyleId — don't set font/size/line-height/letter-spacing by hand. Fonts: Inter (UI) and IBM Plex Mono (code).
6. Theme via collection modes, not value swaps. Light, dark, and high-contrast are modes on the Variables collections. Switch modes with setExplicitVariableModeForCollection; never duplicate a screen to "make a dark version." See Appendix B — Tokens → Theming and Appendix C — Foundations.
7. Accessibility is a gate, not a nicety. Default themes target WCAG 2.2 AA; high-contrast themes target all levels (2.0+2.1+2.2 A/AA/AAA). Validate contrast and focus visibility. See Appendix E — Accessibility.
8. Discover before creating. Inspect the target file and existing <Your DS> screens first; match their naming and structure. Only create local assets when <Your DS> genuinely lacks them.

3. Required Workflow

Follow in order. Load figma-use first.

Step 1 — Confirm the libraries are available

Run get_libraries({ fileKey }) against the target file. Confirm Variables, UI Kit, and Icons are linked (or available to add). If a needed library is missing, add it or tell the user. See Appendix A — Libraries & Discovery.

Step 2 — Resolve the asset keys you need

You need three categories of keys, resolved at runtime (don't guess):

• Variables (semantic colors, spacing, sizing, radius) — from the Variables library.
• Styles (text styles, elevation/effect styles) — from the UI Kit.
• Components / component sets (Button, Table, Modal, …) — from the UI Kit.

Resolve via search_design_system (scoped with includeLibraryKeys) or by running a read-only use_figma against the library file and reading .key off the node. See Appendix A — Libraries & Discovery for both patterns. Inspecting an existing <Your DS> screen in the target file is the most authoritative source.

Step 3 — Build incrementally with <Your DS> assets

Follow the figma-use incremental workflow (≤10 ops per call, validate after each). For each section:

• Import the components / variables / styles you resolved (batch with Promise.all).
• Instance components; override text/variant props via setProperties.
• Bind colors with setBoundVariableForPaint, spacing/radius with setBoundVariable, apply text styles via textStyleId, elevation via effectStyleId.
• Set the correct theme mode on the relevant collection(s).
• Return all created/mutated node IDs.

Step 4 — Validate

get_screenshot per section. Check: tokens actually bound (not hardcoded), correct text styles, correct elevation, correct theme mode, AA contrast, and that components are real instances (have mainComponent). See Appendix E — Accessibility.

4. Reference Appendices

The full reference docs are embedded as appendices at the end of this file (Figma skill upload accepts a single file, so everything is inlined here). Jump to the relevant one on demand:

| Appendix | When to read | Covers | |---|---|---| | Appendix A — Libraries & Discovery | Start of any <Your DS> task | The 3 libraries, get_libraries, search_design_system, runtime key-resolution recipes, import-by-key patterns | | Appendix B — Tokens | Binding any color/spacing/size/radius; theming | Semantic token map (light + dark sources), naming convention, binding patterns, theme modes | | Appendix C — Foundations | Color/type/spacing/sizing/elevation/icon/breakpoint values | Primitive scales, type scale + styles, spacing/sizing scales, elevations, icon rules, breakpoints | | Appendix D — Components | Instancing or building components | Component inventory, discover/instance/override patterns, icon component props | | Appendix E — Accessibility | Any deliverable | WCAG 2.2 AA gate, theme conformance, contrast/focus checks |

5. Pre-Flight Checklist

In addition to the figma-use pre-flight checklist, verify:

• ] figma-use loaded; skillNames includes figma-use-design-system.
• ] All three <Your DS> libraries confirmed linked (Step 1).
• ] Asset keys resolved at runtime — not guessed (Step 2).
• ] Colors bound to semantic tokens (global palette only where no semantic mapping exists).
• ] Spacing/sizing/radius bound to --ds-spacing-* / --ds-size-* / --ds-border-radius-* — no raw px.
• ] Text uses <Your DS> text styles (Inter / IBM Plex Mono); no hand-set font metrics.
• ] Elevation applied via --ds-shadow-* effect styles — no raw box-shadow.
• ] Components are real UI Kit instances with mainComponent, overridden via properties.
• ] Correct theme mode set via collection modes — not value duplication.
• ] Contrast meets WCAG 2.2 AA (default) / all levels (high-contrast).
• ] All created/mutated node IDs returned.

Appendices (Embedded Reference Docs)

> These appendices are the inlined references/*.md docs. They live here because Figma's skill upload accepts only this single SKILL.md. Links to figma-use / figma-generate-* point to those companion skills (uploaded separately), not to anything in this file.

Appendix A — Libraries & Discovery

The three <Your DS> libraries are the source of truth. This appendix covers confirming they're linked and resolving the runtime asset keys you pass to the importXByKeyAsync APIs.

The libraries

| Library | Role | File key | |---|---|---| | Variables | Tokens, primitives, semantic variables, theming (collections + modes) | <variables-file-key> | | UI Kit | Foundations, components, patterns, text styles, effect/elevation styles, layout guides | <ui-kit-file-key> | | Icons | Icons & symbols (stroke default; fill for critical/warning/success only) | <icons-file-key> |

> File keys ≠ publish keys. The values above identify the library files. The keys consumed by importComponentSetByKeyAsync, importVariableByKeyAsync, and importStyleByKeyAsync are per-asset publish keys, resolved at runtime (below).

A.1 — Confirm the libraries are linked

get_libraries({ fileKey: TARGET_FILE_KEY })
// → { libraries_added_to_file: [...], libraries_available_to_add: [...], libraries_available_to_add_next_offset }

Confirm all three <Your DS> libraries appear in libraries_added_to_file. If a needed one is only in libraries_available_to_add, add it (or ask the user). Capture each entry's libraryKey to scope searches in A.2.

A.2 — Resolve asset keys (pick the most authoritative source available)

A.2.A. Inspect an existing <Your DS> screen in the target file (best)

If the target file already has <Your DS> screens, walk one to get an exact component map — authoritative because it reflects what's actually published and linked.

js
// Read-only — skip invisible instance interiors for speed.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "EXISTING_SCREEN");
const sets = new Map();
frame.findAllWithCriteria({ types: ["INSTANCE"] }).forEach(inst => {
  const mc = inst.mainComponent;
  const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
  const key = cs ? cs.key : mc?.key;
  const name = cs ? cs.name : mc?.name;
  if (key && !sets.has(key)) sets.set(key, { name, key, isSet: !!cs, sampleVariant: mc.name });
});
return [...sets.values()];

A.2.B. search_design_system, scoped to the <Your DS> libraries

search_design_system({
  query: "button",
  fileKey: TARGET_FILE_KEY,
  includeLibraryKeys: [UI_KIT_LIBRARY_KEY],   // from get_libraries
  includeComponents: true, includeVariables: true, includeStyles: true
})

Search broadly with synonyms (button, table, modal, input, badge, banner, checkbox, radio, link, dropdown, popover, textarea). For variables, query names: "background", "content", "border", "base", "spacing", "size", "radius", "shadow".

A.2.C. Resolve a key directly from a library file

When you know the node (e.g. from a library URL …/your-ui-kit?node-id=609-35535), run a read-only use_figma against the library file and read .key:

js
const node = await figma.getNodeByIdAsync("609:35535"); // hyphens → colons
const set = node?.parent?.type === "COMPONENT_SET" ? node.parent : node;
return { name: set.name, componentKey: set.key };

A.2.D. Variables and styles

js
// Local-to-target variables only (won't see remote library vars):
const colls = await figma.variables.getLocalVariableCollectionsAsync();
// For library (remote) variables, prefer search_design_system (A.2.B) or read bound vars off an existing screen.

Import resolved assets:

• Components: await figma.importComponentSetByKeyAsync(key) / importComponentByKeyAsync(key)
• Variables: await figma.variables.importVariableByKeyAsync(key)
• Styles: await figma.importStyleByKeyAsync(key) → apply via node.textStyleId / node.effectStyleId

> ⚠️ getLocalVariableCollectionsAsync() returning empty does not mean <Your DS> has no variables — remote/published library variables are invisible to it. Use search_design_system (A.2.B) or inspect a screen (A.2.A).

A.3 — Cache what you resolve

Resolution costs round-trips. Within a task, resolve the keys you need once (batch the lookups), then reuse them across section-build calls. Return them from the discovery call so subsequent calls can pass them as string literals.

Appendix B — Tokens

Semantic tokens standardize design decisions (color, spacing, sizing, radius) in a reusable, theme-aware way. Prefer these over global primitives (Appendix C — Foundations).

Naming convention

--[namespace]-[context/category]-[role/object]-[modifier/attribute/state]

Namespace: --ds-. Examples:

• --ds-background-color-primary — default background color
• --ds-content-color-primary — primary content & icon color
• --ds-content-color-disabled — disabled content
• --ds-button-background-primary-hover — component token, hover state

Semantic color tokens (Light → Dark source)

Background colors

| Token | Light | Dark | |---|---|---| | --ds-background-color-primary | white | grey-950 | | --ds-background-color-secondary | grey-100 | grey-900 | | --ds-background-color-tertiary | grey-200 | grey-800 | | --ds-background-color-brand | blue-50 | blue-950 | | --ds-background-color-info | blue-50 | blue-950 | | --ds-background-color-success | green-50 | green-950 | | --ds-background-color-warning | yellow-50 | yellow-950 | | --ds-background-color-error | red-50 | red-950 |

Base colors (brand/status fills)

| Token | Light | Dark | |---|---|---| | --ds-base-color-brand | blue-500 | blue-500 | | --ds-base-color-info | blue-500 | blue-500 | | --ds-base-color-success | green-500 | green-500 | | --ds-base-color-warning | yellow-500 | yellow-500 | | --ds-base-color-error | red-500 | red-500 |

Border colors

| Token | Light | Dark | |---|---|---| | --ds-border-color-strong | grey-400 | grey-600 | | --ds-border-color-default | grey-300 | grey-700 | | --ds-border-color-muted | grey-200 | grey-800 |

Content colors (text & icons)

| Token | Light | Dark | |---|---|---| | --ds-content-color-primary | grey-900 | grey-100 | | --ds-content-color-secondary | grey-700 | grey-300 | | --ds-content-color-tertiary | grey-500 | grey-400 | | --ds-content-color-brand | blue-600 | blue-500 | | --ds-content-color-constant | white | white | | --ds-content-color-info | blue-600 | blue-400 | | --ds-content-color-success | green-600 | green-400 | | --ds-content-color-warning | yellow-600 | yellow-400 | | --ds-content-color-error | red-600 | red-400 | | --ds-content-color-link | blue-600 | blue-400 | | --ds-content-color-link-hover | blue-700 | blue-300 | | --ds-content-color-link-visited | purple-600 | purple-400 | | --ds-content-color-inked | black | white | | --ds-content-color-placeholder | green-400 | green-600 | | --ds-content-color-disabled | (see Variables library) | |

Semantic spacing / sizing / radius

Spacing (--ds-spacing-* aliases → primitive)

zero→0 · xs→4 · s→8 · m→12 · l→16 · xl→24 · xxl→32 · xxxl→48 (px).

Sizing (--ds-size-* → primitive)

xs→spacing-16 (1rem) · s→spacing-24 (1.5rem) · default→spacing-32 (2rem) · l→spacing-40 (2.5rem).

Border radius (--ds-border-radius-*)

s→spacing-2 (.125rem) · default→spacing-4 (.25rem) · l→spacing-8 (.5rem) · max→50vh (pill).

Component tokens (example: Button)

| Group | Tokens | |---|---| | Background | --ds-button-background-{primary,secondary,danger}, each with -hover / -active; --ds-button-background-disabled | | Size (height) | --ds-button-size-height-s → size-s (1.5rem) · -default → size-default (2rem) · -l → size-l (2.5rem) | | Gap | --ds-button-gap-s → spacing-6 · -default → spacing-s (8) · -l → spacing-m (12) |

Other components expose analogous component-level tokens — discover them per component (see Appendix D — Components).

Theming

Light, dark, and high-contrast (light & dark) are modes on the <Your DS> Variables collections — not separate values you hand-pick.

• Bind a node to the semantic variable; the mode determines the resolved primitive automatically.
• Switch a subtree's theme by setting the mode on the relevant collection:

js
// Resolve the collection + target mode id, then apply to the container node.
const collection = /* imported/looked-up color collection */;
const darkMode = collection.modes.find(m => /dark/i.test(m.name));
containerNode.setExplicitVariableModeForCollection(collection, darkMode.modeId);

• Never duplicate a screen to make a dark version. One screen + a mode switch.
• Default themes target WCAG 2.2 AA; high-contrast themes target all levels — see Appendix E — Accessibility.

Binding patterns (quick reference)

js
// Color → semantic token
const paint = figma.variables.setBoundVariableForPaint(
  { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', bgPrimaryVar
);
node.fills = [paint];

// Spacing / radius → token
frame.setBoundVariable('paddingLeft', spacingLVar);
frame.setBoundVariable('topLeftRadius', radiusDefaultVar);

// Text style / elevation → style
textNode.textStyleId = headingStyle.id;
cardNode.effectStyleId = shadowMidStyle.id;

See variable-patterns.md and effect-style-patterns.md in the figma-use companion skill for full details.

Appendix C — Foundations

Reference values for the <Your DS> primitives. Bind to the <Your DS> variables/styles rather than typing these numbers — they're listed so you can pick the right token and sanity-check that a binding resolved as expected. Namespace for all tokens: --ds-.

Colors (global primitives — Default theme)

> Use the global palette sparingly — only when no semantic token maps to the use case. Prefer the semantic tokens in Appendix B — Tokens.

Hues: grey, blue, green, red, yellow, purple. Each has steps 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950. Token: --ds-color-{hue}-{step}. Bind the variable; the Variables library holds the resolved hex/OKLCH per theme.

Typography

Font stacks: Sans (UI) = "Inter", system-ui, sans-serif · Mono (code) = "IBM Plex Mono", monospace. Scale: Major second (1.125), root/base 1rem = 16px. Weights: 400 body & code, 600 headings.

Type scale (--ds-font-size-*)

| Token | px / rem | Role | |---|---|---| | --ds-font-size-5 | 32 / 2rem | Level 1 heading | | --ds-font-size-4 | 28 / 1.75rem | Level 2 heading | | --ds-font-size-3 | 24 / 1.5rem | Level 3 heading | | --ds-font-size-2 | 20 / 1.25rem | Level 4 heading | | --ds-font-size-1 | 16 / 1rem | Level 5 heading | | --ds-font-size-base | 16 / 1rem | Body copy | | --ds-font-size-neg-1 | 14 / 0.875rem | Body small, code | | --ds-font-size-neg-2 | 12 / 0.75rem | Helper & caption |

Text styles (apply via node.textStyleId)

| Style | font-size | line-height | weight | letter-spacing | |---|---|---|---|---| | ds-heading-01 | size-5 | lh-5 | 600 | ls-3 | | ds-heading-02 | size-4 | lh-4 | 600 | ls-2 | | ds-heading-03 | size-3 | lh-3 | 600 | ls-1 | | ds-heading-04 | size-2 | lh-2 | 600 | — | | ds-heading-05 | size-1 | lh-1 | 600 | — | | ds-body | base | lh-base | 400 | — | | ds-body-small | neg-1 | lh-neg-1 | 400 | — | | ds-caption | neg-2 | lh-neg-2 | 400 | — | | ds-code | neg-1 | lh-neg-1 | 400 | (IBM Plex Mono) |

Spacing (--ds-spacing-*, 4-pt grid)

0=0 · 2 · 4 · 6 · 8 · 12 · 16 · 20 · 24 · 32 · 40 · 48 · 64 · 80 · 96 · 112 · 128 (px). Bind padding/gap/margin to these; see semantic aliases (--ds-spacing-xs…xxxl) in Appendix B — Tokens.

Sizing (--ds-sizing-*)

2 · 4 · 8 · 12 · 16 · 20 · 24 · 28 · 32 · 48 · 64 (px). Component heights/dimensions. Semantic aliases (--ds-size-xs…l) in Appendix B — Tokens.

Elevations

Apply as effect styles (node.effectStyleId). Each token carries distinct light and dark box-shadows, resolved by theme mode — never hand-author shadows.

| Token | Role | |---|---| | --ds-shadow-none | Canvas / background / global areas | | --ds-shadow-low | Main content area | | --ds-shadow-mid | Dropdowns, menus, tooltips | | --ds-shadow-high | Sidesheet, modals, popover, toasts |

Iconography

• Grids: 24×24 (base), 20×20, 16×16. viewBox stays 24×24; size sets width/height attrs.
• Stroke: 1.5px default; 1px for 16px size only. strokeWidth is a separate prop, not scaled from size.
• Rounded end caps; angles in 15° increments; corner radius 2.
• Default variant = stroke. Fill variant only for critical / warning / success states.
• Props: size: 16 | 20 | 24, strokeWidth: number. See Appendix D — Components → Icon component props.

Layout breakpoints

| Name | Value | Range | |---|---|---| | xxlarge | 1920px | 1920+ | | xlarge | 1440px | 1440–1919 | | large | 1088px | 1088–1439 | | medium | 768px | 768–1087 | | small | 480px | 480–767 | | xsmall | 320px | 320–479 |

Responsive padding: --ds-spacing-16 for xsmall/small/medium/large; --ds-spacing-24 for xlarge/xxlarge. Layout guides are provided in the UI Kit library.

Appendix D — Components

Instance components from the UI Kit library — never rebuild them. Resolve their keys at runtime (Appendix A — Libraries & Discovery), import, instance, and override via component properties.

Component inventory (UI Kit)

Known components include:

• Badge
• Banner
• Button
• Checkbox
• Dropdown menu
• Link
• Modal
• Popover
• Radio
• Table
• Text input
• Textarea

> This list reflects the spec snapshot; the published library is the source of truth. Discover the live set with search_design_system or by inspecting the UI Kit file.

Patterns

• Global: App header, Sidebar(s), App layout
• Forms

Patterns are composed from components + layout guides; assemble them from instances, don't flatten.

Instancing & overriding

js
// 1. Import the component set, pick the right variant.
const buttonSet = await figma.importComponentSetByKeyAsync(BUTTON_SET_KEY);
const primary = buttonSet.children.find(c =>
  c.type === "COMPONENT" && c.name.includes("variant=primary")
) || buttonSet.defaultVariant;

// 2. Instance it into your container.
const btn = primary.createInstance();
container.appendChild(btn);

// 3. Override text/variant/boolean props via discovered property keys.
btn.setProperties({ "Label#1:0": "Save changes" });

return { createdNodeIds: [btn.id] };

• Discover a component's property keys by creating a temp instance and reading componentProperties (and nested instances'), then remove the temp instance.
• Read source-code defaults when translating from code — <Button> with no variant may default to primary. Don't assume the library default variant matches the intended one.
• Bind any per-component color/spacing to the component tokens (e.g. --ds-button-*) — see Appendix B — Tokens → Component tokens.

Icons

Icons come from the Icons library.

• If a needed icon exists as a component, instance it (use an INSTANCE_SWAP slot, not a variant-per-icon).
• Otherwise import the SVG source via figma.createNodeFromSvg(...) and size it to the slot (see the figma-generate-design companion skill → icons). Don't reconstruct icons from rotated primitives.

Icon component props

• viewBox stays 24×24.
• size: 16 | 20 | 24 sets the width/height attributes.
• strokeWidth: number is passed directly — not derived from size. Default 1.5; use 1 for the 16px size.
• Default variant is stroke; fill variant only for critical / warning / success.
• Geometry: rounded end caps, 15° angle increments, corner radius 2.

Building a new component (when <Your DS> lacks one)

Only build locally when the library genuinely doesn't cover the need. Then:

• Follow the figma-generate-library companion skill for the component workflow (variant sets, properties, bindings).
• Bind every visual property to <Your DS> variables/styles — no hardcoded values.

Appendix E — Accessibility

Accessibility is a foundational requirement and a validation gate — not a finishing touch.

Conformance targets

| Theme | Target | Scope | |---|---|---| | Default themes (light & dark) | WCAG 2.2 Level AA | Current standard only | | High-contrast themes (light & dark) | WCAG 2.0 + 2.1 + 2.2 | All levels A, AA, and AAA |

High-contrast variants are purpose-built for accessibility and include both light and dark. During onboarding, users pick a theme preference; they can switch themes from the user-profile dropdown in the main header.

What to verify when building / validating

• Contrast — text and meaningful icons meet AA contrast against their background token in every theme mode you ship (light and dark at minimum). Because colors are token-bound, check the resolved values per mode, not just the light mode.
• Focus visibility — interactive elements (buttons, links, inputs, checkboxes, radios) have a visible focus treatment.
• Touch / target size — interactive targets are large enough; use the <Your DS> sizing tokens (--ds-size-*) rather than shrinking below component defaults.
• Semantic mapping — status meaning (info/success/warning/error) is carried by the correct semantic tokens, not color alone; pair with icon/text where the spec component does.
• Don't defeat the system — overriding a component's tokenized colors with raw values can silently break contrast guarantees. Keep bindings intact.

When you build in Figma, prefer the tokenized, component-driven path (which carries the system's accessibility decisions) and flag any place where a requested visual would violate AA.