social-app/docs/plans/2026-03-27-app-theme-dark-mode-migration.md

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.