@webority/theme 0.7.7 → 0.7.8

package/README.md

@@ -37,6 +37,56 @@ colour — intentional shared semantics (see `_variables.scss`).
 `dist/webority-theme.css` is a precompiled default-brand **portal** build (no
 marketing partial). Prefer the SCSS chain above for brand-exact output.
 
+## Dark mode
+
+The theme ships with two built-in dark-mode support patterns:
+
+### Manual toggle (production)
+
+Set `data-theme="dark"` and `data-bs-theme="dark"` on `<html>` to flip both WUI and Bootstrap
+native components together. The dark token remap maps all `--color-*` aliases onto dark hexes,
+and Bootstrap's utility classes (`.text-body`, `.bg-secondary`) and components respond via
+the `[data-bs-theme="dark"]` selector that Bootstrap provides. **Pair the attributes**—setting
+one without the other leaves part of the system on the wrong palette.
+
+Persist the choice in localStorage and restore it on next visit:
+
+```js
+// On mount:
+const theme = localStorage.getItem('theme') || 'light';
+document.documentElement.setAttribute('data-theme', theme);
+document.documentElement.setAttribute('data-bs-theme', theme);
+
+// On toggle:
+const newTheme = theme === 'light' ? 'dark' : 'light';
+document.documentElement.setAttribute('data-theme', newTheme);
+document.documentElement.setAttribute('data-bs-theme', newTheme);
+localStorage.setItem('theme', newTheme);
+```
+
+### Automatic detection (opt-in)
+
+Set `data-theme="auto"` on `<html>` to detect the system preference via `@media (prefers-color-scheme: dark)`
+and apply the dark remap automatically. Works with user-level system settings (OS dark mode);
+**does not persist a user's manual toggle** (every reload reads the OS setting). Use for opt-in
+portals where the portal doesn't control color preference; omit for apps that give users a
+theme picker.
+
+### Implementation
+
+Both patterns use the same 60-line dark-token SCSS mixin (defined in `_wui-aliases.scss`),
+so the compiled dark CSS is byte-identical whether toggled manually or via system preference.
+
+Token remap includes:
+- **Surfaces & text** — `--color-bg`, `--color-border`, `--color-text*`
+- **Bootstrap RGB triplets** — `--bs-body-bg-rgb`, `--bs-body-color-rgb`, etc., so `.bg-body` / `.text-body` utilities flip
+- **Brand & status colors** — primary, success, danger, warning, info (mapped to readable values on dark surfaces)
+- **Scrim** — overlay dimming adjusted for dark backgrounds
+- **Component shadows** — slider thumbs, badge accents, etc. re-mapped for visibility
+
+Marketing sites ship light-only (the `scss/_marketing.scss` partial is opt-in on portals
+and omitted on marketing); dark mode is a **portal feature**, not a marketing requirement.
+
 ## Library vs product ownership
 
 Three layers. Do not collapse product art direction into the shared package.