Restructure CSS variables into three layers: ~15 primitives under
body / body.isDarkTheme (surface ramp, ink ramp, ink-on-channel triplet,
separators, scrim, brand, focus-ring), zero-specificity semantic aliases
under :where(body, body.isDarkTheme), and per-mode Cat-B tokens that
genuinely differ between light and dark. Promote interaction-state
tokens (--state-hover, --state-focus, --state-pressed, --state-selected,
--state-disabled-alpha) with velvet legacy-name var() fallbacks in the
base, so all 13 shipped themes are untouched.
Add a non-blocking contract-presence pass to validateThemeCss: missing
required/recommended tokens surface as warnings (presence-only — no
selector parsing), persist on the StoredTheme record, and a SnackService
toast lists them after install. The scanner blanks string-literal and
url-token contents before matching so `content: "--surface-1:"` cannot
suppress a real missing-token warning. Author docs/theming-contract.md
covering the selector contract, special tokens, and a fork-from-existing
example.
Two demo state-token migrations (dialog-user-profile-management,
dialog-restore-point); bulk sweep is a follow-up.
