2.4 KiB
2.4 KiB
Purpose
Define site-wide theme support (dark, light, high-contrast) using CSS tokens and an application mechanism that can switch across the entire UI.
Requirements
Requirement: Site themes
The site MUST support three themes:
darklighthigh-contrast
Themes MUST be applied by setting a data-theme attribute on the root document element (<html>).
Scenario: Dark theme active
- WHEN
data-theme="dark"is set on<html> - THEN the site's background, text, and component styling reflect the dark palette
Scenario: Light theme active
- WHEN
data-theme="light"is set on<html> - THEN the site's background, text, and component styling reflect the light palette
Scenario: High contrast theme active
- WHEN
data-theme="high-contrast"is set on<html> - THEN the site uses a high-contrast palette with a clearly visible focus ring and high-contrast borders
Requirement: Theme persistence
The site MUST persist the user's theme selection so it is retained across page loads and navigations.
Persistence MUST be stored locally in the browser (e.g., localStorage).
Scenario: Theme persists across reload
- WHEN the user selects
lighttheme and reloads the page - THEN the
lighttheme remains active
Requirement: Default theme selection
If the user has not explicitly selected a theme, the site MUST choose a default theme using environment signals.
Default selection order:
- If forced colors / high-contrast mode is active, default to
high-contrast - Else if the system prefers light color scheme, default to
light - Else default to
dark
Scenario: No stored preference uses system settings
- WHEN the user has no stored theme preference
- THEN the site selects a default theme based on forced-colors and prefers-color-scheme
Requirement: Theme switching transition
Theme changes initiated by the user MUST transition smoothly.
The transition MUST be disabled or substantially reduced when prefers-reduced-motion: reduce is set.
Scenario: Smooth transition on switch
- WHEN the user switches from
darktolighttheme - THEN theme-affecting properties transition smoothly instead of abruptly switching
Scenario: Reduced motion disables theme animation
- WHEN
prefers-reduced-motion: reduceis set and the user switches theme - THEN the theme change occurs without noticeable animation