The palette from a seed

A theme with a seed-color has the Material 3 palette of that color: the 46 color roles (primary, on-primary, surface-container, outline-variant, ...) for the theme's brightness, made by Material's own algorithm, ColorScheme.fromSeed. scheme-variant chooses how the seed becomes the roles, contrast how far apart a color and the color on it are, and any role written under colors.* wins over the made one.

Why

Forty-six roles in two brightnesses are ninety-two colors to choose and keep in step. With a seed, one brand color gives all of them, in tones that keep text readable on every surface, and the dark theme is the same seed with brightness: dark. The few roles a brand needs exactly (an error red, a surface) are set by hand on top.

Example

# lib/resources/application.yml
spring:
  flutter:
    theme:
      seed-color: '#0057B8'
      scheme-variant: tonal-spot
      colors:
        error: '#B3261E'          # set by hand: wins over the seed's
      themes:
        dark:
          brightness: dark        # the same seed, dark tones
        neon:
          seed-color: '#F5E000'
          scheme-variant: fidelity
        high-contrast:
          extends: light
          seed-color: '#000000'
          contrast: 1
spring.flutter.theme.seed-color=#0057B8
spring.flutter.theme.scheme-variant=tonal-spot
spring.flutter.theme.colors.error=#B3261E
spring.flutter.theme.themes.dark.brightness=dark
spring.flutter.theme.themes.neon.seed-color=#F5E000
spring.flutter.theme.themes.neon.scheme-variant=fidelity
spring.flutter.theme.themes.high-contrast.extends=light
spring.flutter.theme.themes.high-contrast.seed-color=#000000
spring.flutter.theme.themes.high-contrast.contrast=1

The properties

Key Values Default What it does
spring.flutter.theme.seed-color a color: '#RRGGBB', a Colors name (teal, deepPurple.shade200), a color object none The color the palette is made from
spring.flutter.theme.scheme-variant tonalSpot, fidelity, content, vibrant, expressive, monochrome, neutral, rainbow, fruitSalad, in any spelling (tonal-spot, fruit_salad) tonalSpot Which of Material 3's algorithms makes the palette
spring.flutter.theme.contrast a number from -1 to 1 0 The contrast between the roles: 0 is Material's standard, 1 the highest, -1 the lowest
spring.flutter.theme.colors.<role> a color made from the seed One role by hand, over the made palette

Each also goes inside a named theme (themes.<name>.seed-color). A variant or a contrast without a seed-color uses the seed of Material 3's baseline, #6750A4. A theme without any of the three has Flutter's baseline palette, the one of ThemeData(): close to the palette of #6750A4, not the same.

The seed is a color like any other, so it may be a reference (seed-color: $brand.blue, to a token) or an object ({ color: teal, mix: { with: white, amount: 20% } }).

Scheme variants

The variant decides how the seed becomes primary, secondary, tertiary and the neutral tones of the surfaces. Each is one of Material Color Utilities' schemes (DynamicSchemeVariant):

Variant What it does When to use it
tonalSpot Material 3's default. Calm colors of medium strength; secondary and tertiary are softer relatives of the seed, the surfaces nearly grey Most apps
fidelity Primary stays as close to the seed as the tones allow, even a strong one; the containers keep its hue and strength; tertiary is the seed's complementary hue The seed is a brand color that must show as it is
content Like fidelity, with tertiary a hue next to the seed's instead of its complement: made for a seed taken from content, such as the main color of an image A palette from an album cover or a photo
vibrant Primary keeps the seed's hue at the highest strength; secondary and tertiary are turned to neighbouring hues; the surfaces are tinted more Playful, colorful apps
expressive Primary's hue is turned away from the seed's, secondary and tertiary further; surprising combinations A distinctive look rather than a faithful one
monochrome Greys only: every role has no hue Black and white designs, a print or e-ink look
neutral Almost grey, with a hint of the seed in every role Calm tools, reading apps
rainbow Grey surfaces with no hue; primary of the seed's hue, tertiary turned well away from it Accents that need to differ clearly from each other
fruitSalad Colorful: primary and secondary turned away from the seed's hue, tertiary of the seed's hue Games, children's apps

An unknown variant fails the start and lists these nine.

Contrast

contrast moves every pair of roles (a color and the color shown on it: primary and on-primary, surface and on-surface) further apart or closer together.

Value What it gives
-1 Reduced contrast: softer, for decorative themes
0 Material 3's standard: text meets WCAG's 4.5:1 on its surface
0.5 Medium contrast, Android's "medium contrast" setting
1 High contrast, Android's "high contrast" setting: for low vision

Any number in between works; outside -1 to 1 fails the start. A high-contrast theme of its own lets a user choose it in the app:

spring:
  flutter:
    theme:
      seed-color: '#3F51B5'
      themes:
        high-contrast:
          extends: light
          contrast: 1
        high-contrast-dark:
          extends: dark
          contrast: 1

Roles by hand over the seed

A role written under colors.* replaces that one role; every other stays as the seed made it. A role may refer to another, set or made:

spring:
  flutter:
    theme:
      seed-color: teal
      scheme-variant: vibrant
      colors:
        secondary: '#0277BD'
        surface-container-low: '#E6F4F1'
        primary-container: { color: $colors.primary, alpha: 18% }
      themes:
        dark:
          brightness: dark
          colors:
            surface-container-low: '#10302E'

The palette of a theme is made in this order:

  1. The palette of the theme's brightness: Flutter's baseline, or with a seed, variant or contrast the one ColorScheme.fromSeed makes of them.
  2. The roles of colors.* over it.
  3. The references are resolved: a role that refers to $colors.primary gets the final primary.

The result is the theme's SpringThemeData.colorScheme (a SpringColorScheme, the Flutter starter's palette class with the same 46 roles) and, in the ThemeData, Material's ColorScheme with the same colors. Every role of the 46 is under colors.* by its name in kebab case; see Colors.

References to made roles

$colors.<role> reaches every role in the theme properties, set by hand or made from the seed, so components and styles follow the palette with only a seed set:

spring:
  flutter:
    theme:
      seed-color: deepPurple
      components:
        card: { color: $colors.surface-container }
        app-bar: { background-color: $colors.primary-container }
      styles:
        tag:
          fill: { color: $colors.tertiary, alpha: 12% }

A theme that changes the seed (ocean with seed-color: teal) changes every value that refers to a made role. In Dart:

final scheme = Theme.of(context).colorScheme;              // Material's ColorScheme
final same = SpringTheme.of(context).colorScheme;          // SpringColorScheme
Container(color: scheme.surfaceContainerHigh);

The generator's typed keys (context.theme.colors.<role>) exist for the roles you write under colors; a made role is read from the color scheme. See typed keys.

The same palette in the web page loader

The web page loader that the generator writes into web/index.html shows before Flutter runs, so it cannot ask Material for colors. The generator makes the palette itself, with the same algorithm (Material Color Utilities) from the same seed-color, scheme-variant and contrast, so a loader with color: $colors.primary shows the color the app shows a moment later:

spring:
  flutter:
    theme:
      seed-color: '#0057B8'
      loaders:
        dots: { kind: dots, color: $colors.primary, size: 10, count: 3 }
      splash:
        background: { color: $colors.surface-container-lowest }
        loader: dots

A theme without a seed, variant or contrast is the one place they can differ: the page loader then uses the palette of #6750A4, not Flutter's baseline. Set a seed, or the roles the loader uses, for an exact match. See the page loader and Loaders and the splash.

Errors

A value that is not a color, an unknown variant or a contrast outside -1 to 1 fails the start and names the property. Without a design starter, any of the three fails the start too:

Invalid theme property spring.flutter.theme.seedcolor (theme light): '#0057B8'; expected a design starter in the dependencies: seed-color, scheme-variant and contrast make a Material 3 palette, which spring_boot_starter_flutter_material (or spring_boot_starter_flutter_cupertino) calculates. Without one, set the roles under colors.

An app without a design library writes its roles under colors.* instead; what it does not set is Flutter's baseline. The Cupertino starter makes the same palette without Material, so a theme shared by a Material and a Cupertino app has the same colors in both.

In Spring (Java)

There is no counterpart. The algorithm is Material 3's (Material Color Utilities), as Flutter's ColorScheme.fromSeed runs it.

See also