diff --git a/docs/DARK_MODE.md b/docs/DARK_MODE.md new file mode 100644 index 0000000..04ed5b3 --- /dev/null +++ b/docs/DARK_MODE.md @@ -0,0 +1,66 @@ +# Dark Mode + +Every page in the Heartbeat web UI supports light mode, dark mode, and automatic (follows the OS/browser setting). Each user picks their preference independently; it is stored in the browser and takes effect immediately without a page reload. + +--- + +## Choosing a theme + +Open your profile page (`/profile`) and scroll to the **Appearance** section. Click one of the three buttons: + +| Button | Behaviour | +|--------|-----------| +| **Auto** | Follows the OS or browser dark-mode preference. Updates live if the system setting changes. | +| **Light** | Always light, regardless of system setting. | +| **Dark** | Always dark, regardless of system setting. | + +The preference is stored in `localStorage` under the key `hbd_theme` and applies to the current browser only. Clearing browser storage resets it to **Auto**. + +--- + +## Implementation notes + +### No flash of unstyled content + +A small synchronous `