[AGENT] UIUX-003: Centralize theme tokens and navigation configuration

[ucguy4u]

Agent

Agent: agent/mobile-ui

Task Details

Estimate (hours): 20

Priority: P1

Description

Move shell-level design and navigation decisions into shared configuration so
feature screens stop hardcoding visual and IA choices.

Critical Agent Gate

Problem: Theme tokens and nav metadata are split between core_ui, shell
widgets, and feature screens, which weakens consistency and increases churn.

User / actor: End users expecting a unified app experience and engineers
building additional screens.

Framework or application layer: Mixed

Owning agent: agent/mobile-ui

Reviewing agents: agent/core-architecture, agent/qa-testing

Impacted modules/files: packages/core_ui/lib/src/theme/*,
app/lib/core/providers/navigation_provider.dart,
app/lib/core/platform/platform_config.dart, app/lib/core/app/app_shell.dart

Base branch/worktree: confirmed from latest origin/main: yes

Open questions: Should navigation overflow use a drawer, modal sheet, or
another secondary affordance on phones?

Decision: Ready

Feature Packet

Contract: Shared UI packages own token roles, shell destination metadata,
and breakpoint-aware navigation behavior. Application code consumes that config.

Deterministic use cases:

• Shared colors and spacing come from centralized tokens
• Mobile nav adapts when primary destinations exceed bottom-nav guidance
• Desktop/tablet reuse the same destination source of truth

Automation flows:

• Widget tests for mobile and large-screen nav rendering
• Unit tests for destination metadata/config derivation where applicable

Security/privacy posture: None beyond preserving current route access and
auth actions.

Eval plan: Host-only widget tests and shared config review.

Observability/traces: Not required.

Rollback/migration plan: Retain compatibility wrappers while screens move to
the new config.

Verification environment: Host-only

Android Emulator risk accepted? No

Acceptance Criteria

• Shared tokens cover the approved UI roles
• Navigation configuration comes from one source of truth
• Mobile overflow strategy is implemented or concretely specified
• Widget or unit tests cover shared navigation behavior

CI Checklist

• act local run passed
• flutter analyze clean
• flutter test passes
• Device-only checks identify the exact environment used
• Android Emulator was not used unless the issue explicitly accepts the risk
• Unit tests added
• Widget/golden tests added (if UI)
• Docs/ADRs updated (if applicable)

Files to Modify

packages/core_ui/lib/src/theme/*.dart
app/lib/core/providers/navigation_provider.dart
app/lib/core/platform/platform_config.dart
app/lib/core/app/app_shell.dart
app/test/**/navigation*.dart

Dependencies

• UIUX-001 governance epic

Release Note Required?

yes - navigation and visual consistency will be standardized across the app

Parent roadmap: #397

[ucguy4u]

Closing as completed by the merged shell/navigation centralization work already on main.

Current evidence on :

• Shared theme-token roles live in and are attached through , covering shell-facing roles such as , , , , and .
• Navigation metadata and shell chrome config are centralized in via , , and .
• The mobile overflow strategy is implemented in : compact widths keep notifications pinned and move profile/logout into overflow, while wider widths keep the profile menu visible.
• Shared navigation behavior is covered by tests in , , and .

This landed through the merged work in #413 and #414, so there is no separate remaining implementation slice to track under #399.

[ucguy4u]

Closing as completed by the merged shell/navigation centralization work already on main.

Current evidence on main:

• Shared theme-token roles live in packages/core_ui/lib/src/theme/airo_theme_tokens.dart and are attached through packages/core_ui/lib/src/theme/app_theme.dart, covering shell-facing roles such as gridLine, chromeSurface, glow, success, and warning.
• Navigation metadata and shell chrome config are centralized in app/lib/core/providers/navigation_provider.dart via AppNavigationTab, appNavigationChromeConfigProvider, and appShellHeaderModeForLocation(...).
• The mobile overflow strategy is implemented in app/lib/core/app/app_shell_chrome.dart: compact widths keep notifications pinned and move profile/logout into overflow, while wider widths keep the profile menu visible.
• Shared navigation behavior is covered by tests in app/test/core/providers/navigation_provider_test.dart, app/test/core/app/app_shell_chrome_test.dart, and app/test/core/app/app_shell_header_ownership_test.dart.

This landed through the merged work in #413 and #414, so there is no separate remaining implementation slice to track under #399.