Themes from properties

In an app with this starter, every theme of spring.flutter.theme.* is also a CupertinoThemeData, and the CupertinoApp shows the one of the theme picked. Without properties it is iOS's own look. What the properties set goes over it: the theme properties of the Flutter starter (palette, typography, background), then the cupertino section, which only this starter reads.

Why

Example

A light theme in iOS's system colors and a dark theme that changes only the colors. The cupertino values refer to palette roles ($colors.primary), so the dark theme needs no cupertino section of its own:

# lib/resources/application.yml
spring:
  flutter:
    theme:
      active: system           # follow the device: light or dark
      colors:
        primary: '#007AFF'
        on-primary: '#FFFFFF'
        tertiary: '#FF9500'
        surface: '#F2F2F7'
      typography:
        body-large: { size: 17, height: 1.3 }
        title-large: { size: 22, weight: bold }
      cupertino:
        primary-color: $colors.primary
        primary-contrasting-color: $colors.on-primary
        scaffold-background-color: $colors.surface
        bar-background-color: { color: $colors.surface, alpha: 80% }
        selection-handle-color: $colors.tertiary
        text-theme:
          nav-title-text-style: { size: 17, weight: 600 }
      themes:
        dark:
          brightness: dark
          colors:
            primary: '#0A84FF'
            tertiary: '#FF9F0A'
            surface: '#000000'
# lib/resources/application.properties: the same
spring.flutter.theme.active=system
spring.flutter.theme.colors.primary=#007AFF
spring.flutter.theme.colors.on-primary=#FFFFFF
spring.flutter.theme.colors.tertiary=#FF9500
spring.flutter.theme.colors.surface=#F2F2F7
spring.flutter.theme.typography.body-large.size=17
spring.flutter.theme.typography.body-large.height=1.3
spring.flutter.theme.typography.title-large.size=22
spring.flutter.theme.typography.title-large.weight=bold
spring.flutter.theme.cupertino.primary-color=$colors.primary
spring.flutter.theme.cupertino.primary-contrasting-color=$colors.on-primary
spring.flutter.theme.cupertino.scaffold-background-color=$colors.surface
spring.flutter.theme.cupertino.bar-background-color.color=$colors.surface
spring.flutter.theme.cupertino.bar-background-color.alpha=80%
spring.flutter.theme.cupertino.selection-handle-color=$colors.tertiary
spring.flutter.theme.cupertino.text-theme.nav-title-text-style.size=17
spring.flutter.theme.cupertino.text-theme.nav-title-text-style.weight=600
spring.flutter.theme.themes.dark.brightness=dark
spring.flutter.theme.themes.dark.colors.primary=#0A84FF
spring.flutter.theme.themes.dark.colors.tertiary=#FF9F0A
spring.flutter.theme.themes.dark.colors.surface=#000000

No Dart: SpringApplicationWidget(home: ...) builds the CupertinoApp with this theme (see The app widget).

What comes from the core

These are the Flutter starter's theme properties. Every app reads them, of any type; this starter puts them into the CupertinoThemeData:

Theme property Where it shows in the CupertinoThemeData
brightness brightness: light or dark, and with it every iOS color that has a light and a dark value (CupertinoColors.label, the default backgrounds)
colors.primary primaryColor, when cupertino.primary-color is not set
colors.surface scaffoldBackgroundColor, when cupertino.scaffold-background-color is not set
background A theme with a background makes the scaffolds transparent, so the background shows through them
typography.font-family, typography.font-family-fallback The font of the eight iOS text styles
typography.<style> The size, weight, line height and letter spacing of the matching iOS text style (below)
any value, by reference $colors.primary, $brand.accent: a cupertino value may refer to any value of the theme (see Tokens and references)

Only the roles you declare under colors.* are taken: a palette made from a seed-color gives the primary color (below), but not the scaffold's background, which stays iOS's own unless colors.surface or cupertino.scaffold-background-color says otherwise.

Text styles from the typography

When the theme sets a typography (a font family, a fallback, or any text style), each of iOS's eight text styles takes the font, and what typography.* writes for the matching style of the theme:

Cupertino text style Takes from the theme
textStyle body-large
actionTextStyle label-large
tabLabelTextStyle label-small
navTitleTextStyle title-large
navLargeTitleTextStyle display-small
navActionTextStyle label-large
pickerTextStyle body-large
dateTimePickerTextStyle body-large

Only what the typography writes changes: a theme that sets title-large: { weight: bold } makes the navigation title bold and keeps iOS's 17 points. Without a typography and without cupertino.text-theme, the text theme is iOS's, untouched. A style written under cupertino.text-theme replaces the one made here (see Theme properties).

What the starter adds

What Where
The cupertino section: primary and contrasting colors, the backgrounds of scaffolds and bars, the selection handles, apply-theme-to-all, the eight text styles Theme properties
The Material 3 palette of seed-color, scheme-variant and contrast, without Material The palette from a seed
motion.page-transition: cupertino, and platform as the iOS slide in a Cupertino app Page transitions
The CupertinoApp that shows the theme The app widget
CupertinoThemeCustomizer beans and a replacing CupertinoThemeData bean Themes in code

How the theme is made

Of the CupertinoThemeData From
brightness The theme's brightness
primaryColor cupertino.primary-color, else colors.primary, else the primary color of the palette of seed-color, else iOS blue
primaryContrastingColor cupertino.primary-contrasting-color, else iOS's (white)
scaffoldBackgroundColor cupertino.scaffold-background-color, else colors.surface; transparent when the theme has a background; else iOS's (systemBackground)
barBackgroundColor cupertino.bar-background-color, else, in an app that also has the Material starter, components.app-bar.background-color, else iOS's translucent bar color
selectionHandleColor cupertino.selection-handle-color, else iOS's (blue)
applyThemeToAll cupertino.apply-theme-to-all, else false
textTheme iOS's eight styles, with the primary color in the action styles, the typography over them, then cupertino.text-theme.*

The theme is made once per theme read, then the CupertinoThemeCustomizer beans change it (see Themes in code).

Light, dark and system

The themes light and dark always exist; themes.<name> adds your own. active picks the theme shown at the start, and system (the default) follows the device, showing system-light or system-dark (by default light and dark). A device switching to dark mode shows the Cupertino theme of the dark theme at once, and so does a theme picked with the ThemeSelection bean:

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

The CupertinoThemeData always has the theme's brightness, never "follow the device" on its own. iOS's colors with a light and a dark value (the label color, the default backgrounds, the default bar color) therefore follow the theme shown, even when the user picked a dark theme on a light device.

A color written as #RRGGBB is one color in every theme. That is why the example writes its colors once, under colors, and lets cupertino refer to them: the dark theme changes colors.primary, and every value that refers to it follows. A theme can still set its own cupertino values (themes.dark.cupertino.bar-background-color); a theme that extends another inherits its cupertino section and changes only what it writes. See How a theme is chosen.

Themes loaded at run time

Themes can come in while the app runs: YAML from a server (SpringThemes.loadYaml), properties from code (SpringThemes.load), or a theme downloaded from a URL (see A theme from a URL). Their cupertino values are checked like those of the files, before anything changes: a wrong value throws and the app keeps its themes.

@Component()
class SeasonThemes {
  SeasonThemes(this.themes);

  final SpringThemes themes;

  Future<void> download() async => themes.loadYaml(
    await http.read(Uri.parse('https://cdn.example.com/themes.yml')),
  );
}
# themes.yml on the server
themes:
  winter:
    colors:
      primary: '#5AC8FA'
    cupertino:
      bar-background-color: '#E6F2F2F7'   # #AARRGGBB: 90% opaque

Each theme read again is made Cupertino again, the customizers run on it again, and the CupertinoApp shows the new values at once. SpringThemes.unload() goes back to the themes of the files.

Checked at the start

A wrong value or an unknown key under cupertino stops the start with the property's name and the valid keys, in the root and in every themes.<name>:

spring:
  flutter:
    theme:
      themes:
        ocean:
          cupertino:
            primary: blue        # the key is primary-color
Invalid theme property spring.flutter.theme.themes.ocean.cupertino.primary: 'blue'; expected a property of cupertino: primary-color, text-theme, primary-contrasting-color, scaffold-background-color, bar-background-color, selection-handle-color, apply-theme-to-all (did you mean 'primary-color'?).

In an app without this starter, a theme may still have a cupertino section: a theme library has it for the apps that use Cupertino. There it is accepted, not shown and not checked, and one INFO line of the log says so, once, naming this starter. See Design libraries.

The theme for the app's own widgets

SpringTheme.of(context) is the same theme for the widgets of the app: its palette with every role (colorScheme.surfaceContainer), its text styles, spacing and tokens. SpringTheme.of(context).toCupertino() is the CupertinoThemeData of the theme shown, as made from the properties (without the customizers); CupertinoTheme.of(context) is the one the app shows.

final theme = SpringTheme.of(context);
return Container(
  color: theme.colorScheme.surfaceContainer,
  padding: EdgeInsets.all(theme.space('m')),
  child: Text(
    'NEON',
    style: CupertinoTheme.of(context).textTheme.navTitleTextStyle,
  ),
);

See also