Build Dynamic Type Scale Service

epic-visual-design-accessibility-services-and-widgets-task-006 — Implement the DynamicTypeScaleService that reads the OS textScaleFactor via MediaQuery and maps it to per-role layout budgets expressed as maxLines and fontSize cap values. Must prevent text overflow at 200% system font scale for all TextTheme roles (bodyMedium, labelLarge, etc.). Provide a Riverpod provider that rebuilds when textScaleFactor changes and exposes ScaledTypeBudget objects per role.

critical priority medium complexity backend pending backend specialist Tier 2

Acceptance Criteria

DynamicTypeScaleService exposes getBudget(TextThemeRole role) returning a ScaledTypeBudget synchronously

ScaledTypeBudget contains: int maxLines, double fontSizeCap, bool allowSoftWrap, double lineHeightMultiplier

TextThemeRole enum covers all Material 3 TextTheme roles: displayLarge/Medium/Small, headlineLarge/Medium/Small, titleLarge/Medium/Small, bodyLarge/Medium/Small, labelLarge/Medium/Small

At textScaleFactor 1.0, budgets match the design token baseline (no caps applied)

At textScaleFactor 2.0 (200%), no TextTheme role causes single-line text overflow in a standard 375pt-wide viewport — verified by golden test or widget test with constrained width

fontSizeCap values are defined in a static budget table (not computed dynamically) to ensure deterministic layout

Riverpod provider dynamicTypeScaleBudgetProvider(TextThemeRole) family provider rebuilds automatically when MediaQuery.textScaleFactorOf changes

Service does not hold a BuildContext reference — textScaleFactor is passed as a constructor/method parameter

All budget table values are documented with the design rationale (e.g., displayLarge capped at 40sp at 200% to prevent hero text overflow)

Widget tests confirm that Text widgets consuming budgets via the provider do not overflow at 150% and 200% scale

Technical Requirements

frameworks

Flutter

Dart (latest)

Riverpod

apis

MediaQuery.textScaleFactorOf(context)

Flutter TextTheme

Flutter TextStyle

data models

ScaledTypeBudget (maxLines: int, fontSizeCap: double, allowSoftWrap: bool, lineHeightMultiplier: double)

TextThemeRole (enum for all M3 TextTheme roles)

TypeScaleBudgetTable (static map of role × scaleFactor bracket → ScaledTypeBudget)

performance requirements

getBudget() must be O(1) — pure table lookup, no computation

Provider rebuild must not cause jank — budget calculation is synchronous and cheap

security requirements

No external data sources — budget table is compile-time constant

ui components

ScaledText (optional convenience widget that consumes the provider and applies budget automatically)

Execution Context

Execution Tier

Tier 2

Tier 2 - 518 tasks

Can start after Tier 1 completes

View Full Execution Plan

Implementation Notes

Place service in lib/core/accessibility/dynamic_type_scale_service.dart. The key design decision is using a static lookup table (Map>) with bracket thresholds (e.g., <=1.0, <=1.5, <=2.0, >2.0) rather than a linear formula. This gives designers explicit control over breakpoints. Use a family provider: final dynamicTypeBudgetProvider = Provider.family((ref, role) { final scale = ref.watch(textScaleFactorProvider); return DynamicTypeScaleService.getBudget(role, scale); }).

Define textScaleFactorProvider as a Provider that reads from a MediaQuery — override it in tests by providing a fixed value. The NHF requirement for cognitive accessibility means conservative maxLines values (e.g., bodyMedium: maxLines=4 at 200% rather than unlimited) to prevent scrollable-within-scrollable anti-patterns.

Testing Requirements

Use flutter_test with testWidgets. Test file: test/dynamic_type_scale_service_test.dart. Required scenarios: (1) at scale 1.0, displayLarge budget fontSizeCap equals baseline size, (2) at scale 2.0, all roles have fontSizeCap <= design-defined maximum, (3) at scale 2.0, a Text widget with labelLarge budget in a 375px-wide Column does not overflow (use RenderObject constraints to verify), (4) provider rebuilds when textScaleFactor changes (use pumpWidget with updated MediaQuery), (5) getBudget returns consistent results for all 15 TextThemeRole values. Use ProviderContainer for unit-testing the service independently of widgets.

Golden tests are optional but recommended for regression protection at 200% scale.

Component

Dynamic Type Scale Service

service medium

Dependencies (1)

Build the design token provider that exposes the project's color, typography, and spacing tokens as typed Dart constants and Riverpod providers. This service is the single source of truth for all downstream enforcement widgets and services. Must expose ColorScheme entries, TextTheme entries, and spacing values so enforcement components can query current token values without hardcoding. epic-visual-design-accessibility-services-and-widgets-task-002

Epic Risks (4)

medium impact high prob integration

Flutter's textScaleFactor behaviour differs between iOS and Android, and third-party widgets used across the app (date pickers, bottom sheets, chips) may not respect the per-role scale caps applied by the dynamic-type-scale-service, causing overflow in screens this epic cannot directly control.

Mitigation & Contingency

Mitigation: Enumerate all third-party widget usages that render text. For each, verify whether they honour the inherited DefaultTextStyle and MediaQuery.textScaleFactor or use hardcoded sizes. File issues with upstream packages and wrap non-compliant widgets in MediaQuery overrides scoped to the safe cap for that role.

Contingency: If upstream packages cannot be patched within the sprint, implement a global MediaQuery wrapper at the app root that clamps textScaleFactor to the highest per-role safe value (typically 1.6–2.0), accepting that users at extreme OS scales see a safe cap rather than full scaling for those widgets.

high impact medium prob dependency

The CI accessibility lint runner depends on the Dart CLI toolchain and potentially custom_lint or a bespoke Dart script. CI environments differ from local dev environments in Dart SDK version, pub cache configuration, and platform availability, risking intermittent CI failures that block all pull requests.

Mitigation & Contingency

Mitigation: Pin the Dart SDK version in the CI workflow configuration. Package the lint runner as a self-contained Dart script with all dependencies vendored or declared in a dedicated pubspec.yaml. Add a CI smoke test that runs the runner against a known-compliant fixture and a known-violating fixture to verify the exit codes are correct.

Contingency: If the custom runner proves too fragile, fall back to running dart analyze with the flutter-accessibility-lint-config rules as the sole CI gate, and schedule the custom manifest validation as a separate non-blocking advisory check until the runner is stabilised.

medium impact medium prob technical

Wrapping all interactive widgets with a 44 pt minimum hit area via HitTestBehavior.opaque may cause unintended tap interception in widgets where interactive elements are closely stacked, particularly in the expense type selector, bulk confirmation screen, and notification filter bar.

Mitigation & Contingency

Mitigation: Conduct integration testing of the touch target wrapper specifically in dense layout scenarios (expense selector, filter bars, bottom sheets with multiple buttons). Use the Flutter Inspector to visualise hit areas and confirm no overlaps. Pair with the interactive-control-spacing-system to ensure minimum 8 dp gaps between expanded hit areas.

Contingency: If overlapping hit areas cause mis-tap regressions in specific screens, allow the touch target wrapper to accept an explicit hitAreaSize parameter that can be reduced below 44 pt only in contexts where the interactive-control-spacing-system guarantees sufficient gap, with a mandatory code review flag for any such override.

high impact medium prob scope

The contrast-safe-color-palette must guarantee WCAG AA ratios for both light and dark mode token sets. Dark mode color derivation is non-trivial — simply inverting a light palette often produces pairs that pass in one mode but fail in the other, and the token manifest must encode both sets explicitly.

Mitigation & Contingency

Mitigation: Define both light and dark token sets explicitly in the accessibility-token-manifest rather than deriving one from the other programmatically. Run the contrast-ratio-validator against both sets as part of the token manifest generation process and include both in the CI lint runner's validation scope.

Contingency: If time pressure forces a dark mode deferral, ship with light mode only and add a prominent in-app notice. Gate dark mode colour tokens behind a feature flag until the full dual-palette validation is complete.

Quick Links

All Tasks Execution Plan