astro-website/openspec/changes/archive/2026-02-11-remember-theme/specs/site-theming/spec.md

ADDED Requirements

Requirement: Theme persistence works across visits with fallback

The site MUST persist the user's theme selection across visits so returning users see the last-selected theme.

The site MUST use client-side persistence and MUST support a fallback mechanism:

• Primary: localStorage
• Fallback: a client-side cookie

The effective theme selection order MUST be:

1. Stored theme in localStorage (if available)
2. Stored theme in a cookie (if localStorage is unavailable)
3. Default selection using environment signals

Scenario: LocalStorage persists across a later visit

• WHEN a user selects light theme and later returns to the site in the same browser
• THEN the site initializes in light theme before first paint

Scenario: Cookie fallback is used when localStorage is unavailable

• WHEN the browser environment blocks localStorage access and the user selects dark theme
• THEN the theme is persisted using a client-side cookie and is restored on the next visit

Scenario: No persistence available falls back to defaults

• WHEN both localStorage and cookie persistence are unavailable
• THEN the site falls back to default theme selection using environment signals