87 lines
4.5 KiB
Markdown
87 lines
4.5 KiB
Markdown
# 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.
|