Design Tokens

Theme architecture

The public compatibility file is lib/components/utils/design_tokens.dart. It re-exports the modular theme registry under components/utils/themes/.

components/utils/themes/
├── app_theme.dart
├── base/design_tokens_model.dart
└── definitions/modern_theme.dart
                 retro_theme.dart
                 cozy_theme.dart
                 paper_theme.dart

AppThemeRegistry currently supports modern, retro, cozy, and paper, each with light/dark token definitions.

Use tokens in widgets

final tokens = ref.watch(designTokensProvider);

Container(
  padding: EdgeInsets.all(tokens.contentPadding),
  decoration: BoxDecoration(
    color: tokens.surface,
    borderRadius: BorderRadius.circular(tokens.cardBorderRadius),
  ),
  child: Text('Hello', style: tokens.bodyPrimary),
);

DesignTokens includes semantic colors, body text styles, border radii, spacing/padding, layout values, component sizes, border colors, and card shadows. Use these values instead of hard-coded colors and dimensions.

Runtime appearance

providers/theme_provider.dart persists:

• AppThemeMode: light, dark, or system.
• AppTheme: modern, retro, cozy, or paper.
• AccentColor: emerald, blue, indigo, purple, pink, or amber.
• Text scale, bold text, reduced motion, and compact mode.

Appearance settings are local and available in both Account and Guest profiles.

Add a theme

1. Add an enum value to AppTheme in components/utils/themes/app_theme.dart.
2. Create complete light/dark DesignTokens values under themes/definitions/.
3. Register both values in AppThemeRegistry maps.
4. Add the option/translation to the appearance page and ARB files.
5. Regenerate provider/localization code as needed.
6. Test contrast, text scaling, compact spacing, reduced motion, and both brightness modes.

Do not edit generated provider files by hand. Keep all required DesignTokens fields populated.

Relevant files

• components/utils/design_tokens.dart
• components/utils/themes/base/design_tokens_model.dart
• components/utils/themes/app_theme.dart
• components/utils/themes/definitions/
• providers/theme_provider.dart
• pages/settings/appearance/page.dart