astro-website/openspec/changes/archive/2026-02-11-remember-theme/tasks.md

1. Theme Persistence Across Visits

• 1.1 Add cookie helpers in site/src/layouts/BaseLayout.astro to read/write a site_theme cookie (Path=/, SameSite=Lax, 1y TTL; Secure on HTTPS)
• 1.2 Update the head theme-init script in site/src/layouts/BaseLayout.astro to prefer localStorage, then cookie, then environment signals
• 1.3 Update the theme setter in site/src/layouts/BaseLayout.astro to keep localStorage and cookie in sync on user selection (cookie fallback when localStorage throws)

2. Umami Tracking For Theme Switch

• 2.1 Define event emission on user-initiated theme changes using window.umami.track("theme_switch", ...) (guarded when Umami is missing)
• 2.2 Use taxonomy fields for the event payload: target_id=theme.switch.<theme>, placement=theme_notch, include theme and prev_theme when available
• 2.3 Ensure theme restoration on page load does NOT emit theme_switch (only explicit user interaction)

3. Verification

• 3.1 Run npm run build and verify output includes cookie read fallback in the head init script
• 3.2 Run npm test and ensure no new failures are introduced
• 3.3 Manual: switch theme, reload, and confirm persistence; repeat with localStorage disabled to confirm cookie fallback