Build ConfirmBeforeSubmitScreen layout and copy
epic-cognitive-accessibility-wizard-ui-task-011 — Implement the ConfirmBeforeSubmitScreen as a full-screen confirmation gate that shows a summary of the wizard answers, a plain-language explanation of what submitting will do, and two clearly labelled actions: Confirm and Go Back. Use SingleActionScreenLayout from the foundation epic. Apply cognitive load design principles: single focal action, no distracting secondary content, large touch targets.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Model the screen API as: `ConfirmBeforeSubmitScreen({required WizardSummary summary, required VoidCallback onConfirm, VoidCallback? onGoBack})`. Derive `onGoBack` default behaviour to `Navigator.of(context).pop()` inside the widget if the parameter is null — this simplifies call sites while keeping the screen testable. For the anchored-bottom-buttons pattern with a scrollable summary above, use a `Column` with an `Expanded(child: ListView(...))` for the summary rows and a fixed-height `Padding(child: Column(children: [confirmButton, goBackButton]))` below it — this is more reliable across screen sizes than Stack-based overlays.
Define `WizardSummaryRow` as a small private widget (or a separate file if reused) that renders a `Row` with a bold label `Expanded` and a plain value `Expanded` — this ensures equal-width columns regardless of text length. Use design token values for all colours and spacings — no hardcoded hex or pixel values. The plain-language explanation paragraph copy should be defined as a localisation key, not a hardcoded string, even if only English is supported at this stage.
Testing Requirements
Write widget tests: (1) all summary rows from a fixture WizardSummary are rendered with correct labels and values; (2) 'Go Back' tap calls Navigator.pop() — verify with a MockNavigatorObserver; (3) 'Confirm' tap calls the onConfirm callback — verify with a mock callback; (4) at 320dp width, no RenderFlex overflow errors; (5) with a 25-row summary, action buttons remain visible at bottom without scrolling (anchored); (6) Semantics labels on both buttons are non-empty. Golden test for the full screen at 375dp. All tests must pass with `flutter test`.
The WizardStateManager BLoC must guarantee that step transitions only occur on explicit user action, never automatically. Subtle reactive patterns in Bloc (e.g. stream listeners triggering add() calls) could inadvertently auto-advance the wizard, violating the core cognitive accessibility rule and creating a regression that is difficult to detect without dedicated tests.
Mitigation & Contingency
Mitigation: Write a dedicated unit test that subscribes to the BLoC stream and asserts no StepChanged event is emitted for 5 seconds after a state update, without an explicit user-sourced event being dispatched. Make this test part of the CI gate for the WizardStateManager.
Contingency: If an auto-advance regression is discovered post-integration, introduce a mandatory UserActionToken parameter on all step-transition events so the BLoC can structurally refuse transitions that do not originate from a user gesture handler.
The ConfirmBeforeSubmitScreen requires deep-linking back to specific wizard steps for corrections. Implementing bidirectional navigation within a multi-step wizard while preserving all previously entered state is architecturally non-trivial and may conflict with the existing StatefulShellRoute navigation setup described in the app architecture.
Mitigation & Contingency
Mitigation: Design the ConfirmBeforeSubmitScreen's back-navigation links to dispatch a GoToStep event on the WizardStateManager rather than using GoRouter's pop() chain. This keeps navigation state entirely in the BLoC and avoids coupling to the router's stack semantics.
Contingency: If BLoC-driven step navigation proves incompatible with the router, implement the correction flow as a dedicated sub-route that pre-populates its form from the WizardStateManager's current draft, then merges the edited field back into the draft on completion before returning to the confirm screen.
The CognitiveAccessibilityAudit utility must inspect live widget trees for violations such as icon-only buttons. Flutter's widget tree inspection APIs are available in test mode but have limitations in identifying semantic intent (e.g. distinguishing a decorative icon from a navigation button). False negatives could give a false sense of compliance.
Mitigation & Contingency
Mitigation: Augment the audit with a convention-based approach: require all navigation buttons to use a named wrapper widget (e.g. LabelledNavigationButton) that the audit can detect by type, rather than relying solely on widget-tree semantics analysis.
Contingency: If widget-tree detection proves insufficiently reliable, scope the CognitiveAccessibilityAudit to route-configuration analysis (verifying back navigation availability per route) and static analysis of wizard step count definitions via the CognitiveLoadRuleEngine, which provides deterministic results.
The InlineContextualHelpWidget sources content from a bundled JSON asset via the HelpContentRegistry. If help texts are missing for newly added screens or fields (a likely scenario as the 61-feature app grows), the widget silently shows nothing, degrading the accessibility experience without any visible failure.
Mitigation & Contingency
Mitigation: Integrate a CognitiveAccessibilityAudit check that verifies every registered (screenId, fieldId) pair that requests help has a corresponding entry in the HelpContentRegistry bundle. Run this check in CI as part of the audit report.
Contingency: Add a debug-mode overlay that highlights fields with missing help entries using a visible warning indicator, making coverage gaps immediately obvious to developers during local development before they reach CI.