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](styling.md) — 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.