astro-website/openspec/changes/archive/2026-02-11-dch-theming/tasks.md

1. Theme Tokens And Application

• 1.1 Add data-theme overrides in site/public/styles/global.css for light and high-contrast (keep :root as default dark)
• 1.2 Add color-scheme rules per theme so native form controls match (dark/light)
• 1.3 Add theme initialization script in site/src/layouts/BaseLayout.astro to set theme before first paint (stored preference → forced colors/high contrast → prefers-color-scheme)
• 1.4 Persist theme selection to localStorage and update data-theme on change
• 1.5 Implement scoped smooth transitions for user-initiated theme changes (no global transition on initial load)

2. Theme Switcher Notch UI

• 2.1 Add markup for a fixed-position right-side notch in site/src/layouts/BaseLayout.astro
• 2.2 Implement notch positioning below .site-header and below .subnav when present (compute top offset; handle resize)
• 2.3 Add notch hover animation (expand/slide) and ensure it feels intentional
• 2.4 Add keyboard and screen reader support (label, focus styles, keyboard selection)
• 2.5 Ensure notch does not overlap critical content on mobile (responsive rules; safe-area)

3. High Contrast Theme Verification

• 3.1 Ensure high-contrast theme has strong fg/bg contrast, obvious focus ring, and strong strokes on interactive elements
• 3.2 Add @media (forced-colors: active) adjustments to avoid illegible gradients and ensure system colors are respected

4. Verification

• 4.1 Run npm run build and verify output HTML includes the head theme-init script
• 4.2 Manual smoke test: switch themes on /, /videos, /podcast, /blog and verify persistence across reload
• 4.3 Manual a11y checks: keyboard-only interaction, focus visibility, prefers-reduced-motion behavior