Now I remember the theme

openspec/specs/analytics-umami/spec.md

@@ -19,6 +19,7 @@ When Umami is enabled, the site MUST support custom event emission for:
 - `outbound_click`
 - `media_preview`
 - `media_preview_close`
+- `theme_switch`
 - a general click interaction event for all instrumented clickable items (per the site tracking taxonomy)
 
 Each emitted event MUST include enough properties to segment reports by platform and placement when applicable.
@@ -63,6 +64,26 @@ For content-related links (clickables representing a specific piece of content),
 - **WHEN** a user clicks a CTA inside the media modal (e.g., "View on YouTube")
 - **THEN** the system emits a `cta_click` event with `target_id`, `placement=media_modal`, `platform`, and `target_url`
 
+### Requirement: Theme switch tracking event
+When Umami is enabled, the site MUST emit a custom event when the user changes theme via the theme switcher UI.
+
+The site MUST emit the event using Umami's JavaScript API (`umami.track(...)`) so runtime properties can be included.
+
+The event name MUST be `theme_switch`.
+
+The emitted event MUST include, at minimum:
+- `target_id`
+- `placement`
+- `theme`
+
+#### Scenario: Theme switch emits event
+- **WHEN** a user selects `high-contrast` in the theme switcher notch
+- **THEN** the site emits a `theme_switch` event with `theme=high-contrast` and a stable `target_id`
+
+#### Scenario: Missing Umami does not break switching
+- **WHEN** Umami is not configured or the Umami script is not present
+- **THEN** theme switching and persistence still work and no browser error is thrown
+
 ### Requirement: Environment configuration
 The site MUST support configuration of Umami parameters (at minimum: website ID and script URL) without requiring code changes.
 

openspec/specs/interaction-tracking-taxonomy/spec.md

@@ -133,3 +133,25 @@ The taxonomy MUST prohibit including personally identifiable information (PII) i
 #### Scenario: Tracking includes only categorical metadata
 - **WHEN** tracking metadata is defined for a clickable item
 - **THEN** it contains only categorical identifiers (ids, placements, domains) and does not include user-provided content
+
+### Requirement: Theme switch event taxonomy
+The tracking taxonomy MUST define an event for theme switching.
+
+The event name MUST be `theme_switch`.
+
+The `theme_switch` event MUST include, at minimum:
+- `target_id`
+- `placement`
+- `theme`
+
+The event MUST include `prev_theme` when it is available.
+
+The taxonomy MUST define the `target_id` namespace for theme switching as:
+- `theme.switch.<theme>`
+
+The taxonomy MUST define the `placement` value for the theme switcher notch as:
+- `theme_notch`
+
+#### Scenario: Theme switch target_id is deterministic
+- **WHEN** a user selects `light` theme using the theme notch
+- **THEN** the event is emitted with `target_id=theme.switch.light` and `placement=theme_notch`

openspec/specs/site-theming/spec.md

@@ -33,6 +33,30 @@ Persistence MUST be stored locally in the browser (e.g., localStorage).
 - **WHEN** the user selects `light` theme and reloads the page
 - **THEN** the `light` theme remains active
 
+### 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
+
 ### Requirement: Default theme selection
 If the user has not explicitly selected a theme, the site MUST choose a default theme using environment signals.