# Provide the theme

The theme role splits the theme between its provider and its template. A provider owns the look: the light and the dark theme of the app. The template of the role owns the theme mode that the user selects, the same with every provider. [How settings work](https://doc.saymyframe.com/concepts/settings.md#the-theme-mode-a-setting-of-a-role) describes the mode, and [Theme](https://doc.saymyframe.com/guides/theme.md) what the app has.

## The two functions

A provider generates two functions in `lib/core/theme/app_theme.dart`. Each takes the `BuildContext` of the root of the app and returns a `ThemeData`: `createLightTheme` one whose brightness is `Brightness.light`, and `createDarkTheme` one whose brightness is `Brightness.dark`. This file of a brick is all that a provider needs. It derives both themes from one color:

```dart title="bricks/seed_theme/__brick__/lib/core/theme/app_theme.dart"
import 'package:flutter/material.dart';

/// The colour that the light and the dark theme of the app derive their
/// colours from. Change it to give the app another look.
const Color seedColor = Colors.teal;

/// The light theme of the app.
///
/// The root of the app calls it each time it builds, so a change of this
/// file shows on a hot reload. [context] is the context of the root, above
/// its `MaterialApp`: it has neither the theme nor the localizations of the
/// app.
ThemeData createLightTheme(BuildContext context) => _themeOf(Brightness.light);

/// The dark theme of the app; see [createLightTheme].
ThemeData createDarkTheme(BuildContext context) => _themeOf(Brightness.dark);

/// The Material 3 theme of [brightness] in the colours of [seedColor]. What
/// both themes of the app share goes here, such as the shape of its
/// buttons.
ThemeData _themeOf(Brightness brightness) => ThemeData(
  colorScheme: ColorScheme.fromSeed(
    seedColor: seedColor,
    brightness: brightness,
  ),
);
```

The developer of the app edits this file for another look, so its comments say where each thing is changed.

A module whose brick has this file is a plain provider:

```dart
final class SeedThemeModule extends SmfModule {
  /// Creates the module.
  const SeedThemeModule();

  /// The id of the module.
  static const id = ModuleId('seed_theme');

  @override
  ModuleDescriptor get descriptor => const ModuleDescriptor(
        id: id,
        description: 'Light and dark Material 3 themes from one seed colour',
        kind: ModuleKinds.infrastructure,
        providers: [RoleProvider.plain(themeRole)],
      );

  @override
  List<Contribution> contribute(ModuleContext context) => [
        BrickContribution(seedThemeBundle),
      ];
}
```

## A provider with a font

The built-in [`material_theme`](https://doc.saymyframe.com/modules/material-theme.md) is a plain provider too. Its file is longer: a palette, text styles and the themes of the components. Its themes are in a font that the app bundles. The brick has the files of the font and their license in `assets/fonts/geist/`, and the module declares them in the pubspec of the app, next to its brick and its note for coding agents:

```dart
  @override
  List<Contribution> contribute(ModuleContext context) => [
        BrickContribution(materialThemeBundle),
        PubspecContribution.flutter(
          assets: const [fontLicenseFile],
          fonts: [
            PubspecFont(fontFamily, [
              for (final MapEntry(key: weight, value: file)
                  in fontFiles.entries)
                PubspecFontAsset(file, weight: weight),
            ]),
          ],
        ),
        AppEntryRole.agentSections.entry(
          themeRole.description,
          AgentNote(agentNote),
        ),
      ];
```

`fontFiles` maps each weight of the font to its file in the app, and `fontLicenseFile` is the license. With the files in the brick, the app gets no package for the font and loads none from the network. The license is an asset of the app, so that each copy of the app has it with the font. The note tells a coding agent where the colors and the font of the themes are, and what a change of the file must keep; see [Notes for coding agents](https://doc.saymyframe.com/extending/infrastructure-module.md#notes-for-coding-agents).

## What the role does itself

The template of the role does the rest, the same with every provider. It gives the root `MaterialApp` its `theme`, its `darkTheme` and its `themeMode`, keeps the theme mode that the user selects, saves it in the preferences and restores it, and gives the settings screen an entry that selects it. So a provider:

- keeps no mode of its own and adds no entry for the mode;
- sets none of the three arguments of the root, each of which takes one value. `smf create` stops with an error on a module that sets one of them in an app with the role;
- requires what the role requires, the preferences role. So an app with the provider has a module that provides the preferences, and the registry of the tests of the provider has one too.

## The context of the functions

The context that the two functions get is the one of the root widget: below the root wrappers and above the root `MaterialApp`, so it has neither the theme nor the localizations of the app.

A provider whose look is fixed leaves the context alone, as `material_theme` does. A provider whose look depends on state of its own, such as a color that the user picks, puts an inherited widget with that state among the root wrappers and reads it from the context in the two functions. The root rebuilds in the new look when that widget notifies. For a setting of its look, such a provider contributes an entry of its own to the settings screen, as [Add a setting](https://doc.saymyframe.com/extending/settings.md) shows.

## Tests

The tests of a provider select a mode with `appThemeMode.choose(mode)` and read it from `appThemeMode.value`, whichever module provides the role; see [Theme](https://doc.saymyframe.com/guides/theme.md#in-tests).

The contract harness checks that a provider generates the symbols its role requires and follows the rules of the role. See [Test a module](https://doc.saymyframe.com/extending/testing.md).

SMF's CI checks the theme in running apps, with every provider of the role that SMF has: the root takes each mode that code chooses, the screens get a light theme in the light mode and a dark one in the dark mode, with the color schemes that the two functions return, and the next start has the mode that was saved. [Contributing](https://doc.saymyframe.com/contributing.md#the-roles-at-run-time) lists these tests.
