---
name: figma-use-design-system
description: "Build or edit Figma designs and components using the <Your Org> (<ABBR>) **<Your DS>** design system. Load alongside `figma-use` whenever a task targets <Your DS> / <Your Org> / <ABBR> products — reusing the published <Your DS> Variables, UI Kit, and Icons libraries (semantic tokens, text styles, effect/elevation styles, components) instead of hardcoding colors, spacing, type, or shadows. Triggers: 'use <Your DS>', 'build with <Your DS>', '<Your Org> design system', '<ABBR> tokens/components', 'apply <Your DS> tokens', '<Your DS> button/table/modal in Figma', 'theme this with <Your DS> light/dark'. Manual/slash invocation."
disable-model-invocation: true
---

# 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](../figma-use/SKILL.md) 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](../figma-use/SKILL.md) before any `use_figma` call.** If the task is a full screen/view, also load [figma-generate-design](../figma-generate-design/SKILL.md); if it is new components or a design-system build, also load [figma-generate-library](../figma-generate-library/SKILL.md). 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](#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](#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](#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](#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](#theming) and [Appendix C — Foundations](#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](#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](#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](#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](#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](#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](#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](#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](#appendix-d--components) | Instancing or building components | Component inventory, discover/instance/override patterns, icon component props |
| [Appendix E — Accessibility](#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](../figma-use/SKILL.md#8-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](#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](#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](#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](#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](#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](#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](#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](#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](#component-tokens-example-button).

### 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.