
# 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 the `SpringTheme`. Both are made from the same properties, so a button of `cupertino_ui` and 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 `cupertino` stops 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:

```yaml
# 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'
```

```properties
# 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](app-widget.md)).

## 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](../spring-boot-starter-flutter/themes/background.md) 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](../spring-boot-starter-flutter/themes/tokens-and-references.md)) |

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](theme-properties.md#text-styles)).

## 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](theme-properties.md) |
| The Material 3 palette of `seed-color`, `scheme-variant` and `contrast`, without Material | [The palette from a seed](palette.md) |
| `motion.page-transition: cupertino`, and `platform` as the iOS slide in a Cupertino app | [Page transitions](page-transitions.md) |
| The `CupertinoApp` that shows the theme | [The app widget](app-widget.md) |
| `CupertinoThemeCustomizer` beans and a replacing `CupertinoThemeData` bean | [Themes in code](themes-in-code.md) |

## 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](../spring-boot-starter-flutter-material/index.md), `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](themes-in-code.md)).

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

```dart
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](../spring-boot-starter-flutter/themes/index.md#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](../spring-boot-starter-flutter/themes/properties.md#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.

```dart
@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')),
  );
}
```

```yaml
# 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>`:

```yaml
spring:
  flutter:
    theme:
      themes:
        ocean:
          cupertino:
            primary: blue        # the key is primary-color
```

```text
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](../spring-boot-starter-flutter/design-libraries.md#what-is-accepted-unchecked).

## 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.

```dart
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](theme-properties.md): every key of `cupertino.*`
- [The palette from a seed](palette.md)
- [Themes in code](themes-in-code.md)
- [Themes of the Flutter starter](../spring-boot-starter-flutter/themes/index.md)
- [Colors](../spring-boot-starter-flutter/themes/colors.md)
- [Typography](../spring-boot-starter-flutter/themes/typography.md)
