diff --git a/README.md b/README.md index d6d7067..c3f3b98 100644 --- a/README.md +++ b/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 diff --git a/codex-guidelines b/codex-guidelines index db7b290..eb0f347 100644 --- a/codex-guidelines +++ b/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) diff --git a/docs/lumi-ui.md b/docs/lumi-ui.md new file mode 100644 index 0000000..39685f3 --- /dev/null +++ b/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. diff --git a/docs/screenshots/lumi-home-desktop.png b/docs/screenshots/lumi-home-desktop.png new file mode 100644 index 0000000..723538e Binary files /dev/null and b/docs/screenshots/lumi-home-desktop.png differ diff --git a/docs/screenshots/lumi-home-mobile.png b/docs/screenshots/lumi-home-mobile.png new file mode 100644 index 0000000..79d5403 Binary files /dev/null and b/docs/screenshots/lumi-home-mobile.png differ diff --git a/docs/screenshots/lumi-theme-editor-desktop.png b/docs/screenshots/lumi-theme-editor-desktop.png new file mode 100644 index 0000000..4b151ff Binary files /dev/null and b/docs/screenshots/lumi-theme-editor-desktop.png differ diff --git a/docs/screenshots/lumi-theme-editor-mobile.png b/docs/screenshots/lumi-theme-editor-mobile.png new file mode 100644 index 0000000..096559b Binary files /dev/null and b/docs/screenshots/lumi-theme-editor-mobile.png differ