Add Dark Mode (UI theme) toggle for foreground styling (not just background)

[zealsprince]

Context

User feedback now explicitly requests a Dark Mode toggle in addition to toning down the background.

We already have background theming issues (#10, #12, #16–#21) that mainly focus on page background. Dark Mode is broader: it should also adjust foreground surfaces (cards), text, borders, and button styles for comfortable prolonged use.

Problem

Even with calmer backgrounds or a background switcher, the site can still feel harsh if text/cards are not tuned for a darker UI. Users expect a cohesive dark theme where the entire UI adapts.

Goal

Ship a simple, accessible Dark Mode toggle that switches the site’s overall UI theme (foreground colors + surfaces), integrates with the existing theming foundation, and persists.

Requirements

UX

• Add a small toggle in the same top-right settings/panel as the background switcher.
  • Label: Dark mode
  • Control: switch/toggle
• Default behavior:
  • If user has never chosen: follow prefers-color-scheme (system).
  • If user chooses explicitly: persist and override system.

Behavior

• When Dark Mode is on:
  • Background can remain user-selected, but cards/surfaces/text should adapt.
  • Ensure readable contrast for headings, body text, links, and buttons.
• When off:
  • Return to light theme tokens.

Technical

• Implement via data-color-mode="light|dark" on document.documentElement.
• Define core CSS tokens for surfaces/foreground:
  • --text-primary, --text-secondary
  • --surface-1 (page content cards), --surface-2 (panels)
  • --border-color
  • --button-bg, --button-text (or reuse existing component styles)
• Persistence:
  • localStorage.roflbox.colorMode = "light"|"dark"|"system"
  • On load: apply stored value; if system, use media query.
• Respect reduced motion (no required animated transitions).

Accessibility

• Toggle is keyboard operable.
• Add aria-label="Toggle dark mode".
• Ensure focus states are visible in both modes.

Acceptance Criteria

• Dark mode changes foreground UI (cards/surfaces/text/buttons), not only the background.
• Default follows system preference if user hasn’t set a preference.
• Choice persists across reload.
• Works across all background presets (from Decide + document curated background preset list (names, thumbnails, contrast checks) for theme switcher #18) and with intensity control (Background customization: add “Background intensity” slider (saturation/opacity) for extra comfort #21) without breaking readability.

Related

• Consolidate background work: define theme tokens + ensure #10 default matches a #12 preset #16 (theme tokens foundation)
• Background switcher UX polish: unobtrusive control + solid colors + accessibility + persistence #17 (settings panel UX)
• Decide + document curated background preset list (names, thumbnails, contrast checks) for theme switcher #18 (preset backgrounds)
• Background settings panel: add small on-page preview + “Reset to default” CTA #20 (panel preview/reset)
• Background customization: add “Background intensity” slider (saturation/opacity) for extra comfort #21 (intensity slider)

Test Plan

• Manual: system set to dark -> first visit loads dark.
• Manual: toggle dark mode -> persists after refresh.
• Manual: switch backgrounds while in dark mode -> text/cards remain readable.
• Manual: keyboard navigate toggle + panel controls.

[zealsprince]

Prioritizing this issue based on repeated site feedback: the background remains too visually intense and readability is still the main complaint. This Dark Mode toggle for foreground UI is the highest-value next step because it improves cards, text, buttons, and overall comfort across all existing background presets.

@copilot Please take this next if/when assignment automation is unavailable. Keep scope focused on:

• data-color-mode="light|dark" on document.documentElement
• persistent light|dark|system behavior via localStorage
• readable foreground tokens for cards/surfaces/text/buttons/borders
• keyboard-accessible toggle in the existing settings UI
• compatibility with current background presets and future intensity control (Background customization: add “Background intensity” slider (saturation/opacity) for extra comfort #21)

Please keep the implementation narrowly scoped to the UI theme toggle and include a short manual test checklist in the PR description.