Activity Wizard Step Semantics
Component Detail
Description
Provides custom semantics for each step of the multi-step activity registration wizard, announcing the current step number and total, the step's purpose, and validation errors. Manages focus placement on step transitions so screen reader users always land on the correct input.
activity-wizard-semantics
Summaries
The Activity Wizard Step Semantics component ensures every user, including those relying on assistive technologies such as screen readers, can successfully complete activity registration without friction. By providing clear, audible step-by-step guidance and real-time validation feedback, it removes barriers that cause users with disabilities to abandon multi-step flows — directly improving completion rates across all user segments. Accessibility compliance reduces legal exposure in markets with stringent digital accessibility regulations (WCAG, ADA, EN 301 549) and demonstrates a measurable commitment to inclusive design, which is increasingly a procurement and brand differentiator.
This is a medium-complexity mobile-only component with two hard dependencies: live-region-announcer and semantics-wrapper-widget, both of which must be stable before integration testing can begin. Development requires a Flutter engineer with hands-on accessibility experience, as focus timing and live-region ordering are difficult to validate without real-device testing. Schedule at least one dedicated QA cycle using VoiceOver on iOS and TalkBack on Android — emulator testing will not catch timing or announcement-ordering regressions. Any future changes to the wizard's step count or structure require a corresponding accessibility review; add this to the team's definition of done for wizard UX changes to avoid late-stage rework.
Activity Wizard Step Semantics wraps the multi-step registration wizard using semantics-wrapper-widget to inject custom SemanticsNode properties at each step boundary. announceStepChange() calls SemanticsService.announce() with a formatted string such as 'Step 2 of 5: Add Participants', routing through live-region-announcer to ensure correct ARIA live-region equivalent behaviour on both platforms. focusFirstField() uses FocusNode.requestFocus() deferred by one post-frame callback via WidgetsBinding.addPostFrameCallback to guarantee the target widget is fully mounted before focus is moved. setStepProgress() updates a semantic value on the wizard's progress node.
announceValidationError() fires on onFocusLost for each field widget. All methods short-circuit when no screen reader is active, adding negligible overhead for standard users.
Responsibilities
- Announce step transitions with step number, total, and step label
- Place focus on the first field or header of each new step
- Expose step progress as a semantic value (e.g., 'Step 2 of 5')
- Announce inline validation errors on field blur
Interfaces
announceStepChange(current, total, stepLabel)
focusFirstField(stepWidget)
setStepProgress(current, total)
announceValidationError(fieldLabel, errorMessage)
announceStepCompletion(stepLabel)
Relationships
Dependencies (2)
Components this component depends on