Add cross-module operational and interaction contracts

docs/THEMING.md

@@ -0,0 +1,28 @@
+# 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.
+