# 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.