macOS accessibility
Read references/accessibility-checklist.md for every user-interface feature, custom control, image, animation, chart, drag-and-drop interaction, or input workflow.
Workflow
- Define the label, value, hint, traits, actions, grouping, and heading level before visual styling.
- Prefer native controls, which provide system behaviour and accessibility semantics.
- Test flexible layout with the largest supported macOS text and accessibility settings.
- Verify VoiceOver order, focus, actions, and announcements.
- Verify that Voice Control uses visible, stable names.
- Check light and dark appearance, Increase Contrast, Reduce Transparency, and Differentiate Without Color.
- Check Reduce Motion for spatial or repeated animation.
- Test keyboard navigation, Full Keyboard Access, pointer and hover, menu and toolbar access, drag-and-drop alternatives, and focus after state changes.
- Record manual checks that cannot be automated.
Guardrails
- An icon-only button still needs a text label. Use
Button("Label", systemImage: ...) and apply .labelStyle(.iconOnly) only to the visual presentation.
- Hide decorative images. Give meaningful images concise labels or descriptions.
- Use
Button for ordinary actions. Use gestures only when tap count, position, or movement is part of the action, and add matching accessibility actions.
- Never communicate state through colour alone.
- Pointer targets must be easy to acquire, and every action needs a keyboard and accessibility-focus path.
- Use semantic text styles. Scale any necessary custom dimensions with the relevant text style.
- Provide a reduced-motion alternative for large spatial movement.
Output
Report the affected assistive technology or setting, macOS version, window state, consequence, correction, and exact manual verification steps. Classify unreachable or unnamed actions as blockers.
1---2name: apple-accessibility3description: Implement or audit macOS SwiftUI accessibility across VoiceOver, Voice Control, keyboard navigation, Full Keyboard Access, text scaling, contrast, motion, focus, and pointer input.4license: MIT5---67# macOS accessibility89Read `references/accessibility-checklist.md` for every user-interface feature, custom control, image, animation, chart, drag-and-drop interaction, or input workflow.1011## Workflow12131. Define the label, value, hint, traits, actions, grouping, and heading level before visual styling.142. Prefer native controls, which provide system behaviour and accessibility semantics.153. Test flexible layout with the largest supported macOS text and accessibility settings.164. Verify VoiceOver order, focus, actions, and announcements.175. Verify that Voice Control uses visible, stable names.186. Check light and dark appearance, Increase Contrast, Reduce Transparency, and Differentiate Without Color.197. Check Reduce Motion for spatial or repeated animation.208. Test keyboard navigation, Full Keyboard Access, pointer and hover, menu and toolbar access, drag-and-drop alternatives, and focus after state changes.219. Record manual checks that cannot be automated.2223## Guardrails2425- An icon-only button still needs a text label. Use `Button("Label", systemImage: ...)` and apply `.labelStyle(.iconOnly)` only to the visual presentation.26- Hide decorative images. Give meaningful images concise labels or descriptions.27- Use `Button` for ordinary actions. Use gestures only when tap count, position, or movement is part of the action, and add matching accessibility actions.28- Never communicate state through colour alone.29- Pointer targets must be easy to acquire, and every action needs a keyboard and accessibility-focus path.30- Use semantic text styles. Scale any necessary custom dimensions with the relevant text style.31- Provide a reduced-motion alternative for large spatial movement.3233## Output3435Report the affected assistive technology or setting, macOS version, window state, consequence, correction, and exact manual verification steps. Classify unreachable or unnamed actions as blockers.
rcarmo