Flutter Semantics and Accessibility Testing
Verify Flutter widget semantics, focus, reading order and gestures with accessibility tests and screen readers. Use for custom widgets, regressions or screen-reader interaction failures.
Write the user journey in terms of what assistive technology must announce and allow. For a custom filter, name the control, its role, current value and disabled/selected state, then specify how to open it, change a value and return to the previous screen. Use an appropriate built-in Flutter control if it already exposes the correct interaction. ## Key Points - [Flutter accessibility testing](https://docs.flutter.dev/ui/accessibility/accessibility-testing) - [Flutter semantic debugger and instrumentation](https://docs.flutter.dev/testing/code-debugging) - [WCAG 2.2 pointer alternatives and keyboard requirements](https://www.w3.org/TR/WCAG22/?KBOpenTab=undefined)
skilldb get flutter-skills/flutter-semantics-accessibilityFull skill: 29 linesFlutter Semantics and Accessibility Testing
Write the user journey in terms of what assistive technology must announce and allow. For a custom filter, name the control, its role, current value and disabled/selected state, then specify how to open it, change a value and return to the previous screen. Use an appropriate built-in Flutter control if it already exposes the correct interaction.
Inspect the semantics users receive
Look at the semantics tree and compare it with the visible UI. For a custom interactive widget, expose a useful label, state and appropriate supported semantic actions. Keep a coherent single control when a text label and decorative icon belong together, and keep genuinely distinct actions independently reachable. Merging descendants may hide a second action. Exclude decorative content only where it conveys no information and avoid announcing both an icon label and the equivalent visible text.
Check traversal and keyboard focus independently. Verify that reading order follows the task through meaningful elements even after conditional content changes. Verify that external keyboard focus reaches every actionable control, has a visible indicator and returns to a predictable target after dialogs or navigation. Dragging, long press or a custom gesture needs a usable alternate control where the core operation would otherwise be inaccessible. Dynamic errors should be discoverable without reading the full screen again.
Use tests that can actually fail
In widget tests, enable semantics for the test duration, assert the control's label, role, state and action, and dispose of the handle. Use Flutter's Accessibility Guideline API for applicable target labels, dimensions and contrast. Check changes under enlarged text and localization, including whether visible and spoken information still agree. Include a known broken control with a missing label or incorrect traversal as a regression control.
Use TalkBack and VoiceOver for the complete journey on supported platforms. Verify real speech and activation, reading order on a new route, focus restoration and any changed values. For Flutter web, also inspect the browser accessibility representation and test the target browser/assistive technology combinations. Record actual devices, versions, results and failure evidence. A widget guideline pass does not establish screen-reader behavior on a device or full accessibility conformance.
References and rights
- Flutter accessibility testing
- Flutter semantic debugger and instrumentation
- WCAG 2.2 pointer alternatives and keyboard requirements
Original SkillDB instructions under LicenseRef-SkillDB-Content. References were checked 2026-11-13 and used for technical verification.
Install this skill directly: skilldb add flutter-skills
Related Skills
Profile Flutter Startup and Frame Performance
Measure Flutter mobile startup and rendering on physical devices in profile mode, distinguish UI and raster work, and verify fixes against comparable traces.
Local Storage
Hive, SharedPreferences, and Drift patterns for local data persistence in Flutter
Manage Flutter and Dart Monorepos with Melos
Set up Dart Pub workspaces and Melos for local package resolution, scoped scripts, and predictable verification across dependent Flutter packages.
Navigation
GoRouter navigation patterns for declarative, deep-linkable Flutter routing
Networking
Dio HTTP client and API integration patterns for Flutter applications
Platform Channels
Platform channels for bridging Flutter with native Android (Kotlin) and iOS (Swift) code