Skip to main content

Feature: Theme Toggle

Purpose​

  • Feature name: Theme toggle
  • Why this feature exists: Allow reviewers to switch between light and dark themes while preserving accessibility.

Scope​

In scope​

  • cockpit-style rocker UI and interaction
  • persistence in local storage
  • system preference fallback
  • keyboard and focus-visible accessibility behavior

Out of scope​

  • CSS variable definitions (covered in theme system)
  • scroll animations (covered in navigation and UX polish)

Prereqs / Inputs​

  • client-side JavaScript enabled
  • prefers-color-scheme available in browser

Procedure / Content​

Feature summary​

  • Feature name: Theme toggle
  • Feature group: Theming and accessibility
  • Technical summary: A compact cockpit-style rocker (pivot/tilt, no sliding thumb) toggles html.light and html.dark classes, persists state in localStorage, and supports keyboard operation with accessible labeling.
  • Low-tech summary: A mode switch in the header flips between dark and light themes and remembers the choice.

Feature in action​

  • Where to see it working: Header on any route, such as / or /projects.

Confirmation Process​

Manual​

  • Steps: Toggle the rocker in the header, refresh, and verify persisted mode.
  • What to look for: The paddle tilts between states (no sliding track/knob), backlight is active in dark mode and dim/off in light mode, mode persists across reloads, and focus ring is visible during keyboard navigation.
  • Artifacts or reports to inspect: None.

Tests​

Potential behavior if broken or misconfigured​

  • Theme does not persist after reload.
  • Theme toggle causes hydration mismatch warnings.
  • Rocker tilt/backlight state drifts from active theme class.

Long-term maintenance notes​

  • Re-test after changes to layout or theme initialization scripts.
  • Keep rocker labels and semantics aligned with mode names used in UI copy.

Dependencies, libraries, tools​

  • Next.js App Router
  • React
  • Tailwind CSS

Source code references (GitHub URLs)​

ADRs​

Runbooks​

  • None.

Additional internal references​

Validation / Expected outcomes​

  • Theme toggle changes appearance immediately and persists across reloads.

Failure modes / Troubleshooting​

  • Theme does not persist: verify local storage usage.
  • Flash of wrong theme: validate pre-hydration script.

References​

  • None.