Document UI components and accessibility patterns

epic-dynamic-terminology-and-labels-ui-and-accessibility-task-013 — Write developer documentation covering: (1) how to use TerminologyAwareTextWidget as a drop-in replacement for Flutter's Text widget with labelKey and fallback parameters, (2) how to wrap interactive widgets with WcagSemanticsLabelResolver to satisfy WCAG 2.2 AA requirements with organization-specific semantics, and (3) how coordinators use the TerminologyAdminPreviewScreen to validate their organization's terminology configuration. Include code examples for all three components and a migration guide for replacing hardcoded Text widgets.

medium priority low complexity documentation pending documentor Tier 5

Acceptance Criteria

Documentation covers all three components: TerminologyAwareTextWidget, WcagSemanticsLabelResolver, and TerminologyAdminPreviewScreen

Each component section includes: purpose, constructor parameters with types and descriptions, at least one complete Dart code example, and known limitations or gotchas

TerminologyAwareTextWidget section explains labelKey, fallback, and any style passthrough parameters with examples showing both basic and styled usage

WcagSemanticsLabelResolver section explains WCAG 2.2 AA compliance context, when to use it vs native Semantics widget, and a before/after code example

TerminologyAdminPreviewScreen section is written for coordinators (non-technical audience): step-by-step usage guide with screenshots or ASCII diagrams if no screenshots available

Migration guide provides a step-by-step checklist for replacing hardcoded Text('Likeperson') widgets with TerminologyAwareTextWidget(labelKey: 'peer_mentor')

Migration guide includes a grep pattern or IDE search strategy to locate all hardcoded strings eligible for migration

Documentation is stored in the project's standard docs location (e.g., docs/ or inline as dartdoc comments on the widget classes)

All code examples are syntactically valid Dart/Flutter and consistent with the project's existing code style

Technical Requirements

frameworks

Flutter

Dart

Riverpod

apis

TerminologyAwareTextWidget API

WcagSemanticsLabelResolver API

LabelKeyRegistry (key enumeration for migration guide)

data models

LabelKeyEntry (for migration guide key reference table)

performance requirements

Documentation must not include performance anti-patterns in code examples (e.g., provider reads inside build loops)

security requirements

Code examples must not include hardcoded org IDs, API keys, or PII in any form

Execution Context

Execution Tier

Tier 5

Tier 5 - 253 tasks

Can start after Tier 4 completes

View Full Execution Plan

Implementation Notes

Write dartdoc comments directly on the widget classes as the primary documentation — this surfaces the docs in IDEs and via 'dart doc'. Supplement with a docs/terminology-system.md file for the coordinator usage guide and the migration checklist, as dartdoc is not suitable for non-technical audiences. The migration guide grep pattern should be: grep -rn 'Text(' lib/ --include='*.dart' | grep -v 'AppText\|TerminologyAware' — document this exact command. For the WCAG 2.2 AA section, reference the specific WCAG criteria (1.1.1 Non-text Content, 4.1.2 Name, Role, Value) to give developers context on why this wrapper is required.

Keep code examples minimal — prefer showing the simplest valid usage first, then one advanced example. Do not write documentation for how Riverpod providers work internally; link to the existing Riverpod docs instead.

Testing Requirements

Documentation is not directly tested, but code examples must be validated: copy each Dart code example into a scratch test file and confirm it compiles without errors via 'flutter analyze'. If dartdoc comments are used, run 'dart doc' and verify zero warnings for the documented classes. Peer review by one other developer to confirm examples are accurate and the migration guide steps are reproducible.

Component

Terminology Admin Preview Screen

ui low

Dependencies (1)

Write integration tests (flutter_test + integration_test package) that simulate a full terminology resolution flow across all three UI components. Test scenario: switch active organization from NHF to Blindeforbundet, verify TerminologyAwareTextWidget re-renders with new labels, verify WcagSemanticsLabelResolver updates its Semantics node, and verify TerminologyAdminPreviewScreen shows the correct resolved values and missing entry count for each organization's map. epic-dynamic-terminology-and-labels-ui-and-accessibility-task-012

Epic Risks (3)

high impact medium prob integration

WcagSemanticsLabelResolver's Semantics wrappers may conflict with Semantics nodes already defined by existing accessible widgets (e.g., accessible-bottom-navigation, activity-wizard-semantics), causing duplicate or contradictory screen reader announcements that fail WCAG 2.2 AA criteria.

Mitigation & Contingency

Mitigation: Audit all existing Semantics-annotated widgets in the accessibility feature before implementing WcagSemanticsLabelResolver. Define a clear hierarchy rule: WcagSemanticsLabelResolver always merges with, never replaces, existing Semantics nodes. Use Flutter's debugSemantics output in CI to detect conflicts automatically.

Contingency: If conflicts are discovered in testing, introduce a resolverMode parameter to WcagSemanticsLabelResolver allowing it to operate in 'override' or 'merge' mode per call site; coordinate with the Screen Reader Support feature team to align Semantics strategies.

medium impact medium prob technical

If TerminologyAwareTextWidget subscribes to the full terminology map provider rather than the per-key labelProvider family, a single label update will trigger a full widget-tree rebuild across all screens simultaneously, causing jank on devices used by older peer mentors.

Mitigation & Contingency

Mitigation: Implement TerminologyAwareTextWidget using ref.watch(labelProvider(key)) on the per-key family provider from TerminologyRiverpodProviders so that only widgets bound to the changed key rebuild. Verify with Flutter DevTools 'rebuild tracking' in widget tests.

Contingency: If full-map subscriptions slip through code review, add a Riverpod lint rule that flags direct organizationLabelsNotifierProvider subscriptions inside widget build methods and enforces the per-key family pattern.

medium impact low prob security

The TerminologyAdminPreviewScreen requires coordinator-level access, but if role checks rely solely on client-side guard logic without matching Supabase RLS policies, a peer mentor could potentially access the admin preview by manipulating navigation state.

Mitigation & Contingency

Mitigation: Protect the admin preview route with a server-validated role guard that re-fetches the user's role from Supabase on screen initialization, not just from local state. Add a Supabase RLS policy that restricts label map read access for the admin preview endpoint to coordinator and admin roles only.

Contingency: If unauthorized access is discovered in testing, immediately add a middleware role assertion that redirects non-coordinators to the no-access screen and logs the unauthorized navigation attempt for audit.

Quick Links

All Tasks Execution Plan