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

ADDED Requirements

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