Accessibility annotation generator · free AI skill

Generates complete accessibility annotations for a UI component or screen — ARIA roles and labels, focus order sequence, keyboard interaction specs, screen reader announcements, and WCAG success criteria references…

Purpose

Turn a plain-language component or screen description into a complete, developer-ready accessibility annotation set — ARIA roles and labels, focus order, keyboard interactions, screen reader announcements, and mapped WCAG criteria — so engineering builds accessible components on the first pass instead of retrofitting after an audit.

When to Use

Invoke this skill when the user asks to:

Annotate a component or screen for accessibility before engineering handoff
Generate ARIA labels, roles, and states for a UI element
Define focus order or keyboard navigation for a screen or flow
Specify screen reader announcements for a component
Document accessibility requirements in a Figma handoff or spec doc
Map a component's behavior to WCAG success criteria

Inputs Required

Before starting, collect:

Component/screen description: What it is and what it does (e.g., "a modal dialog with a form and a close button")
Interactive elements: Buttons, inputs, links, toggles, menus present in the component
States and dynamic behavior: Anything that changes — expand/collapse, loading, error, selected, disabled
Platform: Web (HTML/ARIA) / iOS (UIKit/SwiftUI) / Android / React Native
Content in the component: Labels, headings, placeholder text, icon-only actions
Target WCAG level: A / AA / AAA (default AA if not specified)

If platform is not specified, default to Web/ARIA. If the description omits states, ask one clarifying question about dynamic behavior before generating.

Instructions

Step 1: Decompose the Component into Annotatable Elements

Break the component into a flat list of every element that needs an accessibility annotation:

Structural elements: Landmarks, headings, groups, regions
Interactive elements: Buttons, links, inputs, selects, toggles, tabs, menu items
Dynamic elements: Anything that changes state or content, and any live regions
Decorative elements: Icons, images, or dividers that should be hidden from assistive tech

For each, note whether it is a native semantic element (preferred) or requires ARIA to convey role/state.

Step 2: Assign Roles, Names, and States

For every interactive and structural element, specify:

Role: Native element or ARIA role (e.g., <button> over role="button"; use ARIA only when no native element fits)
Accessible name: The exact label a screen reader announces — resolved via visible text, aria-label, or aria-labelledby
States/properties: aria-expanded, aria-selected, aria-checked, aria-disabled, aria-current, aria-invalid, aria-describedby as applicable
Icon-only actions: Provide the explicit aria-label text, never rely on the icon alone
Decorative elements: Mark as aria-hidden="true" or empty alt=""

Prefer native HTML semantics first; document the ARIA fallback only when the platform or design forces it.

Step 3: Define Focus Order and Keyboard Interactions

Specify the tab sequence and key behaviors:

Focus order: Numbered sequence of focusable elements, matching logical reading order (not visual DOM order if they differ — flag the mismatch)
Focus management: Where focus moves on open/close (e.g., modal opens → focus first field; modal closes → focus return to trigger)
Focus trap: Note where focus must be contained (modals, menus) and how it exits (Escape)
Keyboard interactions per element: Enter/Space to activate, Arrow keys for composite widgets (tabs, menus, radio groups), Escape to dismiss
Visible focus indicator: Confirm a non-color-only focus indicator is required

Follow the WAI-ARIA Authoring Practices keyboard patterns for any composite widget (tabs, combobox, menu, dialog, disclosure).

Step 4: Specify Screen Reader Announcements

Write the exact announced experience for key moments:

On focus: What is read when each interactive element receives focus (name + role + state)
On state change: What is announced when a state changes (e.g., "Expanded" / "Collapsed")
Live regions: For dynamic content (errors, toasts, loading, results), specify aria-live="polite" or "assertive" and the announced text
Error handling: How field errors are announced and associated (aria-describedby + aria-invalid)

Step 5: Map to WCAG Success Criteria

For each significant annotation, reference the relevant WCAG 2.2 success criterion by number and name (e.g., 1.3.1 Info and Relationships, 2.4.3 Focus Order, 2.1.1 Keyboard, 4.1.2 Name Role Value, 1.4.3 Contrast, 2.4.7 Focus Visible). Flag any criterion the current description cannot satisfy and note what the design must add.

Step 6: Assemble the Annotation Document

Produce a single handoff-ready document combining an element annotation table, the focus order list, keyboard interaction spec, screen reader announcement notes, and an open-questions section for anything the design left ambiguous.

Output Format

Structure: Element-by-element annotation table, followed by focus order list, keyboard spec, screen reader announcements, WCAG mapping, and open questions
Length: 700–1,100 words depending on component complexity
Format: Structured document — annotation table plus labeled sections; code-style formatting for attributes and roles
Sections: Component Summary → Element Annotations (table) → Focus Order → Keyboard Interactions → Screen Reader Announcements → WCAG Criteria Map → Open Questions for Engineering
Tone: Accessibility specialist writing for developers — precise, implementation-oriented, no hand-waving; every annotation is directly buildable

Quality Checklist

Before delivering output, verify:

[ ] Every interactive element has a role, accessible name, and applicable states specified
[ ] Focus order is a numbered sequence and flags any visual-vs-DOM order mismatch
[ ] Every icon-only or non-text control has an explicit accessible name — no reliance on visuals
[ ] Focus management on open/close is specified for any overlay, modal, or menu
[ ] Each dynamic/state-change behavior has a screen reader announcement and live-region setting where needed
[ ] Each significant annotation references a WCAG 2.2 success criterion by number and name

Notes

Native semantic elements are always preferred over ARIA — the first rule of ARIA is don't use ARIA when HTML can do the job. Document ARIA only as a documented fallback.
The single most common handoff gap is focus management on modals and dynamic content — specify it explicitly even when the design "looks obvious."
For composite widgets (tabs, comboboxes, menus, date pickers), anchor keyboard behavior to the WAI-ARIA Authoring Practices patterns rather than inventing interactions.
Contrast and target-size criteria depend on visual specs the annotation can't verify alone — flag these as design-side confirmations rather than asserting compliance.

How to use this skill

This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.

Installing in Claude Code:

~/.claude/skills/<folder-name>/SKILL.md — auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)
<your-project>/.claude/skills/<folder-name>/SKILL.md — auto-loads only when working in that project (recommended for project-specific skills)

Restart Claude Code or open a new session to register.

Using in Claude.ai, ChatGPT, Gemini, or other AI tools:

Drag this file into a new chat, or copy and paste its contents
Send your task or request as your next message — the AI will apply the skill where it fits

For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills