Screen reader specs document how assistive technologies should announce and interact with your component across iOS (VoiceOver), Android (TalkBack), and Web (ARIA).
What you need
- A Figma link to the component
- A description of states, behaviors, or interactive parts that aren’t visible in the design
Describe all interactive parts and how they relate. For example: “The label and hint merge into the input’s announcement, but the trailing clear button is a separate focus stop.” This helps the agent determine focus order accurately.
When to use
Create a screen reader spec when you need to document:
- How a component should be announced by screen readers
- Focus order for components with multiple interactive parts
- Platform-specific accessibility properties
- How announcements change across states (enabled, disabled, selected)
What the agent generates
The agent analyzes your component’s visual parts, determines which are independent focus stops vs. merged into another element’s announcement, and produces per-platform documentation.
Simple vs. compound components
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.
Components with multiple independently focusable elements.Examples: Text field with trailing clear button, Chip with dismiss action, Tab barThe output includes a focus order section showing the traversal sequence, plus per-state documentation for each stop.
| 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 |
Example prompts
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
