
# 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](#the-size-of-the-app).

## Example

```yaml
# 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
```

```properties
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:

```yaml
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](theme-properties.md)). Every role reaches the app's own widgets (`SpringTheme.of(context).colorScheme`) and every theme value (`$colors.outline`). See [Colors](../spring-boot-starter-flutter/themes/colors.md#the-color-roles) 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](../spring-boot-starter-flutter-material/palette.md#scheme-variants).

The palette 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 of Material 3's algorithm.
2. The roles of `colors.*` over it.
3. The references: a value that refers to `$colors.primary` gets the final `primary`, 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).colorScheme` has every role (`surfaceContainer`, `outlineVariant`, ...).
- **In the theme values.** `$colors.<role>` reaches every role, so `cupertino.*`, styles, loaders and tokens follow the seed.
- **In the `CupertinoThemeData`.** Its primary color is the palette's primary when neither `cupertino.primary-color` nor `colors.primary` is set and the theme has a `seed-color`. The other roles do not go in by themselves: the scaffold stays iOS's background unless `colors.surface` or `cupertino.scaffold-background-color` is set, so a seed alone does not repaint iOS's grey and white. Refer to the roles you want: `scaffold-background-color: $colors.surface`.

```dart
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](../spring-boot-starter-flutter/design-libraries.md#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](../spring-boot-starter-flutter-material/palette.md). Without one they fail the start, and an app without a design library writes its roles under `colors.*` instead:

```text
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](../spring-boot-starter-flutter/themes/colors.md): the roles, variants, contrast and color values
- [The palette of the Material starter](../spring-boot-starter-flutter-material/palette.md)
- [Theme properties](theme-properties.md)
- [Design libraries](../spring-boot-starter-flutter/design-libraries.md)
