Duolith docs

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/client exports colorScheme, state like network: colorScheme.choice is "system", "light" or "dark", colorScheme.isDark says what shows now, and colorScheme.choose(choice) changes it. Both getters are reactive.
  • The choice is kept on the device (in localStorage on 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, light or dark), and colorScheme.isDark and choose() read it, so isDark always says what shows and choose() never marks the root under a fixed theme.
  • On the web the choice is data-color-scheme on the root element. Under dark: system the emitter writes the dark tokens for the device setting unless the app chose light, and for the app's choice of dark; each dark: 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: system the app shell has a small blocking inline script in its head, before the stylesheet, that reads the choice from localStorage (inside try, so blocked storage only means the device setting) and sets data-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

OptionWhy not
A page style that redefines the colour tokens under a classOverlays 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 elementThe 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 moduleThe 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 timeOne 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 each dark: 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/theming shows one project theme.