WCAG Semantics Label Resolver
Component Detail
Description
Infrastructure utility that bridges the terminology system with Flutter's Semantics tree to satisfy WCAG 2.2 AA requirements. Provides helper methods for wrapping widgets with Semantics nodes whose labels and hints are resolved through the active terminology map, ensuring screen readers announce organization-specific role and action names correctly.
wcag-semantics-label-resolver
Summaries
The WCAG Semantics Label Resolver ensures the application meets WCAG 2.2 AA accessibility standards, a legal and ethical requirement for organizations serving users who rely on screen readers and assistive technologies. Beyond compliance, accessible software expands the addressable user base and signals organizational commitment to inclusive design — a factor increasingly evaluated in enterprise procurement. Critically, this component connects accessibility to the terminology customization system, meaning screen readers announce the same role names and action labels that the organization has configured, not generic defaults. This coherence matters for users with disabilities who are just as subject to each organization's specific vocabulary as sighted users, and ensures the accessibility layer does not become a second-class experience.
This is a low-complexity infrastructure utility, but its delivery has cross-cutting implications for the entire widget tree. Every interactive widget that uses a terminology-resolved label must pass through this component to remain WCAG 2.2 AA compliant, which means accessibility testing cannot be siloed — it must be integrated into the review process for every UI feature. The `assertAccessibleLabel` validation method enables automated accessibility assertions in widget tests, which should be adopted as a team standard to prevent regressions. Dependencies on `label-key-resolver` and `organization-labels-notifier` must both be stable before end-to-end accessibility testing is meaningful.
Budget time for screen-reader testing on real devices (iOS VoiceOver, Android TalkBack) in addition to unit-level assertions, as Semantics tree behavior can differ from unit test outcomes.
This utility bridges Flutter's `Semantics` widget API with the live terminology map. `semanticsLabel(key)` performs a synchronous lookup against the currently loaded organization labels, returning the resolved string for use in `Semantics(label: ...)` nodes. `withSemantics(widget, labelKey, {hintKey})` is the primary composition helper — it wraps any widget in a `Semantics` node whose label and optional hint are both terminology-resolved, keeping widget code free of direct label lookups. `liveRegion(widget, labelKey)` wraps dynamic content in an assertive `Semantics(liveRegion: true)` node, ensuring screen readers announce terminology updates when the active map changes.
`assertAccessibleLabel(key, map)` is intended for use in widget tests to verify semantic coverage. Depends on `organization-labels-notifier` being initialized before first render; guard with `AsyncValue` handling in parent widgets.
Responsibilities
- Wrap widgets in Semantics nodes with terminology-resolved labels
- Resolve semantic hints and button descriptions through the label system
- Provide assertive live-region helpers for dynamic terminology updates
- Validate that all interactive widgets have a resolved semantic label
Interfaces
semanticsLabel(key) → String
withSemantics(widget, labelKey, {hintKey}) → Widget
liveRegion(widget, labelKey) → Widget
assertAccessibleLabel(key, map) → bool
Relationships
Dependencies (2)
Components this component depends on