The palette from a seed
Every theme has a palette of 46 color roles (primary, on-primary, surface, surface-container, outline-variant, ...), under Material 3's names because they are the most complete set of names Flutter has. In a Cupertino app the roles come from two places: the ones you write under colors.*, and, with a seed-color, the palette this starter computes from it. It computes it with material_color_utilities, the color math of Material 3 that Material uses too, and without any of Material's widgets: the colors are those a Material app has from the same seed, variant and contrast.
Why
- One color gives all of them. Forty-six roles in two brightnesses are ninety-two colors to keep in step. With a seed, one brand color gives every role, in tones that keep text readable on every surface, and the dark theme is the same seed with
brightness: dark. - The same colors in both designs. An app that is Material on Android and Cupertino on iOS has one theme; both designs make the same palette of it, so the brand looks the same on both platforms.
- No Material in the build. A Cupertino app gets the palette without
material_ui. See The size of the app.
Example
# lib/resources/application.yml
spring:
flutter:
theme:
seed-color: '#0057B8'
scheme-variant: vibrant
colors:
error: '#FF3B30' # by hand: wins over the seed's
cupertino:
bar-background-color: { color: $colors.surface-container, alpha: 85% }
themes:
dark:
brightness: dark # the same seed, dark tones
colors:
error: '#FF453A'
high-contrast:
extends: light
contrast: 1
spring.flutter.theme.seed-color=#0057B8
spring.flutter.theme.scheme-variant=vibrant
spring.flutter.theme.colors.error=#FF3B30
spring.flutter.theme.cupertino.bar-background-color.color=$colors.surface-container
spring.flutter.theme.cupertino.bar-background-color.alpha=85%
spring.flutter.theme.themes.dark.brightness=dark
spring.flutter.theme.themes.dark.colors.error=#FF453A
spring.flutter.theme.themes.high-contrast.extends=light
spring.flutter.theme.themes.high-contrast.contrast=1
Explicit roles
A theme does not need a seed. The roles written under colors.* are the palette's, over Flutter's baseline palette (the Material 3 baseline), and this works in every app, with or without a design starter. The iOS look is often written this way, with Apple's system colors:
spring:
flutter:
theme:
colors:
primary: '#007AFF'
on-primary: '#FFFFFF'
secondary: '#34C759'
tertiary: '#FF9500'
error: '#FF3B30'
surface: '#F2F2F7'
on-surface: '#000000'
surface-container-lowest: '#FFFFFF'
outline: '#C6C6C8'
outline-variant: { color: $colors.outline, alpha: 50% }
Two of these roles also go into the CupertinoThemeData: colors.primary is its primary color and colors.surface its scaffold background, unless cupertino.* sets them (see Theme properties). Every role reaches the app's own widgets (SpringTheme.of(context).colorScheme) and every theme value ($colors.outline). See Colors for the 46 roles.
A seed and explicit roles mix: the seed makes every role, and those under colors.* replace theirs.
Seed, variant and contrast
| Key | Values | Default | What it does |
|---|---|---|---|
spring.flutter.theme.seed-color |
a color: #RRGGBB, a Colors name, a reference |
none: Flutter's baseline palette | The color the palette is made from |
spring.flutter.theme.scheme-variant |
tonalSpot, fidelity, monochrome, neutral, vibrant, expressive, content, rainbow, fruitSalad, in any spelling (tonal-spot) |
tonalSpot |
Which of Material 3's algorithms makes the palette |
spring.flutter.theme.contrast |
a number from -1 to 1 |
0 |
The contrast between a color and the color on it: 1 is the high contrast level, -1 reduced |
Each may be set per theme (themes.<name>.seed-color). A variant or a contrast without a seed-color uses the seed of Material 3's baseline (#6750A4). Without any of the three, the theme has Flutter's baseline palette, which needs no design starter. What each variant looks like is in the Material starter's palette.
The palette is made in this order:
- The palette of the theme's brightness: Flutter's baseline, or with a seed, variant or contrast the one of Material 3's algorithm.
- The roles of
colors.*over it. - The references: a value that refers to
$colors.primarygets the finalprimary, and a reference to a role nobody declared ($colors.surface-container) reads the palette of step 1.
Where the palette shows
- In the app's own widgets.
SpringTheme.of(context).colorSchemehas every role (surfaceContainer,outlineVariant, ...). - In the theme values.
$colors.<role>reaches every role, socupertino.*, styles, loaders and tokens follow the seed. - In the
CupertinoThemeData. Its primary color is the palette's primary when neithercupertino.primary-colornorcolors.primaryis set and the theme has aseed-color. The other roles do not go in by themselves: the scaffold stays iOS's background unlesscolors.surfaceorcupertino.scaffold-background-coloris set, so a seed alone does not repaint iOS's grey and white. Refer to the roles you want:scaffold-background-color: $colors.surface.
final scheme = SpringTheme.of(context).colorScheme;
return Container(
color: scheme.surfaceContainer,
child: Text('NEON', style: TextStyle(color: scheme.onSurface)),
);
The same colors as Material
The starter calls the algorithms of Material Color Utilities exactly as Flutter's ColorScheme.fromSeed does: the same variant classes, the same contrast level, and the surface tint as the primary color. Its tests compare all 46 roles with ColorScheme.fromSeed for eight seeds, both brightnesses, every variant and four contrasts.
In an app with both design starters, the palette is made by the design of the app's type, and both give the same colors.
The size of the app
Since Flutter 3.50, Material is not part of the SDK but the package material_ui, and an app carries it only if it depends on it. A Cupertino app that wanted Material 3's palette would have to depend on material_ui for one function, ColorScheme.fromSeed. This starter depends on material_color_utilities instead: pure Dart color math with no widgets, the same package material_ui itself computes with. The app's dependencies hold no Material, so none of it can end up in the build, and no Material widget can be imported by accident.
How much a design library weighs shows on this site, a Flutter web app built with Flutter 3.50: its bundle went from 4.39 MB with the 0.7 starter, which carried Material and Cupertino, to 3.53 MB without a design library (see The size of a build).
Without a design starter
seed-color, scheme-variant and contrast need a design starter: this one or the Material starter. Without one they fail the start, and an app without a design library writes its roles under colors.* instead:
Invalid theme property spring.flutter.theme.seed-color (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.
A value that is not a color, an unknown variant or a contrast outside -1 to 1 fails the start too, naming the property.
See also
- Colors: the roles, variants, contrast and color values
- The palette of the Material starter
- Theme properties
- Design libraries