Navigation Route Configuration
Component Detail
Description
Central GoRouter configuration that defines all application routes with accessibility constraints built in: StatefulShellRoute for tab branches, PopScope wrapping to prevent accidental back-swipe as sole dismissal, and route-level metadata declaring whether a close button is required.
navigation-route-config
Summaries
The Navigation Route Configuration is the foundational contract that governs how users move through the entire application. For users with motor disabilities who depend on assistive technologies, a poorly configured navigation architecture can make the app completely unusable — screens they cannot dismiss, flows that trap them, or back buttons that don't appear. This component bakes accessibility requirements directly into the routing layer, making it structurally impossible to ship a screen that violates gesture-free navigation principles without explicitly overriding defined policies. It is a key risk-reduction asset that protects the product's accessibility integrity as the team scales and new features are added by different contributors.
Navigation Route Configuration is a medium-complexity shared infrastructure component that all other navigation and UI work depends on. It must be one of the first components delivered, as no screen-level work can proceed without a route being registered here. The use of GoRouter with StatefulShellRoute requires the team to align on routing conventions early — mismatches between route names, parameter schemas, and deep-link patterns cause cascading bugs.
The `setModalDismissalPolicy()` interface must be enforced as a code review requirement whenever a new modal is added. Regression risk is high: any change to this file can affect all navigation in the app, so route configuration changes require full navigation regression testing before merge.
Navigation Route Configuration is the central GoRouter instance, constructed via `buildRouter()` and provided at the app root. StatefulShellRoute wraps the five tab branches, each with its own navigator key, enabling independent back-stack management per branch. PopScope is applied at route level to suppress the platform swipe-back gesture on routes where it would be the sole dismissal mechanism — this is declared via route metadata rather than per-widget, keeping gesture policy centralized. `getRouteMetadata(routeName)` returns a typed metadata object that the Navigation Accessibility Service consumes for compliance auditing.
`navigateTo(context, routeName, params)` provides a named-route navigation facade to avoid string-literal route paths scattered through the codebase. This component is shared and must be treated as a high-stability, low-churn module — changes require cross-team coordination.
Responsibilities
- Define all application routes using GoRouter and StatefulShellRoute
- Attach route metadata indicating required dismissal mechanisms
- Configure PopScope to suppress platform swipe-back where needed
- Register named routes for consistent deep-link and back-stack navigation
Interfaces
buildRouter()
getRouteMetadata(routeName)
registerRoute(routeConfig)
setModalDismissalPolicy(routeName, policy)
getStatefulShellRoute()
navigateTo(context, routeName, params)