# 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.