Rolfsvaag_Datateknikk/Lumi
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7ab2b61110
Lumi/docs/lumi-ui.md
Franz Rolfsvaag cec485675c docs: document Lumi UI and theme customization
2026-06-15 23:58:30 +02:00

3.2 KiB
Raw Blame History

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

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.