docs: align UI/UX demo theme controls

[franksong2702]

Thinking Path

• The contributor contract index from docs: add contributor contract index #2503 now says UI/theme work should follow
  the current Theme + Skin model.
• docs/ui-ux/index.html and docs/ui-ux/two-stage-proposal.html still showed
  the old data-theme-only picker with legacy theme names.
• Those demo pages are linked from the new contract docs, so leaving them stale
  would keep a misleading contributor path alive.
• This PR updates only the docs/demo controls and adds a small static regression
  test so the pages do not drift back to the old model.

Refs #2502 and #2503.

What Changed

• Updated both docs/ui-ux/ demo pages to initialize as
  class="dark" data-skin="slate" instead of data-theme="slate".
• Replaced the old single-axis buttons (Default, Slate, Light,
  Solarized, Monokai, Nord, OLED) with:
  • Theme: System, Dark, Light
  • Skin: Default, Ares, Mono, Slate, Poseidon, Sisyphus,
    Charizard, Sienna, Catppuccin, Nous
• Updated the inline demo script to toggle .dark and data-skin, matching the
  current app contract.
• Added tests/test_uiux_docs_theme_contract.py to lock the demo docs to the
  current theme/skin axes.
• Added before/after screenshots for review.
• Added an Unreleased changelog note.

Why It Matters

The contract docs now point contributors at these UI/UX demos. If the demos keep
teaching the old theme model, contributors can still copy stale guidance even
after reading the new contract index.

This follow-up makes the public docs agree with each other:

• docs/CONTRACTS.md says the current appearance contract is Theme + Skin.
• docs/UIUX-GUIDE.md warns against stale data-theme-only guidance.
• The linked demo pages now show the same model.

Before / After

docs/ui-ux/index.html

docs/ui-ux/two-stage-proposal.html

Verification

• git diff --check
• rg -n "data-theme=|theme-btn|Solarized|Monokai|Nord|OLED" docs/ui-ux/index.html docs/ui-ux/two-stage-proposal.html
• python3 -m pytest tests/test_uiux_docs_theme_contract.py tests/test_docs_gitignore_policy.py -q
• npx playwright screenshot --channel=chrome --viewport-size=1280,260 ... for both demo pages before and after

Risks / Follow-ups

• This does not change the shipped app appearance picker or runtime settings.
• This does not implement PR-template or CI gates from the contract-index
  follow-up list.
• The two-stage proposal page still remains a proposal/demo page; this PR only
  updates its appearance controls.

Model Used

OpenAI GPT-5.5 via Codex, with local shell/git/gh tooling.

[nesquena-hermes]

Summary

Reading docs/ui-ux/index.html and docs/ui-ux/two-stage-proposal.html on this branch against origin/master, plus the real app's appearance contract at static/boot.js:1207-1255, the demo docs were several months out of date — they still wired the deprecated data-theme="slate|solarized|monokai|nord|oled" attribute API while the live app moved to a two-axis class="dark" + data-skin="..." model. This PR realigns the demos so contributors looking at the static inventory see the same shape they'll find in the real DOM.

Code reference

The new demo wiring at docs/ui-ux/index.html:826-855:

function applyDocAppearance() {
  const resolvedTheme = docTheme === 'system' ? (docThemeMq.matches ? 'dark' : 'light') : docTheme;
  document.documentElement.classList.toggle('dark', resolvedTheme === 'dark');
  if (docSkin === 'default') document.documentElement.removeAttribute('data-skin');
  else document.documentElement.dataset.skin = docSkin;
}

This matches the live app's behavior at static/boot.js:1252-1254 (_setResolvedTheme):

function _setResolvedTheme(isDark){
  document.documentElement.classList.toggle('dark',!!isDark);
  ...
}

and the skin axis lookup at static/boot.js:1217-1224 (_normalizeAppearance), which uses _VALID_THEMES (light|dark|system) for the mode axis and _VALID_SKINS (default|ares|mono|slate|poseidon|sisyphus|charizard|sienna|catppuccin|nous) for the skin axis. The PR's skin button list at docs/ui-ux/index.html:65-74 enumerates exactly those ten skins.

Diagnosis / Recommendation

The shape is correct. The legacy data-theme -> {theme, skin} map at static/boot.js:1204-1213 (Solarized -> {theme:'light', skin:'default'}, Monokai -> {theme:'dark', skin:'sisyphus'}, Nord -> {theme:'dark', skin:'slate'}, OLED -> {theme:'dark', skin:'default'}) is the upstream rationale for dropping those buttons from the demo: they were never a real axis, only a legacy compatibility translation. Good call to drop them rather than translate them.

The contract test at tests/test_uiux_docs_theme_contract.py:21-39 pins the right invariants:

assert 'data-theme="' not in html, f"{doc_path} should not use legacy data-theme"
assert 'class="dark" data-skin="slate"' in html
assert "classList.toggle('dark'" in html
assert "dataset.skin" in html

Worth adding one more assertion to that file: when a future skin is added to _VALID_SKINS in static/boot.js, the demo docs should stay in sync. A drift-detection test that loads static/boot.js for the _VALID_SKINS constant and asserts each entry has a data-skin-btn button in both demo HTML files would catch that. Not required for this PR, but a natural follow-up since both demos now share the same axis enumeration.

Two small nits:

1. The mediaquery listener uses docThemeMq.addEventListener guarded path but the older .addListener fallback isn't added. Modern browsers only — fine for a demo doc, would matter if this was production.
2. docTheme = 'dark' initial value is hardcoded, which matches class="dark" on <html>. If a maintainer wants the demo to honor prefers-color-scheme on first load (similar to how the live app handles initial appearance), it'd need a small docTheme = docThemeMq.matches ? 'dark' : 'light' setup before the listener wires up. Again, demo doc scope only.

Test plan

The new tests/test_uiux_docs_theme_contract.py covers the structural invariants. CI passes (per the diff stat + before/after screenshots in docs/ui-ux/uiux-theme-demo-controls/). For manual reproduction, open docs/ui-ux/index.html directly in a browser, click through System/Dark/Light + the ten skin buttons, and confirm the document re-paints to match each combination — which is exactly the workflow contributors use to preview a new skin without spinning up the app.

This is a small, scoped docs sync with a contract test guarding against drift back. Clean to merge.