bulk commit changes!

openspec/changes/archive/2026-02-13-p06-theming/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-12

openspec/changes/archive/2026-02-13-p06-theming/design.md

@@ -0,0 +1,68 @@
+## Context
+
+The current UI defaults to dark presentation and lacks a global theme control. Users with different preference and accessibility needs cannot choose light/system/high-contrast alternatives.
+
+This change introduces an icon-based theme switcher and persistent client-side preference restoration.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add a header theme switcher with system, light, dark, and high-contrast options.
+- Apply theme choice globally with minimal visual regression.
+- Persist preference in localStorage with cookie fallback.
+- Restore returning-user choice; default to system when unset.
+
+**Non-Goals:**
+- Server-side profile theme persistence.
+- Theme-specific content changes.
+- Full design-system rewrite.
+
+## Decisions
+
+### Decision: Centralize theme state on `document.documentElement`
+**Decision:** Set a root theme attribute/class and drive color tokens from CSS variables.
+
+**Rationale:**
+- Single source of truth for whole page styling.
+- Works with existing Tailwind utility classes via custom CSS variable bridge.
+
+**Alternatives considered:**
+- Component-level theming flags: rejected due to drift and maintenance overhead.
+
+### Decision: Keep system mode dynamic via `prefers-color-scheme`
+**Decision:** For `system`, listen to media query changes and update resolved theme automatically.
+
+**Rationale:**
+- Matches user OS preference behavior.
+
+**Alternatives considered:**
+- One-time system snapshot: rejected as surprising for users changing OS theme at runtime.
+
+### Decision: Use icon-only options with accessible labels
+**Decision:** Theme controls are icon buttons with ARIA labels and visible selected state.
+
+**Rationale:**
+- Meets UX requirement while preserving accessibility.
+
+**Alternatives considered:**
+- Text dropdown: rejected due to explicit icon requirement.
+
+## Risks / Trade-offs
+
+- **[Risk] Existing hardcoded color classes may not adapt perfectly** -> Mitigation: prioritize core surfaces/text and progressively map remaining variants.
+- **[Risk] High-contrast mode may expose layout artifacts** -> Mitigation: audit focus outlines, borders, and semantic contrast first.
+- **[Trade-off] Additional JS for persistence and media listeners** -> Mitigation: keep logic modular and lightweight.
+
+## Migration Plan
+
+1. Add theme tokens and root theme resolver.
+2. Implement icon switcher in header and state persistence.
+3. Wire system preference listener and fallback behavior.
+4. Validate across refresh/returning sessions and responsive breakpoints.
+
+Rollback:
+- Remove theme switcher and resolver, revert to existing dark-default classes.
+
+## Open Questions
+
+- Should high-contrast mode align with OS `prefers-contrast` in a later phase?

openspec/changes/archive/2026-02-13-p06-theming/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+The current UI is locked to dark presentation, which does not match all user preferences or accessibility needs. Adding multi-theme support now improves usability and lets returning users keep a consistent visual experience.
+
+## What Changes
+
+- Add a theme switcher in the top-right header area.
+- Support four theme modes: **system**, **light**, **dark**, and **high-contrast**.
+- Render theme options as icons (not text-only controls).
+- Persist selected theme in client storage with **localStorage as primary** and **cookie fallback**.
+- Restore persisted theme for returning users.
+- Use **system** as default when no prior selection exists.
+
+## Capabilities
+
+### New Capabilities
+- `theme-switcher-control`: Provide an icon-based theme switcher in the header with system/light/dark/high-contrast options.
+- `theme-preference-persistence`: Persist and restore user-selected theme using localStorage first, with cookie fallback.
+- `theme-default-system`: Apply system theme automatically when no saved preference exists.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- **Frontend/UI:** Header controls and global styling system updated for four theme modes.
+- **State management:** Client-side preference state handling added for theme selection and restoration.
+- **Accessibility:** High-contrast option improves readability for users needing stronger contrast.
+- **APIs/Backend:** No required backend API changes expected.

openspec/changes/archive/2026-02-13-p06-theming/specs/theme-default-system/spec.md

@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: System theme is default when no preference exists
+The system SHALL default to system theme behavior if no persisted theme preference is found.
+
+#### Scenario: No saved preference on first visit
+- **WHEN** a user visits the site with no stored theme value
+- **THEN** the UI resolves theme from system color-scheme preference
+- **AND** switcher indicates system mode as active
+
+#### Scenario: Persisted preference overrides system default
+- **WHEN** a user has an existing stored theme preference
+- **THEN** stored preference is applied instead of system mode
+- **AND** user-selected theme remains stable across reloads

openspec/changes/archive/2026-02-13-p06-theming/specs/theme-preference-persistence/spec.md

@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: Theme choice persists across sessions
+The system SHALL persist user-selected theme with localStorage as primary storage and cookie fallback when localStorage is unavailable.
+
+#### Scenario: Persist theme in localStorage
+- **WHEN** localStorage is available and user selects a theme
+- **THEN** selected theme is saved in localStorage
+- **AND** stored value is used on next visit in same browser
+
+#### Scenario: Cookie fallback persistence
+- **WHEN** localStorage is unavailable or blocked
+- **THEN** selected theme is saved in cookie storage
+- **AND** cookie value is used to restore theme on return visit

openspec/changes/archive/2026-02-13-p06-theming/specs/theme-switcher-control/spec.md

@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: Header provides icon-based theme switcher
+The system SHALL display a theme switcher in the top-right header area with icon controls for system, light, dark, and high-contrast modes.
+
+#### Scenario: Theme options visible as icons
+- **WHEN** a user views the header
+- **THEN** all four theme options are represented by distinct icons
+- **AND** each option is keyboard-accessible and screen-reader labeled
+
+#### Scenario: Theme selection applies immediately
+- **WHEN** a user selects a theme option
+- **THEN** the page updates visual theme without full page reload
+- **AND** selected option has a visible active state

openspec/changes/archive/2026-02-13-p06-theming/tasks.md

@@ -0,0 +1,26 @@
+## 1. Theme Foundation
+
+- [x] 1.1 Define root-level theme state model for system, light, dark, and high-contrast
+- [x] 1.2 Add CSS token/variable mapping so all theme modes can be resolved consistently
+
+## 2. Theme Switcher UI
+
+- [x] 2.1 Add icon-based theme switcher control to top-right header area
+- [x] 2.2 Provide accessible labels and active-state indication for each icon option
+
+## 3. Theme Preference Persistence
+
+- [x] 3.1 Persist selected theme in localStorage when available
+- [x] 3.2 Implement cookie fallback persistence when localStorage is unavailable
+- [x] 3.3 Restore persisted preference for returning users
+
+## 4. System Default Behavior
+
+- [x] 4.1 Apply system mode when no persisted preference exists
+- [x] 4.2 Ensure saved user preference overrides system default on subsequent visits
+
+## 5. Validation and Documentation
+
+- [x] 5.1 Validate theme switching and persistence across refreshes and browser restarts
+- [x] 5.2 Validate icon controls with keyboard navigation and screen reader labels
+- [x] 5.3 Update README/docs with theme options and persistence behavior