[AGENT] UIUX-001: Mobile UI governance, shell ownership, and standards

[ucguy4u]

Agent

Agent: agent/mobile-ui

Task Details

Estimate (hours): 16

Priority: P1

Description

Create the shared governance layer for UI work so future screens stop making
independent shell, header, navigation, and asset decisions.

Current State

• app/lib/core/app/app_shell.dart renders a global top app bar
• multiple feature screens still render local AppBars
• six top-level destinations are hardcoded into the bottom navigation model
• theme tokens are only partially centralized in packages/core_ui
• shell asset usage is not governed by a shared registry contract

Proposed Outcome

1. Establish a Mobile UI Agent packet in the repo
2. Establish an ADR for shell/header ownership
3. Establish centralized UI standards for tokens, navigation, and assets
4. Break implementation into focused child issues

Critical Agent Gate

Problem: Repeated UI changes are happening without a stable shared contract,
which causes duplicated headers, wasted space, and inconsistent UX.

User / actor: Mobile users navigating top-level Airo surfaces and engineers
implementing future UI changes.

Framework or application layer: Mixed

Owning agent: agent/mobile-ui

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

Impacted modules/files: app/lib/core/app/app_shell.dart,
app/lib/core/providers/navigation_provider.dart,
app/lib/core/routing/app_router.dart, app/lib/core/platform/platform_config.dart,
packages/core_ui/lib/src/theme/*, app/pubspec.yaml, route screens currently
defining local AppBars

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

Open questions: What overflow model should own the sixth and later primary
destinations on mobile? Which nested flows truly need contextual local headers?

Decision: Ready

Feature Packet

Contract: Shared UI code owns shell chrome, destination metadata, header
configuration, tokens, and asset registration. Feature screens own content and
local workflow presentation.

Deterministic use cases:

• Root shell routes show one visible top header only
• Nested routes either inherit shell chrome or explicitly opt into contextual
  chrome
• Mobile top-level navigation remains understandable without six equal bottom
  destinations
• Shared assets and icons are referenced through a central contract

Automation flows:

• Widget test verifies no duplicate header is rendered for a root shell route
• Widget or route-flow test verifies overflow navigation remains reachable
• Static audit verifies shell-level assets resolve from centralized constants or
  registry accessors

Security/privacy posture: No direct security impact; must preserve existing
auth/profile/logout affordances and avoid exposing additional data in chrome.

Eval plan: Validate route flows on host-only widget tests and review screen
density against the standard.

Observability/traces: Not required for docs-only governance work.

Rollback/migration plan: Governance docs can be reverted independently.
Implementation issues should migrate route groups incrementally.

Verification environment: Host-only

Android Emulator risk accepted? No

Acceptance Criteria

• Mobile UI Agent packet exists in the repo
• ADR exists for shell/header ownership
• UI/UX standards document exists for centralized configuration
• Child issues exist for execution work

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

docs/agents/mobile-ui-agent/README.md
docs/agents/mobile-ui-agent/TASKS.md
docs/standards/mobile-ui-ux-standards.md
docs/adr/0006-mobile-ui-governance-and-shell-ownership.md
docs/adr/README.md
docs/agents/index.md

Dependencies

• None

Release Note Required?

no