Flutter themes in YAML

With spring_boot_starter_flutter the look of an app lives in configuration, not in ThemeData code. You write colors, fonts, shapes, component styles, backgrounds and animations under spring.flutter.theme in application.yml. The starter reads them when the app starts into a theme of its own (SpringThemeData: the palette, the type scale, spacing, shapes, tokens, styles, backgrounds, motion), which every app has, one without a design library too. With a design starter the same theme also becomes Material's ThemeData (spring_boot_starter_flutter_material) or Cupertino's CupertinoThemeData (spring_boot_starter_flutter_cupertino). Designers can change the look in one file, per profile or per platform, without touching widgets.

A first theme

spring:
  flutter:
    theme:
      colors:
        primary: '#0057B8'
        on-primary: '#FFFFFF'
        surface: '#FAFAFA'
      typography:
        font-family: Inter
        title-large: { weight: 600 }
      shape:
        medium: 16
      spacing:
        m: 16

That is a complete theme, and it works in every app: one without a design library, a Material app and a Cupertino app. Everything you do not write keeps Flutter's Material 3 default: the roles you do not set come from Flutter's baseline palette, the text styles you do not set keep Material 3's type scale. A theme without any property is Flutter's own baseline.

Design libraries

spring_boot_starter_flutter knows no design library. What every design shares (the palette roles, typography, shapes, spacing, tokens, styles, motion, backgrounds, loaders, images) is on these pages. What belongs to one design is documented with its starter:

With a design starter, the first theme can be shorter: a seed makes all 46 roles.

spring:
  flutter:
    theme:
      seed-color: deepPurple    # needs a design starter
      typography:
        font-family: Inter

The examples of these pages that use a seed-color are for an app with a design starter; an app without one writes its roles under colors.* (see colors and design libraries).

Every value is checked at start. A misspelled key, a color that does not exist or a number where a word is expected stops the start with a message that names the property, the value and what is allowed, often with a "did you mean". Nothing is ignored silently. The properties of a design whose starter is not in the app (components, cupertino, and the others listed in properties of a design) are accepted, not checked, and named once in the log.

How a theme is chosen

There are three parts:

  1. The root of spring.flutter.theme is shared by every theme.
  2. light and dark always exist. Write themes.light or themes.dark to change only what differs in them.
  3. Any number of themes of your own live under themes.<name>. Each one holds only what it changes.
spring:
  flutter:
    theme:
      active: system          # system, or the name of a theme
      system-light: light     # what "system" shows in light mode
      system-dark: dark       # what "system" shows in dark mode

      seed-color: deepPurple  # shared by every theme

      themes:
        dark:
          seed-color: deepPurple.shade200
        ocean:
          seed-color: teal
          scheme-variant: vibrant
        ocean-night:
          extends: ocean      # start from ocean, not from the root
          brightness: dark
Key Where What it does
active root The theme shown at start. system (the default) follows the device's light or dark mode
system-light root The theme system shows when the device is in light mode. Default light
system-dark root The theme system shows when the device is in dark mode. Default dark
remember root Keeps the theme the user chooses between runs and shows it again while the splash shows. Default true
themes.<name> root A theme of your own, or a change to light or dark
extends in themes.<name> Starts the theme from another theme instead of the root. Chains work; a cycle or an unknown name stops the start

A theme is made in layers, each over the one before:

  1. its brightness (dark for the dark theme, otherwise light),
  2. the root, or the theme it extends,
  3. its own keys.

A list in a later layer replaces the whole list of an earlier one. References ($colors.primary) are resolved after the layers are put together, so a theme that changes colors.primary also changes everything that refers to it. See tokens and references.

Theme names and property names are compared without case, - and _. seed-color, seedColor and seed_color are the same key, and Ocean-Night and ocean_night are the same theme.

Choosing and switching at run time

The ThemeSelection bean holds the choice. A settings page calls select and the whole app changes at once.

selection.select('ocean');    // a theme
selection.select('system');   // follow the device again

The choice is kept between runs (remember: true, the default): ThemeSelection writes it into the app's files, and the next start shows it again while the splash shows, so a reload does not flash the default theme. A ThemeChoiceStore bean keeps it elsewhere, such as an account's settings on a server. Themes can also arrive at run time: themes.loadYaml(yaml) adds YAML from a server, and a theme can be downloaded from a URL by itself (see properties).

Read the theme in Dart

SpringTheme.of(context) has the whole theme, in an app of any type:

final theme = SpringTheme.of(context);
Container(
  padding: EdgeInsets.all(theme.space('m')),
  color: theme.colorScheme.surfaceContainer,
  child: Text(isbn, style: theme.textStyle('code')),
);

A design library's widgets read the theme in their own form: Material's from Theme.of(context) (see themes from properties), Cupertino's from CupertinoTheme.of(context).

Typed keys: context.theme

The build generator reads your properties and writes lib/spring_gen/theme.spring.keys.dart. From it, context.theme has a getter for every key you declare, so a renamed property is a compile error and not a surprise at run time:

context.theme.colors.surfaceContainerLow;   // Color
context.theme.spacing.m;                    // double
context.theme.typography.titleLarge;        // TextStyle
context.theme.tokens.brand.accent;          // Color
context.theme.styles.neonChip;              // AppStyleNeonChip, for ThemeStates
context.theme.motion.fast;                  // Duration
context.theme.motion.curves.out;            // Curve
context.theme.animations.borderSpin;        // AnimationSpec
context.theme.background;                   // ThemeBackgroundData?
AppThemes.ocean;                            // 'ocean', for ThemeSelection.select

Run dart run build_runner build after you add a key. The getters read the theme that is shown when they are called, so a theme switch gives the new values and the widget rebuilds. Only keys you declare are generated; the roles computed from the seed stay in SpringTheme.of(context).colorScheme (in a MaterialApp, also in Theme.of(context).colorScheme). Import spring_gen/main.spring.dart to use them.

Names become Dart names: - and _ start a new word (surface-container-low is surfaceContainerLow), a leading digit gets a $ in front (2xl is $2xl) and a Dart keyword gets a $ behind (default is default$). Two keys that give the same Dart name fail the build.

Pages of this reference

Page What it covers
Properties Every property of spring.flutter.theme and of a theme: active, extends, brightness, which design starter reads which, and a theme downloaded from a URL
Colors The 46 Material 3 color roles, the palette with and without a design starter, named colors, hex forms, alpha and mix
Typography The 15 text roles and code, every style key, fonts from assets
Shape, spacing and elevation The corner scale, spacing names and elevation levels
Tokens and references Your own values, how a value is typed, $ references and $$
Styles and states A look per state for your own widgets, state precedence, ThemeStates, the colors of code
Motion and animations Durations, curves, page transitions, animations.*, reduced motion
Background A color, an image, an overlay and a slow animation behind every screen
Loaders and the splash Spinners, dots, bars, skeletons, loaders of your own and the splash shown while the app starts
Images Images from assets or the network, with a cache, a refresh, a checksum and a fallback

The pages of a design are with its starter: Material's themes from properties, palette, density and ink and component themes; the Cupertino theme properties.

See also