refactor: govern CSS tokens and cascade

docs/governance/architecture-inventory.json

@@ -244,6 +244,7 @@
     }
   ],
   "css_layers": [
+    "/shared/tokens.css?v=20260729-1",
     "/styles.css",
     "/renovation.css?v=20260725-5",
     "/redesign-v2.css?v=20260728-1",
@@ -259,23 +260,23 @@
     },
     {
       "path": "static/styles.css",
-      "bytes": 364385,
-      "lines": 15549
-    },
-    {
-      "path": "static/redesign-v2.css",
-      "bytes": 264960,
-      "lines": 8616
+      "bytes": 361780,
+      "lines": 15465
     },
     {
       "path": "server.py",
       "bytes": 263744,
       "lines": 5856
     },
+    {
+      "path": "static/redesign-v2.css",
+      "bytes": 263539,
+      "lines": 8570
+    },
     {
       "path": "static/index.html",
-      "bytes": 133815,
-      "lines": 1875
+      "bytes": 133880,
+      "lines": 1876
     },
     {
       "path": "database.py",
@@ -294,8 +295,8 @@
     },
     {
       "path": "static/renovation.css",
-      "bytes": 86245,
-      "lines": 1636
+      "bytes": 83949,
+      "lines": 1553
     },
     {
       "path": "static/wentian-v2.css",
@@ -309,8 +310,8 @@
     },
     {
       "path": "static/theme.css",
-      "bytes": 41279,
-      "lines": 1407
+      "bytes": 36427,
+      "lines": 1253
     }
   ]
 }

docs/governance/stage-16-css-tokens.md

@@ -0,0 +1,49 @@
+# Stage 16: CSS Tokens and Cascade Governance
+
+## Scope
+
+This stage changes CSS ownership, not visual design. Existing selectors, page geometry,
+responsive behavior, theme behavior, and the isolated Wentian visual layer remain intact.
+
+## Canonical Token Layer
+
+`static/shared/tokens.css` is the only owner of global application tokens. It is loaded before
+all application styles and follows a three-layer contract:
+
+1. Primitive tokens contain raw palette, dimension, elevation, and motion values.
+2. Semantic tokens describe interface meaning such as canvas, surface, border, text, action,
+   market direction, and warning states.
+3. Component tokens define shared card, control, shell, table, chart, and profile contracts.
+
+Dark mode overrides semantic and compatibility values in the same file. It does not redefine
+component geometry. The `--wt-*` namespace remains owned by `wentian-v2.css` because Wentian
+has a deliberately isolated visual language.
+
+## Compatibility
+
+The historical `--xb-*`, `--r2-*`, and flat variables such as `--blue`, `--line`, and `--up`
+remain compatibility aliases. Their effective light and dark values are unchanged. New CSS
+must use semantic or component tokens; compatibility names exist only so feature selectors can
+be migrated incrementally without a broad visual rewrite.
+
+The stylesheet order is fixed as:
+
+1. shared tokens;
+2. legacy/base styles;
+3. renovation and page redesign rules;
+4. canonical non-Wentian design-system rules;
+5. runtime theme selectors;
+6. isolated Wentian rules.
+
+## Enforcement
+
+`tests/test_css_governance.py` verifies the load order, the three token layers, single global
+ownership, compatibility coverage, and Wentian isolation. A new global `:root` token block in
+any legacy stylesheet fails the regression suite.
+
+## Residual Migration
+
+Page styles still contain literal values and historical variable references. Removing those is
+an incremental page-by-page task because blindly replacing them would risk changing already
+accepted visuals. Stage 16 establishes the ownership boundary that prevents new drift while
+leaving safe migration points for later stages.