govoplan-core/docs/THEMING.md

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. Each user may also choose a validated default, civic_blue, forest, or plum accent palette. Core applies it through data-palette; every module inherits the result through semantic tokens without module-specific CSS.

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.
• Palette defaults form a provenance chain: system, tenant, then an explicit user choice. Invalid stored values are ignored. Reset means inheritance and does not copy the current parent value into the child scope.
• A policy lock is separate from the default. A system lock wins over every child scope; otherwise a tenant lock suppresses a personal override. The authenticated profile reports the effective palette, source, inherited palette, and lock state.
• Tenant branding is a separate policy surface and must preserve contrast and status semantics in both modes.

Palette safety and scope

The Settings preview shows the chosen or inherited accent in every applicable light/dark preview before Save. Presets are checked for WCAG AA contrast in the theme contract. Arbitrary token overrides and branding import/export are not inferred from this preference and require their own governed follow-up.

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 root mode/palette behavior, preset contrast, and representative Campaign, Calendar, Files, and Mail token consumption. The check runs before a production WebUI build.