0043. The app can choose its colour scheme at run time
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: examples gallery; theming (decision 0018)
Context
Decision 0018 lets theme.yaml say whether the app follows the device's light or dark setting (dark: system, the default) or is always light or always dark. That is fixed when the app is built. Many apps, and the examples gallery the owner asked for, offer a light/dark switch in their settings, and there was no way to write one: the web output put dark values behind @media (prefers-color-scheme: dark) only, so a page could reach them only by reaching into the document, which a page must not do (it would not work on iOS or Android).
Decision
@duolith/clientexportscolorScheme, state likenetwork:colorScheme.choiceis"system","light"or"dark",colorScheme.isDarksays what shows now, andcolorScheme.choose(choice)changes it. Both getters are reactive.- The choice is kept on the device (in
localStorageon the web), so the app opens as it was left; choosing"system"forgets it. - It applies when the theme follows the system. A theme that is always light or always dark stays so, since the project chose that at build time: the app shell writes the theme's setting on the root element as
data-theme-scheme(system,lightordark), andcolorScheme.isDarkandchoose()read it, soisDarkalways says what shows andchoose()never marks the root under a fixed theme. - On the web the choice is
data-color-schemeon the root element. Underdark: systemthe emitter writes the dark tokens for the device setting unless the app chose light, and for the app's choice of dark; eachdark:utility is written the same two ways, with the root condition inside:where(), so specificity and the cascade order between utilities (decision 0017) are unchanged. - The first paint already shows the kept choice: under
dark: systemthe app shell has a small blocking inline script in its head, before the stylesheet, that reads the choice fromlocalStorage(insidetry, so blocked storage only means the device setting) and setsdata-color-scheme. The runtime module loads later and takes over. Its text is fixed, so a Content-Security-Policy can allow it by the hash in docs/guide/styling.md. - On iOS and Android the choice will set the window's interface style.
Alternatives considered
| Option | Why not |
|---|---|
| A page style that redefines the colour tokens under a class | Overlays live in their own layer outside the screen, dark: utilities would not follow, and every app would copy the dark values by hand |
A dark value per screen or per element | The scheme is the app's, as on iOS and Android; mixing schemes on one screen is not something the targets do |
Setting data-color-scheme only from the runtime module | The page paints with the device's scheme first and switches when the module has loaded: a flash of the wrong scheme on every load |
| Switching between several themes at run time | One theme per build keeps every style worked out at build time; light and dark are the two sets of values a theme already has |
Consequences
- The gallery's Appearance screen, and any app's settings, can offer System, Light and Dark with
<SegmentedControl>bound to the choice. - Under
dark: system, the CSS for eachdark:utility is written twice. The theme CSS grows by one copy of the dark tokens. - Switching between whole themes (a second
theme.yaml) is still not possible at run time;examples/themingshows one project theme.