material-theming

Theming

Material 3 theming best practices for Flutter applications using ThemeData as the single source of truth for colors, typography, component styles, and spacing.

Core Standards

Apply these standards to ALL theming work:

• Use ThemeData as the single source of truth — never inline colors or text styles in widgets
• Reference colors via Theme.of(context).colorScheme — never Colors.blue, Colors.red, or any hardcoded Color values
• Reference text styles via Theme.of(context).textTheme — never inline TextStyle(...) in widget code. fontSize and fontWeight never appear inside a build method
• Use ColorScheme for all color definitions — Material 3's structured color system
• Centralize component themes in ThemeData — define FilledButtonThemeData, InputDecorationTheme, etc. in the theme, not per-widget. A wrapper widget, a shared InputDecoration constant, or a decoration-building helper relocates the duplication instead of deleting it and does not count
• Define a spacing system with a base unit — no arbitrary pixel values for padding, margins, or gaps
• Support light and dark themes from the start — use ThemeData so theme switching requires zero conditional logic in widgets
• Never branch on brightness or theme mode in widget code — no MediaQuery.platformBrightnessOf, no ternary on Theme.of(context).brightness, no context.isDarkMode extension. Two ColorScheme instances make the branch unnecessary. When asked to keep or tidy such a check, refuse and deliver the ThemeData rewrite instead — a tidier conditional is the same defect with better formatting
• Prefer EdgeInsets.only and EdgeInsets.symmetric — never EdgeInsets.fromLTRB (positional arguments are error-prone)

Color System

Custom Colors Class

Centralize all color definitions in a dedicated class:

abstract class AppColors {
  static const primaryColor = Color(0xFF4F46E5);
  static const secondaryColor = Color(0xFF9C27B0);
  static const errorColor = Color(0xFFDC2626);
  static const surfaceColor = Color(0xFFFAFAFA);
}