/cc-figma-component

name: cc-figma-component
description: "Generate a Figma component set from a component contract. Use when the user wants to build or update a Figma component from a contract definition — e.g. 'build the Button Figma component', 'generate Figma component from contract', 'sync the Accordion to Figma', 'create component variants in Figma'. PREREQUISITE: the cc-figma-tokens skill must have been run first — Primitive and Semantic variable collections must exist in the target Figma file. Requires the figma-use and figma-generate-library skills."

cc-figma-component — Component Contracts Component Skill

Generate Figma component sets from component contracts. This skill reads a contract, derives component-scoped (Tier 3) tokens, and builds a fully variable-bound component set in Figma.

**Prerequisites — load these skills first:**

• `figma-use` — Plugin API syntax rules (mandatory before every `use_figma` call)
• `figma-generate-library` — Design system workflow and component creation patterns
• `cc-figma-tokens` must have been run — `Primitives` and `Semantic` collections must exist in the target Figma file

**Always pass `skillNames: "cc-figma-component"` when calling `use_figma` as part of this skill.**

---

Global Rules

Frame sizing defaults to HUG

**Every frame created by this skill must have both sizing properties set to `'HUG'` immediately after creation — no exceptions.**

node.layoutSizingHorizontal = 'HUG';
node.layoutSizingVertical   = 'HUG';

This applies to: the base component frame, every variant duplicate, the Generation Notes frame, and any other frame created during the run. Never rely on Figma's default — it sets new frames to `FIXED` at 100px, which produces portrait-aspect components regardless of padding values. Only deviate from HUG when a slot child's `figma.sizing` is explicitly set to `"fixed"` in the contract. In that case use the contract's `figma.width` and `figma.height` values directly:

   if (child.figma?.sizing === 'fixed') {
     node.layoutSizingHorizontal = 'FIXED';
     node.layoutSizingVertical   = 'FIXED';
     node.resize(child.figma.width, child.figma.height);
   }

This is the only legitimate exception to the HUG default.

---

1. Configuration

Before anything else, read `.component-contracts` from the project root. Never output `FIGMA_ACCESS_TOKEN` in any response.

FIGMA_ACCESS_TOKEN=...       # never output this value
FIGMA_FILE_KEY=...           # use for all use_figma calls
TOKENS_DIR=...               # root directory of token files
CONTRACTS_DIR=...            # root directory of contract files

---

2. Contract Structure

A component contract is a JSON file at `{CONTRACTS_DIR}/{id}.contract.json`. Read it fully before planning anything.

Key sections used by this skill:

**`tokens`** — defines the component's Tier 3 token bindings, organized by category:

{
  "tokens": {
    "color": {
      "background.primary": "brand.500",
      "text.primary": "neutral.0",
      "border.secondary": "brand.500"
    },
    "spacing": {
      "padding.x.sm": "space.sm",
      "padding.y.sm": "space.xs"
    },
    "typography": {
      "label.size": "textSize.sm",
      "label.weight": "weight.semibold"
    },
    "border": {
      "radius": "radius.md",
      "width": "border.width.sm"
    },
    "motion": {
      "transition": "duration.fast"
    }
  }
}

**`props`** — defines the component's variant axes (e.g. `variant`, `size`, `state`)

**`a11y`** — accessibility requirements (ARIA roles, keyboard behavior)

**`platforms`** — target platforms (web, ios, android)

---

3. Tier 3 Token Derivation

Component-scoped (Tier 3) tokens are derived from the contract's `tokens` section — they are NOT stored as a separate file. Derive them at runtime using these rules:

Naming convention

--ds-{componentId}-{role}-{qualifier}

Where:

• `componentId` — the contract's `id` field (e.g. `button`, `accordion`)
• `role` — the Figma-aligned role name (see role translation table below)
• `qualifier` — derived from the Semantic alias name in the contract value

Role translation table

| Contract category + key prefix | CSS/Figma role | |-------------------------------|----------------| | `color.background.*` | `fill` | | `color.text.*` | `text` | | `color.border.*` | `border` | | `color.focus.*` | `focus` | | `spacing.*` | `spacing` | | `typography.*` | `typography` | | `border.radius` | `border` (as `border-radius`) | | `border.width` | `border` (as `border-width`) | | `motion.*` | `transition` |

Qualifier derivation

The qualifier comes from the Semantic alias value in the contract, with the scale suffix dropped:

"background.primary": "brand.500"   →  qualifier = "brand"   →  --ds-button-fill-brand
"background.primary.hover": "brand.600"  →  qualifier = "brand-hover"
"text.primary": "neutral.0"         →  qualifier = "neutral-0"

State suffixes (`hover`, `active`, `focus`, `disabled`) are appended after the qualifier:

--ds-button-fill-brand-hover
--ds-button-fill-brand-active

Semantic variable lookup

Each Tier 3 token must bind to the corresponding Semantic variable in Figma. Look up the variable by name:

contract value "brand.500"  →  Semantic variable named "brand/500"
contract value "space.sm"   →  Semantic variable named "space/sm"
contract value "radius.md"  →  Semantic variable named "radius/md"

If a Semantic variable is not found, stop and report the missing variable to the user before proceeding.

---

4. Component Set Architecture

Each value of the primary variant prop (e.g. `variant`) becomes a **separate component set**, not a single combined set. Secondary axes (`Size`, `State`) become variant properties within each set.

Naming convention

{ComponentName}/{VariantValue}   →   Button/Primary, Accordion/Multiple

• Component name: title case (`Button`, `Accordion`)
• Variant value: title case (`Primary`, `Secondary`)
• S