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.
• User preference selects the mode and palette. Invalid stored palette values fail safely to default; the profile API accepts only the supported preset identifiers. 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.

Palette safety and scope

The current slice is intentionally user-level. The Settings preview shows the chosen accent in every applicable light/dark preview before Save, and Reset palette returns the draft to the GovOPlaN default before persistence. Presets are checked for WCAG AA contrast in the theme contract. Arbitrary token overrides, tenant/system defaults, branding import/export, and policy locks 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.