# 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.