/extract-color

name: extract-color
description: Interpret a component's color-token mapping (per-element fills/strokes/effects, axis classification, boolean delta, variable mode detection, strategy plan) from the `_base.json` produced by the uSpec Extract Figma plugin, and write the normalized JSON to disk. Read-only interpretation — no Figma calls except an optional tiny delta script.

Extract Color Data

Interpretation-only companion to `create-color`. This skill **does not extract data from Figma**. It reads `{cachePath}/{componentSlug}-_base.json` (produced by the uSpec Extract Figma plugin), applies the same reasoning layer as `create-color`, and writes the finalized color dataset (either `ColorAnnotationData` or `ConsolidatedColorAnnotationData`) to disk for the `create-component-md` orchestrator.

**Quality contract:** every reasoning step (axis classification review, boolean enrichment, mode detection, container detection, composite breakdown, strategy selection, variant reduction plan, audit) mirrors `create-color/SKILL.md`. Any improvement to color-extraction quality must be made in both places.

**Batch-mode contract.** This skill MUST NOT call `AskQuestion`, prompt for confirmation, or pause for user input. On ambiguous rendering-strategy or container-detection decisions, pick the most defensible option based on the evidence and record the reasoning in `generalNotes` or `_containerRerunHint`. No mid-interpretation clarifications.

Invocation Contract

The orchestrator calls this skill with these inputs (already resolved — do NOT re-parse URLs or re-read `uspecs.config.json`):

• `componentSlug` — filename-safe slug
• `cachePath` — cache directory, typically `.uspec-cache/{componentSlug}/`
• `optionalContext` — free-form string from the user (may be `"none"`)
• `mcpProvider` — `figma-console` or `figma-mcp` (only used if a Step 3-delta escape hatch fires)
• `deltaAvailable` — boolean derived from `_base.json._meta.fileKey` + `nodeId`. Plugin exports normally make this `true`; a separately-passed `figmaLink` is not required.
• `apiDictionaryPath` — absolute or workspace-relative path to `{cachePath}/{componentSlug}-api-dictionary.json`. Optional. When present, the file is the canonical vocabulary for axis/value/sub-component/state naming (see Step 2.5). When absent, the skill continues with `_dictionaryUnavailable: true` in its output envelope.
• `evidencePath` — optional. Path to `{cachePath}/{componentSlug}-evidence-color.json` from CLI prepare. When present and hash-valid, use `data` as the Step 3 working evidence set.

`fileKey` and `nodeId` are **not** pass-through parameters anymore. Read them from `{cachePath}/{componentSlug}-_base.json._meta.fileKey` and `_meta.nodeId` at the start of Step 1.

**Output:**

• Writes `{cachePath}/{componentSlug}-color.json` with a `{ _meta, data }` envelope. `data` is the finalized color dataset (Strategy A or Strategy B shape).
• Returns a single-line summary: `"Color extracted: strategy={A|B}, N sections, M unique tokens, modes=[...] → {path}"`.
• Never creates or mutates Figma nodes.

MCP Adapter

Typically **zero** MCP calls — this skill reads `_base.json` from disk. The adapter applies only to the optional Step 3-delta escape hatch.

| Operation | `figma-console` | `figma-mcp` | |-----------|-----------------|-------------| | Execute Plugin JS (delta only) | `figma_execute` with `code` | `use_figma` with `fileKey`, `code`, `description` |

For `figma-mcp` delta scripts, include the page-focus preamble after `getNodeByIdAsync`:

let _p = node; while (_p.parent && _p.parent.type !== 'DOCUMENT') _p = _p.parent;
if (_p.type === 'PAGE') await figma.setCurrentPageAsync(_p);

Workflow

Task Progress:
- [ ] Step 1: Read instruction file
- [ ] Step 2: Load _base.json and optionalContext
- [ ] Step 2.5: Load API dictionary (canonical vocabulary) — optional
- [ ] Step 3: Build working evidence set (resolve colorWalk entries into tokens)
- [ ] Step 3-delta: OPTIONAL — read-only Figma call if a fact is genuinely missing
- [ ] Step 4: Interpret — strategy selection, variant plan, container detection, composite breakdown
- [ ] Step 5: Organize into ColorAnnotationData / ConsolidatedColorAnnotationData
- [ ] Step 6: Audit (re-read instruction file)
- [ ] Step 7: Write JSON to cache and return one-line summary

Step 1: Read Instructions

Read [agent-color-instruction.md]({{ref:color/agent-color-instruction.md}}). This is the **same** instruction file used by `create-color`. Treat it as the single source of truth for the data structure, rendering strategies, the two-gate decision model, composite-style handling, variable-mode rules, and audit checklists.

Rendering-only sections to skip

The shared instruction file describes both extraction and Figma rendering. This skill only performs interpretation — ignore guidance below. The data schema and audit checklists still apply.

• **§Handling Special Cases — Composite Styles §Rendering block** (frame-visibility recipe for `#hierarchy-indicator`) — template-frame contract used only at render time. Still populate `compositeChildren` with `element`, `value`, `notes`.
• **§Handling Special Cases — "Preview rendering limitations"** — does not apply.
• **§Data Structure Reference — "no JSON output is needed"** — inverted: we **do** output JSON.
• **§Structure Rules — "Each entry renders as a heading + preview + table(s)"** — rendering commentary. Schema retained.
• **§Common Mistakes — rows about previews or rendered output** — rendering-path cautions. Data-level mistakes still apply.

**IMPORTANT — fields that look rendering-adjacent but are NOT skippable:**

• **`renderingStrategy: "A" | "B"`** — required discriminant field. Run the full two-gate decision model.
• `variantProperties`, `modeId`, `collectionId`, `stateColumns`, `stateAxisName` — all part of the schema.
• `compositeChildren` — required; only the frame-visibility recipe is rendering-only.

Step 2: Load `