| 1 | # Material 3 Theming System |
| 2 | |
| 3 | This directory contains the Material 3 (M3) theming implementation for Cake Wallet. The theming system is now fully based on Material 3 color tokens and patterns, with all custom theme extensions removed for simplicity, maintainability, and compliance with Material Design 3 guidelines. |
| 4 | |
| 5 | ## Directory Structure |
| 6 | |
| 7 | ``` |
| 8 | lib/themes/ |
| 9 | ├── core/ # Theme state management and base theme logic |
| 10 | ├── theme_classes/ # Light and dark theme data definitions |
| 11 | ├── extensions/ # (Optional) Theme extensions for specific widgets/pages |
| 12 | ├── utils/ # Utilities for theme management |
| 13 | └── README.md # This file |
| 14 | ``` |
| 15 | |
| 16 | ## Key Features |
| 17 | |
| 18 | - Material 3 color system with semantic color tokens |
| 19 | - Dynamic color support (when available) |
| 20 | - MobX-based state management |
| 21 | - Simplified theme management |
| 22 | - Consistent design language across the app |
| 23 | |
| 24 | ## Usage |
| 25 | |
| 26 | ### Accessing Theme Colors |
| 27 | |
| 28 | ```dart |
| 29 | final colorScheme = Theme.of(context).colorScheme; |
| 30 | final primaryColor = colorScheme.primary; |
| 31 | final onSurfaceVariant = colorScheme.onSurfaceVariant; |
| 32 | ``` |
| 33 | |
| 34 | ### Available Color Tokens |
| 35 | |
| 36 | Material 3 provides a comprehensive set of semantic color tokens that adapt to light/dark themes: |
| 37 | |
| 38 | - `primary` / `onPrimary` |
| 39 | - `secondary` / `onSecondary` |
| 40 | - `tertiary` / `onTertiary` |
| 41 | - `error` / `onError` |
| 42 | - `background` / `onBackground` |
| 43 | - `surface` / `onSurface` |
| 44 | - `surfaceVariant` / `onSurfaceVariant` |
| 45 | - `outline`, `outlineVariant` |
| 46 | - ...and more (see Flutter's ColorScheme) |
| 47 | |
| 48 | ### Theme Management |
| 49 | |
| 50 | Theme mode state (light/dark/system) and switching is handled via MobX stores in `core/`. Use the provided store to get/set the current theme mode and listen for changes. |
| 51 | |
| 52 | ```dart |
| 53 | // Example: Getting the current theme mode |
| 54 | final themeStore = ... // Obtain from provider or context |
| 55 | final isDark = themeStore.isDark; |
| 56 | |
| 57 | // Example: Switching theme mode |
| 58 | await themeStore.setThemeMode(ThemeMode.dark); |
| 59 | ``` |
| 60 | |
| 61 | ## Best Practices |
| 62 | |
| 63 | 1. **Always use semantic color tokens** from `ColorScheme` instead of hardcoded colors. |
| 64 | 2. **Leverage Material 3 components** wherever possible for consistency and accessibility. |
| 65 | 3. **Use the MobX theme store** for all theme-related state and switching. |
| 66 | 4. **Test in both light and dark modes** to ensure good contrast and appearance. |
| 67 | 5. **Keep any theme extensions minimal and focused** (if used at all). |
| 68 | 6. **Do not reintroduce custom theme extensions** unless absolutely necessary and not covered by Material 3. |
| 69 | |
| 70 | ## Adding or Modifying Themes |
| 71 | |
| 72 | - To update theme colors, edit the files in `theme_classes/` (e.g., `light_theme.dart`, `dark_theme.dart`). |
| 73 | - To add a new theme variant, create a new file in `theme_classes/` and update the MobX store in `core/` to support it. |
| 74 | - For widget-specific theming, prefer using Material 3's built-in tokens. Only use a theme extension if there is no Material 3 equivalent. |
| 75 | |
| 76 | ## Contributing |
| 77 | |
| 78 | - Follow Material 3 color system and accessibility guidelines. |
| 79 | - Ensure proper contrast ratios for accessibility. |
| 80 | - Test all changes in both light and dark modes. |
| 81 | - Update this documentation if you add new color tokens or theme variants. |
| 82 | - Keep theme files organized and focused. |