127 lines
4.6 KiB
Markdown
127 lines
4.6 KiB
Markdown
|
# App Theme Dark Mode and Hardcoded Color Migration Implementation Plan
|
||
|
|
|
||
|
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||
|
|
|
||
|
|
**Goal:** Enable automatic light/dark mode following system settings and gradually migrate UI color usage from direct `AppColors` references to theme-driven semantic colors.
|
||
|
|
|
||
|
|
**Architecture:** Introduce a dual-theme foundation in `AppTheme` (`light` and `dark`) and route app root to `ThemeMode.system`. Then migrate color access in batches: first shared widgets, then high-traffic feature pages, then long-tail modules. Keep `AppColors` as design-token source only inside theme/token layers during migration.
|
||
|
|
|
||
|
|
**Tech Stack:** Flutter Material 3 (`ThemeData`, `ColorScheme`, `ThemeMode`), existing design tokens (`AppColors`, `AppSpacing`, `AppRadius`), flutter analyze/test verification.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Task 1: Theme Foundation and System Dark Mode Wiring
|
||
|
|
|
||
|
|
**Files:**
|
||
|
|
- Modify: `apps/lib/core/theme/app_theme.dart`
|
||
|
|
- Modify: `apps/lib/app/app.dart`
|
||
|
|
|
||
|
|
**Step 1: Build dual-theme entry points**
|
||
|
|
|
||
|
|
- Add `AppTheme.dark` and a shared private builder `AppTheme._buildTheme(Brightness)`.
|
||
|
|
- Ensure light and dark themes both use Material 3 and `ColorScheme.fromSeed`.
|
||
|
|
|
||
|
|
**Step 2: Remove theme-level hardcoded semantic colors**
|
||
|
|
|
||
|
|
- Replace direct `AppColors` usage in app bar/button/input decoration theme with color-scheme-driven values.
|
||
|
|
- Keep radii and spacing tokens unchanged.
|
||
|
|
|
||
|
|
**Step 3: Wire root app to system mode**
|
||
|
|
|
||
|
|
- In `MaterialApp.router`, set `theme`, `darkTheme`, and `themeMode: ThemeMode.system`.
|
||
|
|
|
||
|
|
**Step 4: Verify**
|
||
|
|
|
||
|
|
Run: `cd apps && flutter analyze`
|
||
|
|
Expected: no new analyzer errors.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Task 2: Shared Widget Batch (P0) - Replace Direct AppColors with Theme Semantics
|
||
|
|
|
||
|
|
**Files:**
|
||
|
|
- Modify: `apps/lib/shared/widgets/error_retry_surface.dart`
|
||
|
|
- Modify: `apps/lib/shared/widgets/confirm_sheet.dart`
|
||
|
|
- Modify: `apps/lib/shared/widgets/destructive_action_sheet.dart`
|
||
|
|
- Modify: `apps/lib/shared/widgets/toast/toast_type_config.dart`
|
||
|
|
|
||
|
|
**Step 1: Migrate simple error surface**
|
||
|
|
|
||
|
|
- Use `Theme.of(context).colorScheme.error` for retry message color.
|
||
|
|
|
||
|
|
**Step 2: Migrate confirm/destructive sheets**
|
||
|
|
|
||
|
|
- Replace sheet background/border/text/primary-action color bindings with `ColorScheme` semantic roles (`surface`, `outlineVariant`, `onSurface`, `onSurfaceVariant`, `primary`, `onPrimary`, `error`, `onError`).
|
||
|
|
|
||
|
|
**Step 3: Migrate toast style mapping**
|
||
|
|
|
||
|
|
- Replace static feedback colors with semantic color-scheme mappings per toast type.
|
||
|
|
- Preserve existing icon and l10n label behavior.
|
||
|
|
|
||
|
|
**Step 4: Verify**
|
||
|
|
|
||
|
|
Run: `cd apps && flutter analyze`
|
||
|
|
Expected: no new analyzer errors.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Task 3: Batch Migration Governance and Rollout Rules
|
||
|
|
|
||
|
|
**Files:**
|
||
|
|
- Modify: `docs/bugs/AppTheme硬编码颜色且缺失DarkMode.md`
|
||
|
|
|
||
|
|
**Step 1: Document batch strategy**
|
||
|
|
|
||
|
|
- Add phased rollout strategy: Foundation -> Shared widgets (P0) -> Core pages (P1) -> Long tail (P2) -> guardrails.
|
||
|
|
|
||
|
|
**Step 2: Define acceptance and rollback criteria**
|
||
|
|
|
||
|
|
- Include per-batch verification (`flutter analyze`, targeted widget tests/manual dark mode checks).
|
||
|
|
- Require small-scope commits per batch for safe rollback.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Task 4: P1/P2 Execution Backlog (Follow-up)
|
||
|
|
|
||
|
|
**Files:**
|
||
|
|
- Modify: `apps/lib/features/home/**`
|
||
|
|
- Modify: `apps/lib/features/settings/**`
|
||
|
|
- Modify: `apps/lib/features/auth/**`
|
||
|
|
- Modify: remaining `apps/lib/features/**`
|
||
|
|
|
||
|
|
**Step 1: Prioritize by user path**
|
||
|
|
|
||
|
|
- P1 order: home -> settings -> auth.
|
||
|
|
- P2: remaining feature pages and low-frequency screens.
|
||
|
|
|
||
|
|
**Step 2: Migrate per file with semantic mapping**
|
||
|
|
|
||
|
|
- Replace direct `AppColors` usage in widget code with `Theme.of(context).colorScheme` or scoped theme helpers.
|
||
|
|
- Keep visual behavior equivalent first; optimize polish after semantic migration is stable.
|
||
|
|
|
||
|
|
**Step 3: Verify per batch**
|
||
|
|
|
||
|
|
Run:
|
||
|
|
- `cd apps && flutter analyze`
|
||
|
|
- `cd apps && flutter test` (targeted where tests exist)
|
||
|
|
|
||
|
|
Expected: no regressions in targeted flows and theme switching.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Risks and Mitigations
|
||
|
|
|
||
|
|
- Risk: dark mode contrast regression in legacy widgets.
|
||
|
|
- Mitigation: migrate shared widgets first, then high-traffic pages with screenshot/manual checks.
|
||
|
|
- Risk: mixed semantic + static colors during transition.
|
||
|
|
- Mitigation: enforce migration order and avoid adding new direct `AppColors` in UI layers.
|
||
|
|
- Risk: broad-scope change fatigue.
|
||
|
|
- Mitigation: ship in small batches with isolated verification and rollback points.
|
||
|
|
|
||
|
|
## Done Criteria
|
||
|
|
|
||
|
|
- `MaterialApp` follows `ThemeMode.system` with `theme` and `darkTheme` configured.
|
||
|
|
- Theme layer no longer relies on static semantic colors for app-wide component themes.
|
||
|
|
- P0 shared widget batch migrated to theme semantics.
|
||
|
|
- Migration plan and execution progress documented in bug tracker doc.
|