What you need
- A component
.mdproduced bycreate-component-md(run it first —create-component-mdneeds a_base.jsonfrom the uSpec Extract plugin). Tell the skill where this.mdlives —components/<slug>.mdis onlycreate-component-md’s default output path; the file can live anywhere. Without it this skill aborts. - Figma MCP connected (Console MCP with Desktop Bridge, or native Figma MCP) — used only to render the frame.
- A description of states/behaviors is captured upstream by
create-component-md; nothing extra is needed here.
How to use
Reference the skill and pass the component.md. Add a render destination or any extra context the spec can’t carry:
- Cursor
- Claude Code
- Codex
What it generates
The agent analyzes your component’s visual parts, determines which are independent focus stops vs. merged into another element’s announcement, and renders per-platform documentation directly in your Figma file.Simple vs. compound components
- Simple (1 focus stop)
- Compound (2+ focus stops)
Components where all parts merge into a single focusable element.Examples: Button, Checkbox with label, Switch, ToggleThe output documents one focus stop per state, with platform-specific properties for each.
Platform properties
Each focus stop is documented with platform-specific properties:| Platform | Key properties |
|---|---|
| iOS (VoiceOver) | accessibilityLabel, accessibilityTraits, accessibilityHint, accessibilityValue |
| Android (TalkBack) | contentDescription, role, stateDescription |
| Web (ARIA) | role, aria-label, aria-describedby, aria-expanded |
Merge analysis
The agent determines how visual parts combine for accessibility:| Visual part | Typical behavior |
|---|---|
| Label | Merges into the control’s announcement |
| Hint text | Becomes the accessibility hint or description |
| Decorative icons | Hidden from screen readers |
| Functional icons (e.g., clear button) | Separate focus stop |
| Action buttons | Separate focus stop |
How it works
The screen reader skill is heavily AI-driven — the agent determines merge behavior, focus order, and platform-specific properties, while deterministic scripts handle template rendering and layout. 30% Deterministic 70% AI ReasoningRequire the .md
The skill requires
components/<slug>.md (produced by create-component-md) and fails fast if it is missing — it does not re-extract from Figma.Parse the Voice section
The skill parses the
.md’s Voice section (guidelines, focus order, per-state platform tables) plus the render-meta block and the hidden voice-render-meta focus-stop layer-name carry.Build render inputs
Sections, focus stops (by Figma layer name), variant props, boolean defs, and slot insertions are assembled directly from the parsed
.md — no live extraction walk.Import template
The screen reader documentation template is imported from the library, instantiated, and detached into an editable frame.
Render
The skill fills header fields, builds focus order diagrams, state tables, and per-platform property sections, placing markers by name-match + live bbox on the rendered instance.
Tips for better output
- List all states: enabled, disabled, selected, expanded, loading. The agent can’t infer states it can’t see in Figma
- Describe interactive parts and merge behavior: explain which elements are tappable, which are decorative, and which should merge into another element’s announcement. For example: “The label and hint merge into the input’s announcement, but the trailing clear button is a separate focus stop”
- Mention reactive elements: error messages, status updates, and toasts are announced as live regions, not focus stops. Call them out if they’re part of your component
- Note focus order preferences: if the traversal order matters (e.g., input before clear button), describe it
- Describe state-specific announcements: if the announcement changes based on state (e.g., a switch announcing “on” vs “off”), mention it