extract-voice

# Extract Voice / Screen Reader Data

Interpretation-only companion to `create-voice`. 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-voice`, and writes the finalized `VoiceSpecData` object to disk for the `create-component-md` orchestrator.

**Quality contract:** every reasoning step (visual parts listing, merge analysis, focus-stop counting, state grouping with `A11Y_AXES` filter, behavioral state detection, slot scenario selection, state-to-variant mapping, platform section population, audit) mirrors `create-voice/SKILL.md` and its platform reference files.

**Batch-mode contract.** This skill MUST NOT call `AskQuestion`, prompt for confirmation, or pause for user input. Behavioral states are inferred from `optionalContext` and platform defaults; if a state can't be inferred, omit it rather than asking. On missing `_base.json` sections, abort with a single-line diagnostic. 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 user context. **Especially important for voice specs** — behavioral states ("single-select vs multi-select", "collapsed vs expanded", "validation error") are typically only discoverable from user context.
- `mcpProvider` — `figma-console` or `figma-mcp` (only needed if a Step 3-delta escape hatch fires AND a live Figma link was provided to the orchestrator)
- `deltaAvailable` — boolean. When the orchestrator received only a `baseJsonPath` (no `figmaLink`), this is `false` and the Step 3-delta escape hatch must not fire; log the gap in `data._deltaExtractions[]` with `unavailable: "no-figma-link"` and continue with best-effort output.
- `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.

`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}-voice.json` with a `{ _meta, data }` envelope. `data` follows the `VoiceSpecData` shape (`componentName`, `guidelines`, optional `focusOrder`, `states[]`).
- Returns a single-line summary: `"Voice extracted: N focus stops, M states, platforms=[VoiceOver, TalkBack, ARIA] → {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`:

```javascript
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 and platform reference files
- [ ] Step 2: Load _base.json and optionalContext
- [ ] Step 2.5: Load API dictionary (canonical vocabulary) — optional
- [ ] Step 3: Build working evidence set (elements, slotDefs, slotVisibility from _base.json)
- [ ] Step 3-delta: OPTIONAL — read-only Figma call if a fact is genuinely missing
- [ ] Step 4: Visual parts, merge analysis, focus stops (+ retain layerName per stop), states, slot scenarios
- [ ] Step 5: Generate VoiceSpecData (guidelines, focusOrder, states with 3 platform sections)
- [ ] Step 6: Audit (re-read instruction file)
- [ ] Step 7: Write JSON to cache and return one-line summary
```

### Step 1: Read References

Read these files before generating output:
- [agent-screenreader-instruction.md]({{ref:screen-reader/agent-screenreader-instruction.md}}) — main instructions
- [voiceover.md]({{ref:screen-reader/voiceover.md}}) — iOS VoiceOver patterns
- [talkback.md]({{ref:screen-reader/talkback.md}}) — Android TalkBack patterns
- [aria.md]({{ref:screen-reader/aria.md}}) — Web ARIA patterns

These are the **same** references used by `create-voice`. They are the single source of truth for the `VoiceSpecData` schema, merge analysis, state grouping, announcement patterns, and the Validation Checklist.

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

- **§Analysis Process — "The rendering script uses visibility-aware focus stop resolution for the Focus Order artwork…"** — rendering path. The preceding guidance about flagging conditional focus stops still applies.
- **§Validation Checklist — the entire "After Rendering in Figma" sub-section** — rendering-only. Replace in-mind with the extraction-side audit in Step 6.
- **§Validation Checklist — the "Before Rendering in Figma" sub-section** — DO still apply.
- **§Examples — narrative references to rendered output** — example data shapes still apply; rendered-table narration is irrelevant.

Note: Fields that look like rendering config but are part of the output schema (e.g., `slotInsertions`, `focusOrder.tables`, `variantProps`, per-state `sections`) must still be populated.

### Step 2: Load `_base.json`

Read `{cachePath}/{componentSlug}-_base.json`. If missing or required sections are `null`, abort with a diagno