Material Theming

Material 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);
}

ColorScheme Configuration

Every color reaches widgets through a ColorScheme role. Define two schemes — one light, one dark — inside a single AppTheme class, and pass both to MaterialApp as theme and darkTheme. That pair is what makes brightness branching in widget code unnecessary:

class AppTheme {
  static ThemeData get light => ThemeData(
    colorScheme: const ColorScheme.light(
      brightness: Brightness.light,
      surface: AppColors.surfaceColor,
      // ... remaining color roles
    ),
  );

  static ThemeData get dark => ThemeData(
    colorScheme: const ColorScheme.dark(
      brightness: Brightness.dark,
      surface: AppColors.surfaceColorDark,
      // ... remaining color roles
    ),
  );
}

See references/color-scheme.md for the full 45-role ColorScheme configuration, ColorScheme.fromSeed, and how widgets read colors.

Typography

Define an AppTextStyle class with a base style and named variants (displayLarge, headlineMedium, bodyLarge, etc.), then integrate them into ThemeData.textTheme. Access styles via Theme.of(context).textTheme.

See references/typography.md for font asset setup, the full AppTextStyle class, TextTheme integration, and widget access patterns.

Replacing a Hardcoded TextStyle

Map the literal to the nearest slot AppTextStyle already defines, by size and weight — 18px/w500 lands on titleLarge (20/w500), 16px/w400 on bodyLarge, 14px/w500 on labelLarge. Adjust that slot's size in AppTextStyle if the app needs a different one; do not keep the number at the call site. Do not land on a slot AppTextStyle does not define and TextTheme does not register: the read still returns a style, but it comes from Material's default typography, so the app's font silently reverts. copyWith at the call site sets a color role and nothing else:

final theme = Theme.of(context);

Text(
  label,
  style: theme.textTheme.titleLarge?.copyWith(
    color: theme.colorScheme.onPrimary,
  ),
)

Swapping only the color and leaving TextStyle(fontSize: 18, fontWeight: FontWeight.w500) in the widget is not a fix — the typography still lives outside the theme.

Component Themes

Define component themes centrally in ThemeData (e.g., filledButtonTheme, inputDecorationTheme, appBarTheme) instead of styling individual widget instances. A complete AppTheme class assembles ColorScheme, TextTheme, and all component themes into a single ThemeData.

See references/components.md for FilledButton, InputDecoration, and AppBar theme examples, the complete theme assembly, and widget access patterns.