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:
- The palette of the theme's brightness: Flutter's baseline, or with a seed,
variant or contrast the one
ColorScheme.fromSeedmakes of them. - The roles of
colors.*over it. - The references are resolved: a role that refers to
$colors.primarygets the finalprimary.
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
- Colors: the 46 roles and how to write a color
- Themes from properties
- The palette of the Cupertino starter
- Tokens and references
- Design libraries