# WebUI Theme Contract

GovOPlaN supports `system`, `light`, and `dark` as persisted user preferences.
`system` follows `prefers-color-scheme` live; it is not resolved permanently at
save time. Core applies the resolved mode through `data-theme` on the document
root and exposes the selected preference through `data-theme-preference`.

## Ownership

- Core owns semantic CSS tokens, native `color-scheme`, preference persistence,
  the Settings selector, and the shared shell.
- Modules consume semantic tokens such as `--surface`, `--text`, `--line`, and
  the status token families. They may define domain aliases whose values resolve
  to shared tokens.
- User preference selects the mode. Tenant and system policy may provide a
  future default, but must not silently replace an explicit user choice.
- Tenant branding is a separate policy surface and must preserve contrast and
  status semantics in both modes.

Do not introduce fixed foreground/background colors in a module merely to make
one mode look correct. Add or reuse a semantic Core token, then define both
light and dark values. Bitmap content and externally authored HTML are exempt,
but their surrounding controls must still use the shared tokens.

`npm run test:theme-contract` verifies the root behavior and representative
Campaign, Calendar, Files, and Mail token consumption. The check runs before a
production WebUI build.