
# 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

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

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

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

```yaml
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](../spring-boot-starter-flutter/themes/colors.md#the-color-roles).

## 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:

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

```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](../spring-core-dart-generator/flutter/typed-keys.md).

## 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:

```yaml
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](../spring-core-dart-generator/flutter/page-loader.md) and
[Loaders and the splash](../spring-boot-starter-flutter/themes/loaders.md).

## 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:

```text
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](../spring-boot-starter-flutter-cupertino/palette.md) 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](../spring-boot-starter-flutter/themes/colors.md): the 46 roles and how to write a color
- [Themes from properties](themes.md)
- [The palette of the Cupertino starter](../spring-boot-starter-flutter-cupertino/palette.md)
- [Tokens and references](../spring-boot-starter-flutter/themes/tokens-and-references.md)
- [Design libraries](../spring-boot-starter-flutter/design-libraries.md)
