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
- One theme for every widget. Cupertino's widgets read a
CupertinoThemeData, the app's own widgets read theSpringTheme. Both are made from the same properties, so a button ofcupertino_uiand a card of your own show the same primary color. - No theme in Dart. The iOS look, the dark theme and any number of themes of your own are YAML. A designer changes them without a build of the code, and a theme can even arrive from a server at run time.
- Checked at the start. A misspelled key or a wrong color under
cupertinostops the start with the property's name, not the first screen that uses it.
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
- Theme properties: every key of
cupertino.* - The palette from a seed
- Themes in code
- Themes of the Flutter starter
- Colors
- Typography