New color roles in `ColorScheme` include seven tone-based surfaces and containers, and twelve accent colors for primary, secondary, and tertiary groups. This update deprecates three existing color roles: `background`, `onBackground`, and `surfaceVariant`. The `ColorScheme` constructed by the updated `ColorScheme.fromSeed` method now generates different values compared to the previous version, adapting to the Material Design 3 guidelines.
- Who is affected
- Applications and packages relying on the previous behaviour or signature. Code that uses ColorScheme, ColorScheme.fromSeed, ColorScheme.background and related APIs.
- Practical impact
- Behaviour or API differences that can break builds or change runtime behaviour.
- What action should I take?
- Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
Before and after (from the official guide)
| 1 | ColorScheme.fromSeed( | |
| 2 | seedColor: Color(0xFF0000FF), // Bright blue | |
| 3 | ) |
| 1 | ColorScheme.fromSeed( | |
| 2 | seedColor: Color(0xFF0000FF), // Bright blue | |
| 3 | + | dynamicSchemeVariant: DynamicSchemeVariant.fidelity, |
| 4 | ) |
Raw before / after
ColorScheme.fromSeed(
seedColor: Color(0xFF0000FF), // Bright blue
)ColorScheme.fromSeed(
seedColor: Color(0xFF0000FF), // Bright blue
dynamicSchemeVariant: DynamicSchemeVariant.fidelity,
)Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)
The differences caused by the updated ColorScheme.fromSeed and
the new color roles should be small and acceptable.
However, when providing a brighter seed color to ColorScheme.fromSeed,
it might construct a relatively darker version of ColorScheme.
To force the output to still be bright,
set dynamicSchemeVariant: DynamicSchemeVariant.fidelity in
ColorScheme.fromSeed. For example:
Code before migration:
ColorScheme.fromSeed(
seedColor: Color(0xFF0000FF), // Bright blue
)Code after migration:
ColorScheme.fromSeed(
seedColor: Color(0xFF0000FF), // Bright blue
dynamicSchemeVariant: DynamicSchemeVariant.fidelity,
)Material Design 3 removes 3 colors.
To configure the appearance of the material components,
background should be replaced with surface,
onBackground should be replaced with onSurface, and
surfaceVariant should be migrated to surfaceContainerHighest.
Code before migration:
final ColorScheme colorScheme = ColorScheme();
MaterialApp(
theme: ThemeData(
//...
colorScheme: colorScheme.copyWith(
background: myColor1,
onBackground: myColor2,
surfaceVariant: myColor3,
),
),
//...
)Code after migration:
final ColorScheme colorScheme = ColorScheme();
MaterialApp(
theme: ThemeData(
//...
colorScheme: colorScheme.copyWith(
surface: myColor1,
onSurface: myColor2,
surfaceContainerHighest: myColor3,
),
),
//...
)Custom components that used to look up ColorScheme.background,
ColorScheme.onBackground, and ColorScheme.surfaceVariant can look up
ColorScheme.surface, ColorScheme.onSurface and
ColorScheme.surfaceContainerHighest instead.
Code before migration:
Color myColor1 = Theme.of(context).colorScheme.background;
Color myColor2 = Theme.of(context).colorScheme.onBackground;
Color myColor3 = Theme.of(context).colorScheme.surfaceVariant;Code after migration:
Color myColor1 = Theme.of(context).colorScheme.surface;
Color myColor2 = Theme.of(context).colorScheme.onSurface;
Color myColor3 = Theme.of(context).colorScheme.surfaceContainerHighest;AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).
An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.
- Official migration guide
- Support tone-based surface and surface container ColorScheme roles
- Support fidelity variant for ColorScheme.fromSeed
- Introduce tone-based surfaces and accent color add-ons - Part 1
- Introduce tone-based surfaces and accent color add-ons - Part 2
- Enhance ColorScheme.fromSeed with a new variant parameter
- Source commit
- b3045439b7c0
- Source last updated
- Oct 21, 2026
- Last synchronized
- Oct 21, 2026
- Publication status
- published
Publication history
- Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.