How do you build a maintainable theme system?

Material 3 derives much of its palette from a seed colour. A single ColorScheme supplies semantic roles such as primary, surface and error. Widgets should read those roles rather than hardcoded colours, so dark mode and brand changes propagate without editing every screen.

final lightScheme = ColorScheme.fromSeed(
  seedColor: const Color(0xFF0F766E),
  brightness: Brightness.light,
);

final appTheme = ThemeData(
  useMaterial3: true,
  colorScheme: lightScheme,
  filledButtonTheme: FilledButtonThemeData(
    style: FilledButton.styleFrom(
      minimumSize: const Size(48, 48),
      shape: RoundedRectangleBorder(
        borderRadius: BorderRadius.circular(12),
      ),
    ),
  ),
);

• Use ColorScheme roles instead of raw hex values in widgets
• Provide light and dark ThemeData and let ThemeMode follow the system when appropriate
• Centralise text styles and component themes rather than repeating styleFrom
• Use ThemeExtension for tokens Material does not model, such as custom spacing or brand colours
• Check contrast ratios and do not encode meaning in colour alone

Why hardcoded styles rot

A screen that writes Colors.grey directly will look wrong in dark mode and will not follow a rebrand. A screen that reads colorScheme.outline adapts. Component themes keep interaction states consistent across the app and reduce the chance that one button forgets its disabled style.