Theming done

2026-02-10 20:10:06 -05:00
parent 6cb4d55241
commit 70710239c7
19 changed files with 1260 additions and 42 deletions
--- a/openspec/specs/site-theming/spec.md
+++ b/openspec/specs/site-theming/spec.md
@@ -0,0 +1,59 @@
+## 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:
+- `dark`
+- `light`
+- `high-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 `light` theme and reloads the page
+- **THEN** the `light` theme 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:
+1) If forced colors / high-contrast mode is active, default to `high-contrast`
+2) Else if the system prefers light color scheme, default to `light`
+3) 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 `dark` to `light` theme
+- **THEN** theme-affecting properties transition smoothly instead of abruptly switching
+
+#### Scenario: Reduced motion disables theme animation
+- **WHEN** `prefers-reduced-motion: reduce` is set and the user switches theme
+- **THEN** the theme change occurs without noticeable animation