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.

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 Made from the seed with Material's ColorScheme.fromSeed, then colors.*
With spring_boot_starter_flutter_cupertino 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:

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:

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 of the Material starter (and of the Cupertino starter).

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

Opacity and mixing: the color object

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

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:

spring.flutter.theme.colors.primary-container.color=$colors.primary
spring.flutter.theme.colors.primary-container.alpha=18%
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.

Read it in 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); it exists in a MaterialApp only.

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

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