trentuna/candle-annotator
8
0
Fork 0
Code Issues Pull requests Releases Packages Activity Actions
candle-annotator/openspec/specs/theme-switching/spec.md

3.3 KiB
Raw Permalink Blame History

ADDED Requirements

Requirement: System theme detection

The application SHALL detect the user's operating system color scheme preference on initial load and apply the matching theme (dark or light).

Scenario: System prefers dark mode

  • WHEN the user's OS is set to dark mode and no manual preference is stored
  • THEN the application renders with the dark theme

Scenario: System prefers light mode

  • WHEN the user's OS is set to light mode and no manual preference is stored
  • THEN the application renders with the light theme

Scenario: System preference changes while app is open

  • WHEN the user changes their OS color scheme while the app is open and theme is set to "system"
  • THEN the application switches to match the new system preference without page reload

Requirement: Manual theme toggle

The application SHALL provide a toggle control that cycles through three modes: System, Light, and Dark.

Scenario: Toggle from system to light

  • WHEN user clicks the theme toggle while in "system" mode
  • THEN the theme switches to "light" mode regardless of system preference

Scenario: Toggle from light to dark

  • WHEN user clicks the theme toggle while in "light" mode
  • THEN the theme switches to "dark" mode regardless of system preference

Scenario: Toggle from dark to system

  • WHEN user clicks the theme toggle while in "dark" mode
  • THEN the theme switches to "system" mode and applies the current OS preference

Scenario: Toggle icon reflects current mode

  • WHEN the theme is set to "system"
  • THEN the toggle displays a monitor icon
  • WHEN the theme is set to "light"
  • THEN the toggle displays a sun icon
  • WHEN the theme is set to "dark"
  • THEN the toggle displays a moon icon

Requirement: Theme preference persistence

The application SHALL persist the user's theme choice in localStorage so it survives page refreshes and browser restarts.

Scenario: Preference survives refresh

  • WHEN user selects "dark" mode and refreshes the page
  • THEN the application loads in dark mode without flashing light mode first

Scenario: Clearing preference

  • WHEN user selects "system" mode
  • THEN the stored preference is set to "system" and the OS preference is followed

Requirement: No flash of incorrect theme (FOUC prevention)

The application SHALL apply the correct theme before the first paint to prevent a visible flash of the wrong color scheme.

Scenario: Dark mode user loads page

  • WHEN a user with dark mode preference stored loads the page
  • THEN the page renders dark from the first visible frame with no white flash

Scenario: Light mode user loads page

  • WHEN a user with light mode preference stored loads the page
  • THEN the page renders light from the first visible frame with no dark flash

Requirement: ThemeProvider integration

The application SHALL use a ThemeProvider component wrapping the app in the root layout. The provider SHALL use the class strategy to add/remove the dark class on the <html> element.

Scenario: Dark class applied

  • WHEN the active theme is dark
  • THEN the <html> element has the dark class

Scenario: Dark class removed

  • WHEN the active theme is light
  • THEN the <html> element does NOT have the dark class