Terminology-Aware Text Widget
Component Detail
Description
A drop-in replacement for Flutter Text widgets that automatically resolves label keys through the active organization's terminology map. Accepts a label key and optional fallback string, consuming the OrganizationLabelsNotifier via Riverpod to render the correct localized term. Ensures WCAG 2.2 AA Flutter semantics labels also resolve through this system.
terminology-aware-text-widget
Summaries
The Terminology-Aware Text Widget allows each client organization to use its own preferred vocabulary throughout the app — for example, one organization may call participants 'residents' while another uses 'clients' or 'members'. This level of personalization significantly increases user adoption and reduces training friction, as staff interact with language that matches their existing workflows and documentation. It also ensures the app meets WCAG 2.2 AA accessibility requirements automatically, reducing legal and compliance risk. As a shared drop-in replacement for standard text elements, it delivers this personalization benefit across the entire application without requiring per-organization development work.
This is a low-complexity shared UI component that, once delivered, must be adopted consistently across all screens to provide value — partial adoption creates inconsistent terminology experiences. A good approach is to require its use in the component standards documentation and enforce it during code review from the outset. It depends on OrganizationLabelsNotifier being available in the Riverpod provider scope, so that provider must be initialized before any screen using this widget renders. Testing should cover: correct resolution for known keys, fallback rendering for unknown keys, reactive rebuild when the terminology map is reloaded, and correct Semantics label output for accessibility audits.
TerminologyText(labelKey, fallback) is a StatelessWidget that watches OrganizationLabelsNotifier via ref.watch (Riverpod ConsumerWidget) and calls resolveLabel(key) to return the organization-specific string, falling back to the provided default if the key is absent from the map. TerminologySemanticLabel wraps Flutter's Semantics widget so screen readers announce resolved terminology rather than raw keys. Because it uses ref.watch, widgets automatically rebuild when the notifier emits a new terminology map (e.g., on org switch). The resolveLabel function should be a pure static utility testable in isolation.
Avoid using this widget inside const constructors — it must remain reactive. For rich text scenarios, TerminologyRichText accepts a list of spans where each span resolves its own key independently.
Responsibilities
- Resolve label keys to organization-specific display strings
- Apply Flutter Semantics labels using resolved terminology
- Render fallback text when a key is missing from the map
- Reactively rebuild when the terminology map changes
Interfaces
TerminologyText(labelKey, fallback)
TerminologyRichText(spans)
TerminologySemanticLabel(labelKey)
resolveLabel(key) → String