## 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 `` element. #### Scenario: Dark class applied - **WHEN** the active theme is dark - **THEN** the `` element has the `dark` class #### Scenario: Dark class removed - **WHEN** the active theme is light - **THEN** the `` element does NOT have the `dark` class