docs: document Lumi UI and theme customization

README.md

@@ -53,7 +53,14 @@ Users have an internal UUID and username. Link Twitch accounts in **Profile** an
 
 ## Theming
 
-Use **Admin → Theming** to adjust light and dark mode colors. The UI uses your OS theme preference.
+Use **Admin → Theming** to select one of six read-only Lumi themes. Duplicate a
+built-in or custom theme to edit colors, surfaces, controls, status colors,
+focus states, radius, shadows, and spacing with a live light/dark preview.
+Custom themes can be applied, renamed, duplicated, and deleted. Invalid or
+incomplete values fall back safely to the selected built-in base theme.
+
+Developer and modding conventions are documented in
+[`docs/lumi-ui.md`](docs/lumi-ui.md).
 
 ## Notes
 

codex-guidelines

@@ -160,7 +160,12 @@ Important settings keys (core)
 
 Known file locations
 - Layout partials: src/web/views/partials/layout-top.ejs, layout-bottom.ejs
-- Global CSS: src/web/public/styles.css
+- Lumi UI tokens: src/web/public/lumi-tokens.css
+- Lumi UI layout: src/web/public/lumi-layout.css
+- Lumi UI components: src/web/public/lumi-components.css
+- Legacy/feature CSS: src/web/public/styles.css
+- Theme service: src/services/themes.js
+- UI and theme conventions: docs/lumi-ui.md
 - Global JS: src/web/public/app.js
  - Asset versioning: res.locals.assetVersion (cache-bust for styles/app)
 - Nav icons: src/web/public/icons/nav (defaults), data/nav-icons (admin uploads)

docs/lumi-ui.md

@@ -0,0 +1,62 @@
+# Lumi UI and theme system
+
+Lumi UI is the project-native design layer used by every page rendered through the
+shared EJS layout. It keeps route behavior and page-specific JavaScript separate
+from visual tokens and reusable components.
+
+## Files
+
+- `src/web/public/lumi-tokens.css`: semantic colors, spacing, radii, shadows,
+  typography, compatibility aliases, and reduced-motion behavior.
+- `src/web/public/lumi-layout.css`: application shell, sidebar, content
+  containers, responsive grids, stacks, clusters, and mobile navigation.
+- `src/web/public/lumi-components.css`: buttons, forms, cards, tables, lists,
+  badges, alerts, tabs, modals, empty/loading/error states, and tooltips.
+- `src/web/public/styles.css`: legacy and feature-specific styles that still use
+  the shared tokens. New general-purpose styling belongs in the Lumi UI files.
+- `src/web/views/partials/page-header.ejs`: standard page title and description.
+- `src/web/views/partials/theme-vars.ejs`: safe active-theme variables for shell
+  and standalone pages.
+- `src/services/themes.js`: built-in themes, custom theme CRUD, validation,
+  migration, fallback handling, and active-theme selection.
+
+Use `lumi-stack`, `lumi-cluster`, `lumi-split`, `lumi-grid`, `page-header`,
+`button-group`, `card`, `panel`, `table-wrap`, `empty-state`, `loading-state`,
+and `status-indicator` before adding one-off layout rules. Preserve existing IDs,
+field names, data attributes, and JavaScript hooks when restyling a page.
+
+## Themes
+
+Lumi ships with six read-only themes: Lumi Default, Lumi Dark, Lumi Light, High
+Contrast, Midnight, and Soft Aurora. Admins select them from **Admin > Theming**.
+Built-in themes cannot be renamed, edited, or deleted.
+
+Open a theme's **More actions** section and duplicate it to create an editable
+custom theme. Custom themes can be previewed in light and dark mode, saved,
+applied globally, renamed, duplicated, or deleted. Deleting the active custom
+theme falls back to Lumi Default.
+
+The compact editor exposes common colors first. Advanced controls cover
+background glows, raised surfaces, links, buttons, inputs, focus rings, radius,
+shadow strength, and spacing scale. The server accepts only six-digit hex colors,
+bounded metric values, and readable text/button/input contrast.
+
+Missing or invalid stored values are replaced from the custom theme's built-in
+base. Existing installations with modified legacy `theme_light_*`,
+`theme_dark_*`, or `theme_role_*` settings are migrated once into a custom
+**Migrated Theme** and selected automatically. The legacy `/admin/theming` POST
+route remains supported and writes into an editable custom theme.
+
+Run `npm run verify:webui` to compile every EJS view and exercise built-in theme
+validation plus custom duplicate, apply, edit validation, rename, and delete.
+
+## Visual references
+
+- [Home, desktop](screenshots/lumi-home-desktop.png)
+- [Home, 360px mobile](screenshots/lumi-home-mobile.png)
+- [Custom theme editor, desktop](screenshots/lumi-theme-editor-desktop.png)
+- [Custom theme editor, 360px mobile](screenshots/lumi-theme-editor-mobile.png)
+
+The broad sidebar and content structure remains in place. Theme controls moved
+from one long raw color form into the Theme Studio library and grouped custom
+editor; no navigation destination or non-theme control was relocated.