Update the material 3 design token docs

[kevmoo]

This aligns the docs with the changes in
flutter/flutter#170000

[flutter-website-bot]

Visit the preview URL for this PR (updated for commit 447b04a):

https://flutter-docs-prod--pr12125-material-colors-docs-pr1700-sdfkve8o.web.app

[sfshaza2]

A few nits. :)

[Piinks]

Greetings from stale PR triage! 👋
This is dependent on flutter/flutter#170000. Are these changes still on your radar?

[sfshaza2]

Pinged kevmoo. He said he'll sync with Kate in the next week.

[kevmoo]

@Piinks is going to review the target flutter PR. When that lands I'll update this!

[kevmoo]

@sfshaza2 – this is ready!

Do we have a process for going back through these and updating after a release?

[rydmike]

First off, great that this bump is finally being done! Love it! 😄

@kevmoo as agreed on X/Twitter here is some nit details about the breaking change impact, that you may want to consider, or not 😏

User’s often find seed generated ColorScheme a bit complicated and confusing, and yes the algos are for from trivial.

Overall the existing breaking change info is good, maybe at least consider adding that it only impacts light mode generated color schemes. More complete impact info below.

Impact of update to MCU 0.13.0

• The expressive on-color breaking change for the tokens used by the default Material-3 ColorScheme in Flutter was released already with Flutter 3.22, where the tones for the light scheme on-colors for the default const token value defined ColorScheme changed as follows:
  • onPrimaryContainer: Primary10 to Primary30
  • onSecondaryContainer: Secondary10 to Secondary30
  • onTertiaryContainer: Tertiary10 to Tertiary30
  • onErrorContainer: Error10 to Error30
• This change does the same for any seed generated light ColorScheme.
• It only impacts seed generated ColorScheme results for above colors in light mode when the used dynamicSchemeVariant in ColorScheme.fromSeed is:
  • DynamicSchemeVariant.tonalSpot (the default one)
  • DynamicSchemeVariant.neutral
  • DynamicSchemeVariant.vibrant
  • DynamicSchemeVariant.expressive
  • DynamicSchemeVariant.rainbow
  • DynamicSchemeVariant.fruitSalad
• When using the following DynamicSchemeVariant in ColorScheme.fromSeed there is no change as they have had their own expressive tone exceptions a long time already:
  • DynamicSchemeVariant.fidelity - has had its own expressive on color tone exception since MCU 0.3.0
  • DynamicSchemeVariant.content - has had its own expressive on color tone exception since MCU 0.3.0
  • DynamicSchemeVariant.monochrome - has had its own on color expressive tone exception since MCU 0.4.0

For the above cases the seed generated ColorScheme results in more color expressive on-container colors in light mode, this is in-line with Material expressive color specification.

The new color combinations have a bit less contrast. The accepted min contrast curve is now ContrastCurve(3, 4.5, 7, 11) instead of ContrastCurve(4.5, 7, 11, 21) for the on-container colors. Meaning normal contrast of 4.5 is now accepted, when it was 7 before. The container color and its on-colors appear more colorful, but also loose a bit of contrast.

Visual demonstration

Visually the changes using Color(0xFF6750A4) and the default DynamicSchemeVariant.tonalSpot

   final ColorScheme schemeLight = ColorScheme.fromSeed(
      brightness: Brightness.light,
      seedColor: Color(0xFF6750A4),
      dynamicSchemeVariant: DynamicSchemeVariant.tonalSpot,
    );

Look like this:

Before

After

It is worth noticing that the generated tonal palettes do not change, only the used tones from them. Visually even though only the on-colors for primaryContainer, secondaryContainer, tertiaryContainer and onErrorContainer change, we perceive that the container colors themselves look and feel more colorful "expressive", when they use more colorful text and icons.

The above images where generated with https://rydmike.com/flexseedscheme/demo-v4/

Using the old tones?

There is way when using ColorScheme.fromSeed to get the old on-color tones back after this change.

For those that require them, for backwards compatibility or for contrast reasons, you can set colors back to previously computed seed values manually with overrides in ColorScheme.fromSeed.

Alternatively, with the 3rd party package https://pub.dev/packages/flex_seed_scheme you can seed and opt-out of this change. With on SeedColorScheme.fromSeeds you can seed as follows to opt-out of this change and get the legacy on-color tones:

   final ColorScheme schemeLight = SeedColorScheme.fromSeeds(
      brightness: Brightness.light,
      primaryKey: Color(0xFF6750A4),
      variant: FlexSchemeVariant.tonalSpot,
      useExpressiveOnContainerColors: false, // Opt out of new expressive on color tones
    );