# 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, stateful action
  buttons, and tooltips.
- `src/web/public/lumi-state-button.js` and
  `src/web/views/partials/state-button.ejs`: reusable multi-state button
  behavior for submit/loading/success actions.
- `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. Typography controls use constrained font
presets plus bounded base-size, heading-scale, and control-density ranges. The
server accepts only six-digit hex colors, supported font presets, bounded metric
values, and readable text/button/input contrast.

The live preview updates colors, role colors, metrics, and typography before
save. The editor also shows contrast warnings for the current preview mode,
offers a reset-to-base action for inherited custom themes, and provides an
optional desktop pop-out preview window that stays synchronized with the editor.

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, typography validation,
stateful theme actions, localhost login rendering, rename, and delete.

## Localhost Login

Development builds opened from `localhost`, `127.0.0.1`, or `::1` show a
**Localhost Login** option. It defaults to username `admin` and password `admin`
unless those settings have already been changed. The option is not inserted into
the login list, cannot be used, and does not satisfy setup requirements for
non-localhost requests.

Admins can change the localhost username and password from **Admin > Settings**
when the settings page itself is accessed through localhost. Leaving the
password field blank keeps the existing password.

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