Think "single source of truth" — see Part 1.

A single, central source of truth for an app's visual style (colors, text, component defaults) that widgets reference instead of hardcoding, so a change happens in one place and propagates everywhere.

It's a future cost that charges interest.

The future cost incurred by hardcoding values now: every later style change costs more than it should (you must find and edit each copy), and the "interest" compounds as the app grows.

Compare TextStyle(color: Colors.black) with ...colorScheme.onSurface.

Instead of declaring an absolute value (Colors.black), the widget reads a role from the theme (Theme.of(context).colorScheme.onSurface), getting a context-appropriate answer (e.g. light vs dark) it doesn't have to know about.

It falsifies "the background is white" everywhere at once.

Dark mode. Every hardcoded color bakes in a background assumption, so adding dark mode becomes an audit of every widget unless colors were themed.

Typing a number vs typing =Prices!B2.

Hardcoding is typing a literal number into a cell; theming is typing a reference (=Prices!B2). Change the one source cell and every reference updates.

It fixes duplication but not context.

It's still one absolute value: it can't be one color in light mode and another in dark, can't vary per brand, and carries no semantic role. A theme provides context-sensitive and role-named values.

Think consistency and accessibility.

Consistency (you accumulate several near-identical greys nobody chose deliberately) and accessibility (contrast ratios become accidental). Also: slower onboarding, code/design language mismatch.

Compare the cost of starting vs retrofitting.

Retrofitting cost scales with app size (more screens = more literals to migrate), while starting themed costs ~nothing because flutter create already ships a ThemeData. Cheapest moment is the first color you type.

Use colorScheme.onSurface.

Text('Hi', style: TextStyle(color: Theme.of(context).colorScheme.onSurface));

colorScheme.primary (or set appBarTheme globally).

AppBar(backgroundColor: Theme.of(context).colorScheme.primary);

Better yet, set appBarTheme once on ThemeData so every AppBar is consistent.

The nearest one of these objects.

The nearest ThemeData found by walking up the widget tree from context.

Same color, many spellings.

The same color appears in different forms — uppercase/lowercase hex, Color.fromARGB(...), a near-equivalent Colors.deepPurple — so a single literal search won't catch them all.

Both sides speak the same language.

Designers describe UI in tokens/roles (primary, surface, title). When code uses the same named roles, handoff and review become "use primary" instead of translating to and arguing about hex codes.

One app, several brands.

Hardcoded, each brand needs its colors changed in dozens of places → divergent forks. Themed, each brand is one ThemeData/seed selected by config, with widgets unchanged because they reference roles.

The first time you do a certain thing.

The first time you type a color. The infrastructure (ThemeData) already exists from flutter create.

There's a low-emphasis on-surface role.

final c = Theme.of(context).colorScheme.onSurfaceVariant;
// use c for all three

One role replaces the ad-hoc greys (covered in Part 3).

Reading subscribes; changing notifies.

Theme.of(context) subscribes the widget to the inherited Theme. Swapping the ThemeData notifies all dependents, which rebuild and re-read the new values — no manual listeners on leaf widgets.

The token is the answer.

Reviewers no longer debate "is #6750A4 the right purple?" on every change — the role name (primary) encodes the decision, which lives in one place (the theme).

"Just temporarily" + prototypes that ship.

Small apps grow and prototypes become production. Since the theme infrastructure is free and already present, hardcoding only defers a cost that increases with size — there's no upside to skipping the theme.

Who decides the color — the widget or the theme?

Control moves from the widget (asserting absolute values) to the theme (providing context-sensitive, role-named values). Widgets become consumers of style, not authors of it.

The central style object → MaterialApp.

The immutable object holding colors, text styles, and component defaults. You pass it to MaterialApp's theme: (and darkTheme:).

One property; useMaterial3 is already default.

ThemeData(colorSchemeSeed: Colors.orange);

Default since 3.16.

No — Material 3 is the default since Flutter 3.16, so you don't set it for new apps (set it explicitly only during a migration to make intent clear).

The heart of the theme.

colorScheme — almost every Material widget colors itself from it.

Convenience vs control.

colorSchemeSeed: takes a single seed color and builds the scheme for you (simplest). colorScheme: takes a ColorScheme you construct (e.g. ColorScheme.fromSeed(..., brightness: ...)), needed for brightness control or role tweaks.

appBarTheme.

ThemeData(
  colorSchemeSeed: Colors.indigo,
  appBarTheme: const AppBarTheme(elevation: 0, centerTitle: true),
);

It's immutable.

ThemeData is immutable; you can't edit it in place. copyWith returns a new instance with some fields replaced and the rest copied.

visualDensity.

final compact = base.copyWith(visualDensity: VisualDensity.compact);

Walk up to the nearest inherited Theme.

It walks up the tree from context to the nearest Theme InheritedWidget (inserted by MaterialApp) and returns its ThemeData, subscribing the caller to rebuilds.

Which context?

The context is from the same build that creates MaterialApp, i.e. above the theme, so it returns the default. Read from a child widget below MaterialApp (or wrap in a Builder).

cardTheme.

ThemeData(
  cardTheme: CardThemeData(
    shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(16)),
  ),
);

Tokens Material doesn't know about.

For app-specific tokens beyond Material's vocabulary (e.g. a "success" color, brand gradient, custom spacing), attached via ThemeData(extensions: [...]).

xxxTheme named after the widget.

Examples: appBarTheme, elevatedButtonTheme, cardTheme (also chipTheme, inputDecorationTheme, dialogTheme, …).

Local Theme widget + copyWith on the scheme.

Theme(
  data: Theme.of(context).copyWith(
    colorScheme: Theme.of(context).colorScheme.copyWith(primary: Colors.red),
  ),
  child: const DangerZone(),
)

You already hold a ColorScheme.

When you already have a ColorScheme object and want a theme built from it. In practice ThemeData(colorScheme: ...) covers most cases.

Pre-baked.

Ready-made light and dark Material themes — handy for quick starts, defaults, or fallbacks.

scheme.surface / scheme.onSurface.

final scheme = ColorScheme.fromSeed(seedColor: Colors.indigo);
ThemeData(
  colorScheme: scheme,
  appBarTheme: AppBarTheme(
    backgroundColor: scheme.surface,
    foregroundColor: scheme.onSurface,
  ),
);

Sub-themes feed every instance.

A sub-theme applies to every widget of that type; if it hardcodes a color, that color won't adapt to dark/brand. Pulling from the scheme keeps the global style adaptive.

Two or three properties.

Set colorSchemeSeed/colorScheme, optionally a textTheme, and a few component sub-themes — that's a complete professional theme; everything else has sensible defaults.

Did it actually read via of(context)?

It captured the theme outside build (e.g. stored it in a field/initState) so it isn't subscribed to the inherited theme; or it used a stale/const context. Read Theme.of(context) inside build so it re-subscribes and rebuilds on change.

One color in, many out.

A full ColorScheme (~30 coordinated roles) generated from one seed color via Material 3's tonal algorithm, tuned to harmonize and meet contrast.

Content drawn on a background.

For a background role X, onX is the readable content color to draw on top of it. Always pair X with onX.

Apply the on rule.

onPrimary.

Bold vs soft.

primary is the bold, saturated brand color (filled FAB/buttons); primaryContainer is a softer tinted version (chips, highlighted cards), with onPrimaryContainer for its content.

Vary brightness.

final light = ColorScheme.fromSeed(seedColor: Colors.green);
final dark  = ColorScheme.fromSeed(seedColor: Colors.green, brightness: Brightness.dark);

Shared hue → on brand.

They share a hue so they read as two views of one brand identity, while each is independently tuned for its background's contrast.

Wrong on pairing.

Container(color: scheme.error, child: Text('!', style: TextStyle(color: scheme.onError)));

background, surfaceVariant.

background → surface; onBackground → onSurface; surfaceVariant → surfaceContainerHighest (or surfaceContainerHigh).

The component background role.

surface (with onSurface for content on it).

Who reads the scheme automatically?

Built-in Material widgets color themselves from the scheme's roles (FAB → primaryContainer, card → surface, etc.), so a correct scheme styles all standard components automatically; you only reach for roles by hand in custom widgets.

Container roles, not the saturated one.

Container(
  padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
  decoration: BoxDecoration(color: scheme.tertiaryContainer, borderRadius: BorderRadius.circular(8)),
  child: Text('Beta', style: TextStyle(color: scheme.onTertiaryContainer)),
)

Layering/elevation tints.

A graduated set of surface tints used to express elevation/layering in Material 3 (a higher card sits on a higher container tone), replacing the older single surfaceVariant.

There's an outline family.

outline (and outlineVariant for subtler/decorative lines).

Just a seed.

Use ColorScheme.fromSeed(seedColor: ...) with no role overrides — the generated values harmonize and pass contrast; override only when a brand spec forces it.

There's a contrastLevel knob.

ColorScheme.fromSeed(seedColor: Colors.teal, contrastLevel: 1.0); // 0.0 default → 1.0 high

Where does the palette come from on Android 12+?

A palette derived from the user's wallpaper on Android 12+, obtained in Flutter via the dynamic_color package, with a seed scheme as fallback.

Widgets reference roles, not hex.

Because widgets reference semantic roles, you can change where the ColorScheme comes from (seed, wallpaper, per-brand config) and every widget re-reads its role — no widget edits.

Deprecated → surface.

Replace colorScheme.background with colorScheme.surface (and onBackground → onSurface).

A container pair.

primaryContainer (background) and onPrimaryContainer (icon) by default.

onPrimary wasn't regenerated.

Overriding primary alone leaves onPrimary unchanged, so the pair is no longer contrast-matched. Either avoid manual overrides (regenerate from a new seed) or override onPrimary to match — the safe path is changing the seed, not individual roles.

Biggest to smallest.

display, headline, title, body, label — each with Large/Medium/Small.

Theme.of(context).textTheme.

Text('Title', style: Theme.of(context).textTheme.titleMedium);

title / body / label.

AppBar title → titleLarge; paragraphs → bodyLarge/bodyMedium; button label → labelLarge.

copyWith on the style.

Text('Pro', style: Theme.of(context).textTheme.titleLarge?.copyWith(
  color: Theme.of(context).colorScheme.primary,
));

What happens to the unlisted styles?

A fresh TextTheme(...) only populates the styles you pass; the others become null. copyWith/merge keep all 15 and override only the overlaps.

GoogleFonts.interTextTheme(base.textTheme).

final base = ThemeData(colorSchemeSeed: Colors.indigo);
ThemeData(
  colorScheme: base.colorScheme,
  textTheme: GoogleFonts.interTextTheme(base.textTheme),
);

You replaced instead of merged.

final base = ThemeData(colorSchemeSeed: Colors.indigo);
base.copyWith(
  textTheme: base.textTheme.copyWith(bodyLarge: const TextStyle(fontSize: 17)),
);

So it adapts to dark mode.

From the colorScheme (onSurface, onSurfaceVariant, primary, …) — not a hardcoded value — so it adapts between light and dark.

Heading styles vs manual formatting.

TextTheme is the document's style sheet; titleLarge/bodyMedium are named styles like "Heading 2." You apply the named style instead of manual sizes, and editing the sheet updates everywhere.

Keep vs discard.

base.merge(other) keeps all of base's styles and overrides the overlaps from other; a fresh TextTheme(...) discards everything not explicitly set.

Font first (merge to all), then copyWith one style; leave colors unset.

final base = ThemeData(colorSchemeSeed: Colors.indigo);
final tt = GoogleFonts.poppinsTextTheme(base.textTheme).copyWith(
  headlineSmall: base.textTheme.headlineSmall?.copyWith(fontWeight: FontWeight.w700),
);
ThemeData(colorScheme: base.colorScheme, textTheme: tt);

Leave text colors unset so the scheme supplies them per mode.

5 families × 3 sizes.

labelSmall + onSurfaceVariant.

final t = Theme.of(context);
Text('Updated now', style: t.textTheme.labelSmall?.copyWith(
  color: t.colorScheme.onSurfaceVariant,
));

Stripped theme; ?. / ??.

If a custom TextTheme left it unset. Guard with ?.copyWith(...) or style ?? const TextStyle(). The default Material theme populates all 15.

Size from one, color from the other.

Take size/weight from textTheme.<style> and color from colorScheme.<role> (often via .copyWith(color: ...)), so the text is both correctly scaled and correctly colored per mode.

headline / body / label.

final t = Theme.of(context).textTheme;
Column(children: [
  Text('Dashboard', style: t.headlineSmall),
  Text('Welcome back.', style: t.bodyMedium),
  Text('2m ago', style: t.labelSmall),
]);

One line re-skins all text.

GoogleFonts.<font>TextTheme(base.textTheme) — one call applies a typeface to all 15 styles.

Let the theme apply onSurface.

Often no — leaving it unset lets the theme apply the correct onSurface color automatically (adapting to light/dark). Set a color only for emphasis/intent, pulled from the scheme.

Font to all, then copyWith two heading styles.

Apply the font via GoogleFonts.xTextTheme(base.textTheme), then .copyWith(headlineLarge: ...w700, headlineSmall: ...w500). All other styles keep the font and defaults.

Tune the scale once.

You express what the text is (title, body, label); the scale defines how big in one place. Adjusting the scale updates every screen, and the code reads semantically.

Two themes + a selector.

theme, darkTheme, and themeMode.

Force one or follow OS.

ThemeMode.light, ThemeMode.dark, ThemeMode.system.

themeMode: ThemeMode.system + both themes.

MaterialApp(
  theme: lightTheme,
  darkTheme: darkTheme,
  themeMode: ThemeMode.system,
  home: const HomePage(),
);

Otherwise it falls back.

A non-null darkTheme. Without it, system falls back to theme even when the OS is dark.

Pass brightness to fromSeed.

ThemeData themeFor(Brightness b) =>
  ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF6750A4), brightness: b));

Inherited theme changes → rebuild.

themeMode swaps the active ThemeData; the inherited Theme changes; dependents that read colorScheme/textTheme rebuild and re-read the dark values — same widget code, dark output.

surface / onSurface.

final s = Theme.of(context).colorScheme;
Container(color: s.surface, child: Text('Hi', style: TextStyle(color: s.onSurface)));

Look for hardcoded white/black/hex.

Ask "did I hardcode a background or text color (Colors.white/Colors.black/hex)?" If yes, it'll break in dark mode — replace with a scheme role.

Effective theme vs OS setting.

Theme.of(context).brightness reflects the effective applied theme (respects an in-app themeMode override). MediaQuery.platformBrightnessOf reports only the OS setting.

Theme.of(context).brightness == Brightness.dark.

final isDark = Theme.of(context).brightness == Brightness.dark;
final logo = isDark ? 'assets/logo_light.png' : 'assets/logo_dark.png';

Brand consistency + less to maintain.

It keeps both modes on-brand (same hue and typography) and minimizes maintenance — there's one source of truth and a single deliberate difference (brightness) rather than two hand-authored palettes that can drift.

Build the world once; change the lens.

Your widgets are the world (built once). theme/darkTheme are two pairs of glasses (clear/tinted); themeMode chooses which is worn. The world doesn't change — the lens does.

SystemChrome.setSystemUIOverlayStyle.

SystemChrome.setSystemUIOverlayStyle(
  isDark ? SystemUiOverlayStyle.light : SystemUiOverlayStyle.dark,
);

(SystemUiOverlayStyle.light = light icons, for a dark background.)

Make it state.

Make themeMode user-controllable state (a Light/Dark/System setting) and persist it — the job of the Riverpod theming series.

Roles resolve per scheme.

Those roles resolve to light values in the light scheme and dark values in the dark scheme. Since the AppBar references roles (not hex), switching the active scheme re-colors it correctly with no change.

themeFor(light) / themeFor(dark).

MaterialApp(
  theme: themeFor(Brightness.light),
  darkTheme: themeFor(Brightness.dark),
  themeMode: ThemeMode.system,
  home: const HomePage(),
);

It's built into MaterialApp.

No — theme/darkTheme/themeMode are built into MaterialApp.

It read the OS, not the app.

MediaQuery.platformBrightnessOf(context) (OS setting), which ignores the in-app override. It should use Theme.of(context).brightness.

Honors an existing choice.

It honors the light/dark choice the user already made in their OS settings, rather than imposing one — and auto-switches when they change it.

Combine Parts 2–5.

const seed = Color(0xFF6750A4);
ThemeData themeFor(Brightness b) {
  final s = ColorScheme.fromSeed(seedColor: seed, brightness: b);
  return ThemeData(
    colorScheme: s,
    textTheme: appTextTheme,
    appBarTheme: AppBarTheme(backgroundColor: s.surface, foregroundColor: s.onSurface, elevation: 0),
  );
}
MaterialApp(
  theme: themeFor(Brightness.light),
  darkTheme: themeFor(Brightness.dark),
  themeMode: ThemeMode.system,
  home: const HomePage(),
);

Widget themedCard(BuildContext context) {
  final s = Theme.of(context).colorScheme;
  final t = Theme.of(context).textTheme;
  return Card(
    color: s.surfaceContainerHigh,
    child: ListTile(
      title: Text('Premium', style: t.titleMedium?.copyWith(color: s.onSurface)),
      subtitle: Text('Unlock all features',
          style: t.bodySmall?.copyWith(color: s.onSurfaceVariant)),
    ),
  );
}

Every color now comes from the scheme; the text sizes from the type scale.

ThemeData appTheme(Color seed, Brightness b) {
  final s = ColorScheme.fromSeed(seedColor: seed, brightness: b);
  return ThemeData(
    colorScheme: s,
    appBarTheme: AppBarTheme(
      backgroundColor: s.surface, foregroundColor: s.onSurface, elevation: 0,
    ),
    cardTheme: CardThemeData(
      shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(16)),
    ),
  );
}

ThemeData(
  colorSchemeSeed: Colors.indigo,
  elevatedButtonTheme: ElevatedButtonThemeData(
    style: ElevatedButton.styleFrom(
      shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(12)),
      textStyle: const TextStyle(fontSize: 14, fontWeight: FontWeight.w600),
    ),
  ),
  filledButtonTheme: FilledButtonThemeData(
    style: FilledButton.styleFrom(
      shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(12)),
    ),
  ),
);

final base = ThemeData(colorSchemeSeed: Colors.deepPurple);
final tt = GoogleFonts.poppinsTextTheme(base.textTheme).copyWith(
  headlineLarge: base.textTheme.headlineLarge?.copyWith(fontWeight: FontWeight.w700),
  headlineMedium: base.textTheme.headlineMedium?.copyWith(fontWeight: FontWeight.w700),
  headlineSmall: base.textTheme.headlineSmall?.copyWith(fontWeight: FontWeight.w700),
);
final theme = ThemeData(colorScheme: base.colorScheme, textTheme: tt);

Theme(
  data: Theme.of(context).copyWith(
    colorScheme: Theme.of(context).colorScheme.copyWith(
      primary: Colors.red, onPrimary: Colors.white,
    ),
  ),
  child: const DangerZone(),
)

Overriding onPrimary too keeps the contrast pair correct.

Widget chip(BuildContext c, String label, Color bg, Color fg) => Container(
  padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 4),
  decoration: BoxDecoration(color: bg, borderRadius: BorderRadius.circular(999)),
  child: Text(label, style: TextStyle(color: fg)),
);

// In build():
final s = Theme.of(context).colorScheme;
Wrap(spacing: 8, children: [
  chip(context, 'Error', s.errorContainer, s.onErrorContainer),
  chip(context, 'Info', s.secondaryContainer, s.onSecondaryContainer),
  chip(context, 'New', s.tertiaryContainer, s.onTertiaryContainer),
]);

(Material doesn't ship "success/warning" roles — for true brand semantic colors you'd add a ThemeExtension, the next theming topic.)

Widget status(BuildContext context) {
  final isDark = Theme.of(context).brightness == Brightness.dark;
  final s = Theme.of(context).colorScheme;
  return Column(children: [
    Text('Dark mode is ${isDark ? "ON" : "OFF"}'),
    Divider(color: s.outlineVariant),
  ]);
}

final base = ThemeData(colorSchemeSeed: Colors.teal);
final theme = base.copyWith(
  textTheme: base.textTheme.copyWith(
    bodyLarge: base.textTheme.bodyLarge?.copyWith(fontSize: 16),
  ),
);

Merging onto base.textTheme keeps the other 14 styles.

enum Brand { acme, globex }
const _seeds = {Brand.acme: Color(0xFF6750A4), Brand.globex: Color(0xFF00696D)};

ThemeData brandTheme(Brand brand, Brightness b) =>
  ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: _seeds[brand]!, brightness: b));

// usage:
MaterialApp(
  theme: brandTheme(Brand.acme, Brightness.light),
  darkTheme: brandTheme(Brand.acme, Brightness.dark),
  themeMode: ThemeMode.system,
);

Switching the Brand reskins the entire app — the whitelabel payoff from Part 1.

import 'package:flutter/material.dart';
import 'package:google_fonts/google_fonts.dart';

const _seed = Color(0xFF6750A4);

ThemeData _themeFor(Brightness b) {
  final s = ColorScheme.fromSeed(seedColor: _seed, brightness: b);
  final base = ThemeData(colorScheme: s, useMaterial3: true);
  return base.copyWith(
    textTheme: GoogleFonts.interTextTheme(base.textTheme),     // Part 4
    appBarTheme: AppBarTheme(                                  // Part 2
      backgroundColor: s.surface, foregroundColor: s.onSurface, elevation: 0,
    ),
    cardTheme: CardThemeData(
      shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(16)),
    ),
    filledButtonTheme: FilledButtonThemeData(
      style: FilledButton.styleFrom(
        shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(12)),
      ),
    ),
  );
}

void main() => runApp(const CapstoneApp());

class CapstoneApp extends StatelessWidget {
  const CapstoneApp({super.key});
  @override
  Widget build(BuildContext context) => MaterialApp(
    theme: _themeFor(Brightness.light),       // Part 3 + 5
    darkTheme: _themeFor(Brightness.dark),
    themeMode: ThemeMode.system,              // Part 5
    home: const HomeScreen(),
  );
}

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});
  @override
  Widget build(BuildContext context) {
    final s = Theme.of(context).colorScheme;  // Part 3
    final t = Theme.of(context).textTheme;    // Part 4
    return Scaffold(
      appBar: AppBar(title: const Text('Theming Capstone'), centerTitle: true),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Card(
              child: ListTile(
                title: Text('Welcome', style: t.titleMedium),       // role color via theme
                subtitle: Text('Fully themed — no hardcoded colors.',
                    style: t.bodyMedium?.copyWith(color: s.onSurfaceVariant)),
                trailing: Container(
                  padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 4),
                  decoration: BoxDecoration(
                    color: s.tertiaryContainer,
                    borderRadius: BorderRadius.circular(999),
                  ),
                  child: Text('New', style: t.labelSmall?.copyWith(
                    color: s.onTertiaryContainer)),
                ),
              ),
            ),
            const SizedBox(height: 16),
            FilledButton(onPressed: () {}, child: const Text('Get started')),
          ],
        ),
      ),
    );
  }
}

Which part each piece exercises: the seed→scheme and roles are Part 3; ThemeData assembly, copyWith, and global sub-themes are Part 2; the custom-font textTheme and named styles are Part 4; theme/darkTheme/themeMode and role-based adaptivity are Part 5; and the whole "no hardcoded colors in the screen" discipline is the thesis of Part 1. Run it, flip your OS to dark, and watch every pixel adapt without touching HomeScreen.