Prohlížeč zdrojového kódu

docs/specs/themes.md

Náhled Zdrojový kód

Spec: Light/Dark Theme Switching

  • Status: active
  • Created: 2026-03-05
  • Related code: app/javascript/controllers/theme_controller.js, app/views/layouts/application.html.erb, app/assets/stylesheets/_variables.scss, app/assets/stylesheets/rouge.scss

Overview

The application supports light and dark visual themes. The active theme is stored in localStorage and applied immediately on page load, so the user's preference persists across visits without a server round-trip. When no preference is saved, the browser's prefers-color-scheme media query is used as the default. A toggle button in the navigation bar lets users switch themes at any time.

Behaviour

  • On every page load, the <html> element receives a data-theme attribute of either "light" or "dark".
  • Priority order for selecting the theme on load:
    1. localStorage["theme"] if set
    2. prefers-color-scheme media query
  • The nav contains a theme toggle button. Its icon is 🌙 when light mode is active (inviting switch to dark) and 🔅 when dark mode is active (inviting switch to light).
  • Clicking the toggle flips the theme, saves the new value to localStorage, and updates the button icon — without a page reload.
  • The HTML default attribute is data-theme="light" to minimise flash for light-mode users before JS runs.

Implementation Notes

  • ThemeController (Stimulus) is attached to the toggle <button> in the nav via data-controller="theme" and data-action="click->theme#toggle".
  • connect() reads localStorage["theme"], falls back to window.matchMedia("(prefers-color-scheme: dark)"), sets document.documentElement.setAttribute("data-theme", theme), and calls updateIcon.
  • toggle() reads the current data-theme, flips it, persists to localStorage, and calls updateIcon.
  • updateIcon() sets this.element.textContent to "🔅" (dark mode active) or "🌙" (light mode active).
  • CSS dark overrides use [data-theme="dark"] selectors in _variables.scss and rouge.scss.

Tests

  • spec/system/theme_spec.rb — default theme is light; toggle switches to dark and back; preference persists across navigation.

See Also

  • Styling and CSS — broader stylesheet system of which dark mode is a part; _variables.scss and rouge.scss provide the CSS for each theme.

Change Log

  • 2026-03-05: Spec written; system test added.