
# Theme colors

A theme's palette is made from one **seed color**, in an app with a design
starter, or is Flutter's Material 3 baseline. You can then change any of the
46 Material 3 **color roles** by hand. Colors are written as names,
hex codes, references to other colors, or an object that changes the
opacity or mixes two colors.

```yaml
spring:
  flutter:
    theme:
      seed-color: '#0057B8'
      scheme-variant: vibrant
      contrast: 0.5
      colors:
        secondary: '#FFD700'
        error: '#B3261E'
        surface: '#FAFAFA'
        surface-container-low: grey.shade100
        outline-variant: { color: $colors.outline, alpha: 40% }
      themes:
        dark:
          seed-color: deepPurple.shade200
          colors:
            surface: '#121212'
```

## With and without a design library

The seed needs a design starter: `seed-color`, `scheme-variant` and
`contrast` make a Material 3 palette, and the algorithm is in the design
starters. The roles of `colors.*` work in every app.

| App | The palette |
|---|---|
| Without a design library (type `widgets`) | Flutter's Material 3 baseline (`SpringColorScheme.baseline`), with the roles of `colors.*` over it. A seed, a variant or a contrast stops the start |
| With [spring_boot_starter_flutter_material](../../spring-boot-starter-flutter-material/index.md) | Made from the seed with Material's `ColorScheme.fromSeed`, then `colors.*` |
| With [spring_boot_starter_flutter_cupertino](../../spring-boot-starter-flutter-cupertino/index.md) | The same palette, computed with `material_color_utilities`, without Material: the colors a Material app has from that seed |

The example above is for an app with a design starter. Without one, the start
fails with a message that says what to do:

```text
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 theme for an app without a design library writes its roles out:

```yaml
spring:
  flutter:
    theme:
      colors:
        primary: '#0057B8'
        on-primary: '#FFFFFF'
        primary-container: '#D6E3FF'
        on-primary-container: '#001B3D'
        surface: '#FAFAFA'
```

## Seed, variant and contrast

With a design starter, three properties make the palette instead of
Flutter's baseline: `seed-color`, the one color all 46 roles are made from;
`scheme-variant`, which of Material 3's nine algorithms makes them
(`tonalSpot`, `fidelity`, `vibrant`, ...); and `contrast`, from `-1` to `1`.
The Material and the Cupertino starters make the same colors from them.
Every variant, the contrast levels and examples are in
[the palette from a seed](../../spring-boot-starter-flutter-material/palette.md) of the Material starter (and
[of the Cupertino starter](../../spring-boot-starter-flutter-cupertino/palette.md)).

| Property | Type | Values | Default | What it does |
|---|---|---|---|---|
| `seed-color` | color | any color | Flutter's baseline palette | The color the palette is made from. Needs a design starter |
| `scheme-variant` | enum | `tonalSpot`, `fidelity`, `content`, `vibrant`, `expressive`, `monochrome`, `neutral`, `rainbow`, `fruitSalad` | `tonalSpot` | How the palette is made from the seed. Needs a design starter |
| `contrast` | number | `-1` to `1` | `0` | Palette contrast. Needs a design starter |
| `brightness` | enum | `light`, `dark` | by theme | Light or dark tones. See [properties](properties.md#brightness) |
| `colors.<role>` | color | any color | from the seed, else the baseline | Replaces one role of the palette. Works in every app |

## The color roles

`colors.<role>` takes any role below, in kebab case (`on-surface`). A role
you do not write comes from the seed (or, without one, from the baseline). A
role you do write replaces only that one role; the others stay as the seed
or the baseline made them.

### Primary, secondary and tertiary

Primary is the main accent: buttons, active controls, key components.
Secondary is for less prominent components such as filter chips. Tertiary is
for contrasting accents that balance primary and secondary.

| Role | What it is used for |
|---|---|
| `primary` | The main accent: filled buttons, switches that are on, focus rings, links |
| `on-primary` | Text and icons on `primary` |
| `primary-container` | A softer accent surface: a prominent card, a selected navigation indicator |
| `on-primary-container` | Text and icons on `primary-container` |
| `primary-fixed` | An accent surface whose color does not change between light and dark |
| `primary-fixed-dim` | A dimmer `primary-fixed`, for emphasis next to it |
| `on-primary-fixed` | Text and icons on `primary-fixed` and `primary-fixed-dim` |
| `on-primary-fixed-variant` | Lower-emphasis text and icons on the fixed colors |
| `secondary` | A less prominent accent: filter chips, tonal buttons |
| `on-secondary` | Text and icons on `secondary` |
| `secondary-container` | A soft surface for secondary components: tonal buttons, selected chips |
| `on-secondary-container` | Text and icons on `secondary-container` |
| `secondary-fixed` | A secondary surface that stays the same in light and dark |
| `secondary-fixed-dim` | A dimmer `secondary-fixed` |
| `on-secondary-fixed` | Text and icons on the secondary fixed colors |
| `on-secondary-fixed-variant` | Lower-emphasis text and icons on the secondary fixed colors |
| `tertiary` | A contrasting accent for balance: badges, highlights |
| `on-tertiary` | Text and icons on `tertiary` |
| `tertiary-container` | A soft surface for tertiary components |
| `on-tertiary-container` | Text and icons on `tertiary-container` |
| `tertiary-fixed` | A tertiary surface that stays the same in light and dark |
| `tertiary-fixed-dim` | A dimmer `tertiary-fixed` |
| `on-tertiary-fixed` | Text and icons on the tertiary fixed colors |
| `on-tertiary-fixed-variant` | Lower-emphasis text and icons on the tertiary fixed colors |

### Error

| Role | What it is used for |
|---|---|
| `error` | Errors: invalid fields, destructive actions, error text |
| `on-error` | Text and icons on `error` |
| `error-container` | A soft surface for an error message |
| `on-error-container` | Text and icons on `error-container` |

### Surfaces

Surfaces are the backgrounds of the app. The container roles are five steps
from the lowest to the highest, so cards and sheets can sit above the page.

| Role | What it is used for |
|---|---|
| `surface` | The default background of screens, cards and sheets |
| `on-surface` | Text and icons on any surface; the main text color |
| `on-surface-variant` | Lower-emphasis text and icons on surfaces: hints, secondary text |
| `surface-dim` | A surface that is always darker than `surface` |
| `surface-bright` | A surface that is always brighter than `surface` |
| `surface-container-lowest` | The lowest container step, for areas behind others |
| `surface-container-low` | A low container step: cards, sheets |
| `surface-container` | The middle container step: navigation bars, dialogs |
| `surface-container-high` | A high container step: menus, date pickers |
| `surface-container-highest` | The highest container step: text fields, segmented buttons |
| `surface-tint` | The color laid over a surface to show elevation in some components |

### Inverse, outline and system

| Role | What it is used for |
|---|---|
| `inverse-surface` | A surface that looks the opposite of the theme: snack bars |
| `on-inverse-surface` | Text and icons on `inverse-surface` |
| `inverse-primary` | An accent shown on `inverse-surface`, such as the action of a snack bar |
| `outline` | Borders of text fields and outlined buttons; important dividers |
| `outline-variant` | Decorative dividers and lighter borders |
| `shadow` | The color of shadows |
| `scrim` | The color that dims the page behind a modal sheet or dialog |

Any other name under `colors` stops the start and lists the valid roles.

## Writing a color

A color value is one of these:

| Form | Examples | Notes |
|---|---|---|
| `#RGB` | `'#F00'` | Each digit is doubled: `#F00` is `#FF0000` |
| `#RRGGBB` | `'#FF40A0'` | Opaque |
| `#AARRGGBB` | `'#80FF0000'` | The first two digits are the opacity |
| A `Colors` name | `white`, `black`, `transparent`, `red`, `grey`, `deepPurple`, `black54`, `white70` | Flutter's `Colors` names |
| A shade | `red.shade200`, `deepPurple.shade700`, `redAccent.shade100` | `shade50`, `shade100` ... `shade900`; an accent family has 100, 200, 400 and 700 |
| A reference | `$colors.primary`, `$brand.accent` | A role or any value of the theme. See [tokens and references](tokens-and-references.md) |
| An object | `{ color: $colors.primary, alpha: 12% }` | A color with changes, below |

There is one form for a color with changes: the object. A role name alone
(`primary`) or a role with an opacity (`primary@12%`) is not a color; write
`$colors.primary`.

Notes:

- **Quote anything that starts with `#`** in YAML, or the rest of the line is
  a comment (also inside `{ ... }`).
- A `Colors` name can be written in camelCase (`deepPurple`), kebab case
  (`deep-purple`) or snake case (`deep_purple`). Names are case sensitive:
  `Red` is not a color.
- The families of Flutter's `Colors` are `red`, `pink`, `purple`,
  `deepPurple`, `indigo`, `blue`, `lightBlue`, `cyan`, `teal`, `green`,
  `lightGreen`, `lime`, `yellow`, `amber`, `orange`, `deepOrange`, `brown`,
  `grey` and `blueGrey`, each with `.shade50` to `.shade900`. Every colored
  family but `brown`, `grey` and `blueGrey` also has an accent family:
  `redAccent`, `pinkAccent`, `purpleAccent`, `deepPurpleAccent`,
  `indigoAccent`, `blueAccent`, `lightBlueAccent`, `cyanAccent`,
  `tealAccent`, `greenAccent`, `lightGreenAccent`, `limeAccent`,
  `yellowAccent`, `amberAccent`, `orangeAccent` and `deepOrangeAccent`,
  each with `.shade100`, `.shade200`, `.shade400` and `.shade700`
  (`pinkAccent.shade200`). `black87`, `black54`,
  `black45`, `black38`, `black26`, `black12`, `white70`, `white60`,
  `white54`, `white38`, `white30`, `white24`, `white12` and `white10` are the
  Flutter colors with that opacity.

### Opacity and mixing: the color object

A color with changes is an object. Only `color` is required:

```yaml
badge-fill:
  color: $colors.primary
  alpha: 12%
hover-fill:
  color: $colors.primary
  mix: { with: white, amount: 14% }
```

| Key | What it does |
|---|---|
| `color` | The color to start from: a plain color, a reference, or another object. Required |
| `mix` | `{ with: <color>, amount: <percent> }` moves the color that share of the way to `with` |
| `alpha` | Sets the opacity of the result to that share. It replaces the opacity the color had |

`mix` is applied first, then `alpha`, whatever the order of the keys. A
percent is `0%` to `100%`, or `0` to `1` (`12%` and `0.12` are the same).
A percent outside that range, a missing `color`, or a key that is not
`color`, `mix` or `alpha` stops the start and names the closest key
(`alfa` gives "did you mean 'alpha'"). The object works everywhere a color
does: `colors.*`, `seed-color`, tokens, styles (also per state), components
(also per state), `cupertino`, `background` and the colors of a gradient.
In a `.properties` file the object is written key by key:

```properties
spring.flutter.theme.colors.primary-container.color=$colors.primary
spring.flutter.theme.colors.primary-container.alpha=18%
```

```yaml
spring:
  flutter:
    theme:
      colors:
        primary: '#F5E000'
        primary-container: { color: $colors.primary, alpha: 18% }
        secondary-container:
          color: $colors.primary
          mix: { with: white, amount: 80% }
      tokens:
        glass: { color: '#FFFFFF', alpha: 8% }
```


Roles are not written by name in `colors`. To use one role in the definition
of another, or in `components` and `cupertino`, use a reference:
`$colors.primary`, `$colors.surface-container-low`; see
[components](../../spring-boot-starter-flutter-material/components/index.md).

## Read it in Dart

```dart
final theme = SpringTheme.of(context);               // any app type
theme.colorScheme.secondary;                         // a SpringColorScheme
theme.role('surface-container-low');                 // by name
final colors = Theme.of(context).colorScheme;        // Material apps only
```

`SpringThemeData.colorScheme` is a `SpringColorScheme`: the starter's own
palette class, with Material 3's 46 roles under the same names (`primary`,
`onSurface`, `surfaceContainerHigh`), `role(name)`, `roles`, `withRoles(...)`
and `SpringColorScheme.baseline(brightness)`. It is not Material's
`ColorScheme`. In a Material app, `Theme.of(context).colorScheme` is Material's
`ColorScheme` with the same roles (see
[themes from properties](../../spring-boot-starter-flutter-material/themes.md#reading-the-theme)); it exists in a
`MaterialApp` only.

With the generator, every role you declare under `colors` is typed:

```dart
context.theme.colors.surfaceContainerLow;   // Color
context.theme.colors.outline;               // a Material role also works
```

`context.theme.colors.<role>` gives the theme's own value, or the Material
role of that name from the palette. Roles you did not declare have no getter
(use `SpringTheme.of(context).colorScheme`).

## See also

- [Properties](properties.md): `brightness`, `seed-color`, `scheme-variant`, `contrast`
- [The palette from a seed](../../spring-boot-starter-flutter-material/palette.md): the scheme variants and contrast
- [Tokens and references](tokens-and-references.md): `$colors.primary` and color objects
- [Component themes](../../spring-boot-starter-flutter-material/components/index.md): colors of Material's buttons, cards and bars
- [Background](background.md): colors and gradients behind screens
- [Design libraries](../design-libraries.md): the palette with and without Material or Cupertino
