[material_ui] Add contrastLevel for M3 ColorScheme by QuncCccccc · Pull Request #11801 · flutter/packages

QuncCccccc · 2026-05-29T00:53:03Z

This PR is to add medium- and high-contrast M3 ColorScheme baselines. I also added a double? contrastLevel to ThemeData.

By default, ThemeData() shows standard M3 ColorScheme. To choose medium/high contrast, use

ThemeData(
  // brightness: Brightness.dark shows dark version of the baselines.
  contrastLevel: ContrastLevel.medium, // ContrastLevel.high
)

This change will not cause breaking changes because the standard-contrast m3 color scheme baseline stays the same.

TODO:
Add an example or update an existing example to reflect the new feature.

Pre-Review Checklist

QuncCccccc · 2026-07-31T22:46:14Z

      stdout.writeln('Generating contents...');
    }
-    final String contents = generateContents(_className);
+    final String contents = generateContents(requiresGeneratedClass ? _className : '');


We don't need a class for ColorScheme, so I added a requiresGeneratedClass field.

gemini-code-assist

Code Review

This pull request introduces support for Material 3 contrast levels in ThemeData by adding a contrastLevel parameter to the constructor. This allows standard, medium, high, or custom contrast levels to be applied when generating or selecting a ColorScheme. The generation of default color schemes is migrated to a new template (ColorSchemeTemplateM3), and corresponding unit tests are added. Feedback on the changes points out a broken documentation link referencing a non-existent public ThemeData.contrastLevel property, suggesting it be updated to refer to the constructor parameter instead.

gemini-code-assist · 2026-07-31T23:42:14Z

+/// A custom `double` between -1.0 and 1.0 can also be passed to
+/// [ThemeData.contrastLevel] when [ThemeData.colorSchemeSeed] is provided, in
+/// which case the value is passed to [ColorScheme.fromSeed].


The documentation references [ThemeData.contrastLevel], but ThemeData does not actually have a public contrastLevel property or getter (similar to colorSchemeSeed). This results in a broken documentation link. We should update the documentation to refer to the constructor parameter instead.

/// A custom double between -1.0 and 1.0 can also be passed as the /// contrastLevel parameter of the [ThemeData] constructor when /// [ThemeData.colorSchemeSeed] is provided, in which case the value is passed /// to [ColorScheme.fromSeed].

Updated documentation.

chunhtai

just some questions

chunhtai · 2026-08-05T02:09:45Z

    ColorScheme? colorScheme,
    Brightness? brightness,
    Color? colorSchemeSeed,
+    double? contrastLevel,


how does this work with MaterialApp. highContrastTheme and MaterialApp . highContrastDarkTheme? it feels like we are inventing another system.

Android also has contrast setting that can set contrast from -1 and 1 which felt like where the material design is based on. is there a good way a developer can set this value based on Android settings?

See flutter/flutter#182863

This PR is to add medium and high contrast ColorScheme baselines. See the M3 update section: https://m3.material.io/styles/color/system/overview#07f3a1d9-6c54-49f6-ae79-e52a6ee3e192

how does this work with MaterialApp. highContrastTheme and MaterialApp . highContrastDarkTheme?

MaterialApp( highContrastTheme: ThemeData(contrastLevel: ContrastLevel.high) highContrastTheme: ThemeData(brightness: Brightness.dart, contrastLevel: ContrastLevel.high) )

will provide default M3 colorSchemes with high contrast.

Android also has contrast setting that can set contrast from -1 and 1 which felt like where the material design is based on. is there a good way a developer can set this value based on Android settings?

We do have an api ColorScheme.contrastLevel to set -1.0 - 1.0 and build a color scheme. But I don't think it is wired up to Android contrast setting. Are there an Android API available so we can set it up? If so, maybe we can so it in a separate PR.

Are there an Android API available so we can set it up?

we don't have yet, but i think sooner or later we need to do so. Just want to make sure the api you propose here can be wired up in the future.

Is the intention to deprecate the highContrastTheme and other variant and solely relies on developer to create their own theme class by reading highcontrast double and brightness from mediaquery?

No, the intention is not to deprecate highContrastTheme or highContrastDarkTheme in this PR.

This PR is just to let ThemeData generate/select the right M3 ColorScheme for standard, medium, and high contrast. MaterialApp.highContrastTheme still has a broader role because it lets developers provide a complete high-contrast ThemeData, not only a different color scheme. Does this make sense?

elliette · 2026-08-05T23:13:40Z

+///    brightness, and contrast level.
+///  * <https://m3.material.io/styles/color/system/overview>, the Material 3
+///    color system overview.
+abstract final class ContrastLevel {


Disregard if this is not a normal Flutter pattern, but I wonder if we could make this an enhanced enum instead?

ThemeData could then take the enum as a parameter, whereas ColorScheme.fromSeed would take a double (and we could document that there are preset values in the ContrastLevel enum.)

ThemeData(contrastLevel: ContrastLevel.medium)

vs

ColorScheme.fromSeed(contrastLevel: ContrastLevel.medium.value)

This would disallow any non-supported levels in ThemeData, so we wouldn't need the warning comment about them being dropped.

Thanks for your review! I considered this, but I think keeping ThemeData.contrastLevel as a double better fits here.

ThemeData uses contrastLevel in two paths:

when colorSchemeSeed is provided, it forwards the value directly to ColorScheme.fromSeed, which supports the full -1.0..1.0 range;

when colorSchemeSeed is null, it selects among the token-backed baseline schemes, where only standard, medium, and high have generated tokens.

Using an enum would make the token-backed path stricter, but it would prevent ThemeData(colorSchemeSeed: Colors.red contrastLevel: 0.6), even though that is valid for ColorScheme.fromSeed. It would also make future system contrast integration
harder, since platform APIs may expose a continuous contrast value rather than only the three named presets.

So I’d prefer to keep the parameter as double?, with ContrastLevel.standard/medium/high as named constants for the token-backed baselines, and document that custom values only apply when a seed is provided. WDYT😄?

elliette

LGTM with one suggestion!

elliette · 2026-08-11T17:29:13Z

+  }
+
+  /// Whether the generated contents must declare the generated defaults class.
+  bool get requiresGeneratedClass => true;


Instead of adding requiresGeneratedClass, what if we simply override the className (like how outputFileName is being overridden?)

flutter-dashboard Bot added the CICD Run CI/CD label May 29, 2026

github-actions Bot added triage-framework Should be looked at in framework triage p: material_ui labels May 29, 2026

QuncCccccc force-pushed the m3e_migration branch from 129b42b to c410028 Compare June 15, 2026 22:40

QuncCccccc force-pushed the m3e_migration branch from 82410bd to 68877fe Compare July 1, 2026 22:06

QuncCccccc force-pushed the color_scheme_udpate branch 4 times, most recently from de5b083 to 6d663fa Compare July 23, 2026 18:29

QuncCccccc force-pushed the color_scheme_udpate branch 2 times, most recently from 4513c4f to e293b35 Compare July 30, 2026 22:53

QuncCccccc commented Jul 31, 2026

View reviewed changes

QuncCccccc requested review from Piinks and elliette July 31, 2026 23:40

QuncCccccc marked this pull request as ready for review July 31, 2026 23:40

gemini-code-assist Bot reviewed Jul 31, 2026

View reviewed changes

chunhtai reviewed Aug 5, 2026

View reviewed changes

elliette reviewed Aug 5, 2026

View reviewed changes

QuncCccccc force-pushed the color_scheme_udpate branch 2 times, most recently from 0e4fd51 to af390b8 Compare August 6, 2026 22:02

QuncCccccc added 10 commits August 10, 2026 10:33

Add contrastLevel for M3 color scheme

2a4d780

Update ContrastLevel doc

e67bd1c

Update ColorScheme template

df70e26

Update colorScheme template

14dffb4

Remove migrated ColorScheme files from temporarily_excluded

91c96fc

Use fallback tokens for contrast ColorSchemes

111dc72

Group fallback ColorScheme token roles

4670b1a

Clarify ContrastLevel docs

3f3359a

Clarify generated color scheme docs

f2f98c2

Consolidate ColorScheme generation docs

aa6ccea

QuncCccccc added 8 commits August 10, 2026 10:33

Rephrase contrast level docs

3e8a7e1

Add contrast level doc example

fddd749

Reorganize contrast level docs

86bfaf3

Use light color tokens in ColorScheme template

ca5cefd

Update contrast level docs

e3937ac

Remove redundant contrast level docs

bcc8a3d

Fix contrast level doc links

ab434a4

Format gen_defaults test

fd2108b

QuncCccccc force-pushed the color_scheme_udpate branch from af390b8 to fd2108b Compare August 10, 2026 17:46

elliette approved these changes Aug 11, 2026

View reviewed changes

Uh oh!

Conversation

QuncCccccc commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-Review Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chunhtai left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elliette Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elliette left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

QuncCccccc commented May 29, 2026 •

edited

Loading

chunhtai left a comment •

edited

Loading

elliette Aug 5, 2026 •

edited

Loading