Accessibility Annotations

Annotate Figma screens with accessibility (AX) annotations so engineers know the reading order, focus order, roles, labels, and alt text for every element.

Work is Figma-first: use the annotation library configured for the project. Never invent components or draw homemade highlight shapes.

Project configuration

This skill is design-system agnostic. Resolve these values before the first write, from the project handoff, the repo, or by asking once:

If the library names components differently (for example Focus Order instead of Order), map them once and record the mapping in the handoff. Everything else in this skill stays the same.

Before you start

1. Load your environment's Figma write skill (for example figma-use) before every Figma write call.
2. Read the project handoff if one exists — it is the canonical status and lists signed-off templates. See handoff-template.md.
3. Confirm the section/screen to annotate. Prefer one screen at a time; wait for user QA before applying to sibling screens.
4. Open the matching user-corrected pattern (see patterns.md) and clone from it. Do not invent denser layouts.

Workflow

Task progress:
- [ ] Identify section + screens
- [ ] Pick pattern (A–I) from the signed-off template
- [ ] Inspect target nodes (texts, controls, existing AX)
- [ ] Clone library / canvas instances (never homemade shapes)
- [ ] Place orders + callouts (gutters, no stacking)
- [ ] Screenshot-verify
- [ ] Update handoff status
- [ ] Stop for user QA

Process rules

1. Sequential Figma writes only — never run parallel write calls on the same file.
2. After the user corrects something, inspect their nodes before touching siblings — their edit is the new source of truth.
3. Clone pre-labeled instances instead of editing text properties on a fresh library instance.
4. If the brand font blocks appendChild or text edits: swap the text to a safe font (for example Inter) → reparent/edit → restore original fills.
5. Parent annotations to the section (or a stable overlay), not deep inside screen chrome, when overlays get messy.
6. Sibling state screens can be leaner — only annotate what is new; shared chrome lives on the primary screen.
7. Prefer less clutter. Never stack annotations on top of each other.

Critical rules (non-negotiable)

Image ≠ Button

• Never put Alt="" on a Button.
• Image/Button label text must keep its original fill colour after any font swap.

Button ≠ Role (no doubles)

• Button = named actions (Close, Back, Clear filters, Try again, …).
• Role = richer traits (accordion, tappable teaser, first card in a grid, filter/checkbox/radio/dismiss chips) and no Button on that control.
• Never pair Button + Role on the same control.

Order markers

• Reading order (gray) = text only. Tab order (red) = reading + focus.
• One continuous number stream across reading and tab markers.
• Default: markers in a side gutter. On-element only when side placement is ambiguous (for example chip grids).
• A single element gets no order markers at all — there is nothing to sequence. Add orders only when the target holds several elements to sequence, or when the user asks for order explicitly.

Single element (component docs)

Annotating one component or card is not annotating a screen. Keep it to the semantics of that element:

Keep Info to one short sentence (for example Entire card is one tappable element.). State wording such as out of stock or disabled belongs in the Label, not in Info.

Placement

• Keep callouts next to their targets; Callout Direction must point at the real control.
• Roles in side gutters; if the left is tight, use the right. Stagger Y.
• Keep Button/Image/Role callouts off screen content when they would hide UI.
• No homemade highlight rectangles, and no library rectangles either unless the user asks. Never use one to group a single element.
• No documentation-only More info notes. Exception: Pattern H Shimmer.

Loading / shimmer (Pattern H)

One More info table — not per-skeleton order markers:

Pattern picker (quick)

Pattern detail: patterns.md. Component kit and tooling gotchas: figma-tooling.md. Handoff format for multi-session work: handoff-template.md.

Role label recipes (filters)

Teaser card (Pattern G) checklist

1. The whole card is one Role — not a separate CTA Button.
2. Direction Left; Value off.
3. Label is the full spoken string (title, price/summary, every tag, in visual order).
4. Info is one short sentence, for example Entire card is one tappable element.
5. Hint is Double tap to activate.
6. Logos and tag icons inside the card → Image Alt=""; skip +N overflow chips.
7. When the card is the whole request: no order markers, no rectangle, no note card.

Figma plugin constraints

• Switch pages with the async page API only, and at most one page switch per call.
• Failed scripts are atomic — diagnose and fix, then retry. Do not blind-retry.
• Do not rely on toast notifications; always return the IDs of created or mutated nodes.
• Do not rely on variable/brand fonts loading successfully for text property writes.

Done criteria (per screen)

• Correct pattern applied; cloned from the signed-off template when one exists
• Image vs Button correct; no Button+Role doubles
• Orders continuous; gutters clean; no stacking
• Callouts close to targets with the correct Direction
• Screenshot looks clean next to neighbouring screens
• Handoff updated; waiting on user QA before siblings