[Task] Modern API Polish Pass

[conorluddy]

Context

Part of #8 (Web Components Migration).

Progressive enhancement layer — applying modern browser APIs for polish, performance, and delight. These are non-blocking improvements applied after the core migration works.

Scope

Modify:

• src/styles/tokens.css — CSS light-dark() migration
• src/styles/tokens.css — CSS color-mix(in oklch) for derived colors
• src/components/tb-tab-bar.js — View Transitions for tab switching
• src/components/tb-preset-bar.js — View Transitions for preset selection
• src/components/tb-flag-row.js — Popover API for flag description tooltips
• src/components/tb-flag-group.js — scheduler.postTask() for chunked rendering

Current State

After the core migration (issues #9-#20), the app works with standard CSS and synchronous rendering. Theme switching uses [data-theme="light"] overrides. Hover colors are hardcoded hex. Flag tooltips use title attribute. All 226 flag rows render synchronously. Tab switching is instant (no transition).

Target State

CSS light-dark() + color-scheme

Replace [data-theme="light"] { ... } override block with:

:root { color-scheme: light dark; }
--bg-primary: light-dark(#1d1e20, #f5f7f2);

Theme toggle sets document.documentElement.style.colorScheme.

CSS color-mix(in oklch)

Replace hardcoded hover/pressed colors:

--accent-hover: color-mix(in oklch, var(--accent) 80%, white);
--bg-hover: color-mix(in oklch, var(--bg-surface) 90%, white);

View Transitions API

Wrap tab content swaps in document.startViewTransition():

document.startViewTransition(() => { /* swap active tab pane */ });

With ::view-transition-old / ::view-transition-new CSS for crossfade.

Popover API

Replace title attribute on flag rows with styleable popover:

<button popovertarget="desc-FLAGKEY">i</button>
<div popover id="desc-FLAGKEY">Full description + impact + slider info</div>

scheduler.postTask()

In <tb-flag-group>, chunk flag row creation:

const chunk = flags.splice(0, 20);
// render chunk
if (flags.length) scheduler.postTask(() => renderMore(), { priority: 'background' });

Fallback: requestIdleCallback.

Implementation Hints

• light-dark() inverts the argument order from the current theme — verify colors map correctly
• color-mix() in oklch gives perceptually uniform results (better than srgb for derived states)
• View Transitions require the content swap to happen synchronously inside the callback
• Popover API: each popover needs a unique id — use the flag key
• scheduler.postTask() may not be available in all browsers — feature-detect and fallback
• These are all progressive enhancements — the app must work without them

Dependencies

• [Task] Root App Element + index.html Shell #20 — Root App + index.html Shell (core migration must be complete)

Definition of Done

• CSS uses light-dark() for all theme-varying tokens
• CSS uses color-mix(in oklch) for hover/derived states
• Tab switching has a smooth crossfade via View Transitions
• Flag descriptions show as styled popovers on click/hover
• Flag rows render in chunks (no jank on initial load)
• All features degrade gracefully in browsers without support
• No visual regressions in either theme

Verification

1. Toggle theme — verify smooth transition, all colors correct
2. Hover an accent element — verify derived color looks correct
3. Switch tabs — verify crossfade animation
4. Click info icon on a flag — verify popover appears with description
5. Hard-refresh — verify no jank from 226 flag rows loading
6. Test in Safari — verify graceful degradation of unsupported APIs