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

Why

Theme choice is part of a user's identity and comfort on the site; returning visitors should land in the theme they previously selected. We also need measurement to understand whether the theme switcher is being used and which themes are preferred.

What Changes

• Persist the user's selected theme across visits so returning users see the last-selected theme immediately.
• Add Umami tracking for theme selection changes so theme switch usage can be measured and segmented.
• Improve robustness of persistence by supporting either localStorage or a client-side cookie (cookie fallback when localStorage is unavailable).

Capabilities

New Capabilities

• (none)

Modified Capabilities

• site-theming: Extend theme persistence requirements to explicitly cover returning visits and define acceptable client-side persistence mechanisms / fallback behavior.
• analytics-umami: Add a custom event emitted from client-side code for theme selection changes (using Umami's JS API when needed).
• interaction-tracking-taxonomy: Define the theme selection event name and required event properties (at minimum target_id and placement, plus theme metadata).

Impact

• Frontend: update theme switcher behavior in site/src/layouts/BaseLayout.astro (persistence/fallback and event emission).
• Analytics: new Umami event(s) added; dashboards/filters can segment by selected theme and placement.
• Specs: update the modified capabilities above to reflect the new requirements.