Semantics Service Facade
Component Detail
Description
Abstracts Flutter's SemanticsService and platform accessibility APIs behind a unified interface to simplify testing and enable consistent announcement behaviour across iOS and Android. Provides helper methods for the most common announcement patterns used throughout the app.
semantics-service-facade
Summaries
The Semantics Service Facade is a shared infrastructure component that ensures screen reader announcements work correctly and consistently for users on both iPhone and Android devices, regardless of the underlying platform differences between Apple VoiceOver and Google TalkBack. Without this abstraction, accessibility announcement behaviour would need to be duplicated and maintained separately for each platform, increasing the risk of regressions and inconsistencies that directly harm users with visual impairments. By centralising this logic, the product team can confidently ship accessibility features knowing they will behave as intended across the full device landscape. The test mode support also means quality assurance of accessibility behaviour is automated and reliable, reducing manual testing overhead and the likelihood that accessibility regressions reach production users.
As a shared, medium-complexity component with no external dependencies, the Semantics Service Facade should be prioritised early in the delivery sequence since it is a dependency for the Accessibility Test Harness and potentially other announcement-dependent features. Medium complexity arises from the need to handle platform-specific announcement differences between iOS VoiceOver and Android TalkBack, which may require device-specific testing. The setTestMode interface is critical for enabling automated testing of announcement sequences — confirm with QA that this is integrated into the test harness before those tests are authored. Deployment considerations are limited since this is a mobile-only, in-process component with no network or backend dependencies.
Main risk is subtle platform divergence in announcement timing or queuing behaviour, which should be validated on real devices rather than simulators only.
Semantics Service Facade wraps Flutter's SemanticsService.announce() and platform accessibility channel calls behind a unified interface, enabling announcement logic to be written once and tested without platform conditionals scattered across the codebase. The isEnabled() method should query the platform accessibility state (via ServicesBinding.instance.accessibilityFeatures) to allow callers to gate announcements appropriately. The getActiveReader() method should return an enum distinguishing VoiceOver, TalkBack, or None, enabling locale-aware announcement formatting where necessary. The setTestMode(bool) method should swap the underlying SemanticsService call for an in-memory announcement queue, enabling verifyAnnouncement assertions in the Accessibility Test Harness without requiring a real accessibility service to be active.
flushAnnouncements() should drain that queue and is essential for deterministic test teardown. As a shared component, maintain strict backwards compatibility on all public interfaces.
Responsibilities
- Wrap SemanticsService.announce() with platform-aware behaviour
- Provide testable interfaces for unit and integration tests
- Handle platform differences between VoiceOver and TalkBack announcement APIs
- Support locale-aware announcement formatting
Interfaces
announce(message, textDirection)
announceForAccessibility(message)
isEnabled()
getActiveReader()
setTestMode(bool)
flushAnnouncements()