Give tooltips their own two theming tokens

[AllTerrainDeveloper]

Tooltips had no tokens of their own, so each one borrowed its surface and text colour from an unrelated family. Those pairings hold at the framework defaults and come apart under a custom desktop theme — and there was no name a theme could aim at to fix one without moving the other thing that token controls.

• .desktop-mode-dock__tooltip took its surface from --wpd-scrim, an overlay backdrop. The Neon Glass reference theme sets that to rgba( 6, 4, 24, 0.68 ) for its modals, which made every dock tooltip 68% opaque with the wallpaper reading through the label. Dropping the scrim's alpha to fix it would have made every modal backdrop opaque.
• .desktop-mode-content-graph__tooltip paired --wpd-surface-elevated with --wpd-fg-on-accent. A light theme sets the first light and leaves the second white — white text on a white chip. Retuning either would have moved raised strips, or the text on accent-filled buttons.

What changed

--desktop-mode-tooltip-bg / --desktop-mode-tooltip-fg are that name. All three tooltip surfaces read the dedicated token first, with their old chain as the fallback:

Surface	Sheet
Dock tile tooltip	assets/css/dock.css
Corkboard satellite tooltip	assets/css/content-graph.css
Site window entity hover card	assets/css/my-wordpress.css

Both tokens are left undeclared, matching the --wpd-* palette and the texture family: every site reads var( --desktop-mode-tooltip-bg, <the chain it always had> ), so an unthemed shell computes exactly the literals it did before. No default drift, no flag day.

No PHP needed — desktop_mode_sanitize_desktop_theme_tokens() already accepts anything matching ^--desktop-mode-[a-z0-9-]+$. Verified by running the real sanitizer over an updated manifest: nothing dropped.

Scope note

Secondary text inside the richer tooltips — the hover card's excerpt — still follows --wpd-fg-muted. These two tokens cover the surface and the primary text on it. A theme setting a dark tooltip-bg inside an otherwise-light palette would want a --desktop-mode-tooltip-fg-muted companion; I documented that boundary rather than expanding the surface with a third token unasked.

Docs

New Tooltips subsection under Shell tokens in docs/desktop-themes.md — the table, a JSON snippet, and why setting them explicitly is worth it.

Tests

tests/vitest/tooltip-tokens.test.ts pins both halves of the contract: each surface reads the token first with its exact prior fallback, and neither token is declared anywhere. Asserted against stylesheet text, because jsdom will not resolve a nested var() chain against undeclared properties — a computed-style assertion would prove nothing.

Gates: npm run build, lint, typecheck, and test:js (256 files / 2481 tests) all green. No PHP touched.

Testing

Hover any dock icon. For the other two: open Corkboard, click a node so satellites fan out, hover a satellite bubble; open the window named after your site and hover a post or user tile.

To exercise the tokens without a theme:

document.documentElement.style.setProperty( '--desktop-mode-tooltip-bg', '#7c5cff' );
document.documentElement.style.setProperty( '--desktop-mode-tooltip-fg', '#fff' );

Or upload this theme :)

neon-glass.zip

All three turn purple. removeProperty on both should return them to exactly their previous look — that's the undeclared-by-default half, and the part most worth confirming by eye.

🤖 Generated with Claude Code