Lumora Product Documentation

Back to Dashboard Last Updated: 2026-05-06

Build, Extend, and Operate Lumora with Confidence

This document is the implementation-level reference for engineers joining the Lumora admin template. It explains not only what exists, but why each pattern exists, how to extend safely, and how to keep consistency across pages, themes, and components.

HTML5 + Bootstrap 5.3.3 + Vanilla JS Token-driven CSS system BEM-ish component architecture A11y and responsive-first

Quick Start

Ready
  1. Open project root in VS Code: d:/RnD/dash/lumora.
  2. Use index.html or any file in pages/ as start page.
  3. Ensure internet connectivity for CDN-based assets (Bootstrap, Font Awesome, Google Fonts, chart libs).
  4. Load CSS via assets/css/app.css only. Avoid ad-hoc imports in page files.
  5. Load behavior via assets/js/app.js plus page scripts under assets/js/pages/.
For predictable rendering across pages, keep CSS import order unchanged: tokens -> reset -> base -> utilities -> layout -> components -> themes.

Solution Architecture

Stable

Lumora follows a layered frontend architecture where design tokens are the source of truth, layout primitives control shell behavior, and feature components stay isolated. This minimizes style drift and improves maintainability when pages scale. 

Layer 1: Design Tokens (assets/css/tokens.css)
Layer 2: Global Foundations (reset.css, base.css, utilities.css)
Layer 3: Shell Layout (layout.css)
Layer 4: Reusable Components (assets/css/components/*.css)
Layer 5: Page Overrides (assets/css/pages/*.css)
Layer 6: Theme Overrides (assets/css/themes/dark.css)

JavaScript follows the same principle: common boot modules first, then page-level scripts.

Folder Structure (Operational View)

Active 
lumora/
|- index.html                # default dashboard
|- landing.html              # marketing/front landing
|- assets/
|  |- css/
|  |  |- tokens.css
|  |  |- reset.css
|  |  |- base.css
|  |  |- utilities.css
|  |  |- layout.css
|  |  |- app.css
|  |  |- components/         # reusable component-level css
|  |  \- themes/
|  \- js/
|     |- app.js
|     |- theme.js
|     |- sidebar.js
|     |- topbar.js
|     |- auth.js
|     |- charts/
|     \- pages/
|- pages/                    # all functional pages
|- partials/                 # reusable html fragments
\- docs/
   \- index.html             # this file

Design Tokens

Canonical
Use tokens only. Avoid hardcoded values unless there is a strict technical reason.

--brand

#5B5BF7

--brand-soft

#EAEAFE

--success

#22C55E

--warn

#F59E0B

--danger

#EF4444

--info

#0EA5E9

--bg

#F6F7FB

--surface

#FFFFFF

--surface-2

#F1F3F9

--border

#E6E8EE

--text

#0F172A

--text-muted

#64748B

Category Token Set Guidance
Typography --font-sans / --font-num / --font-mono Josefin Sans for UI, Inter for numerics, JetBrains Mono for code-like values.
Spacing --sp-1 ... --sp-10 4px baseline. Prefer spacing tokens over ad-hoc margin/padding values.
Radius --r-xs ... --r-pill Use consistent corner hierarchy: controls small, cards medium/large.
Shadow --shadow-1 / 2 / pop Use sparingly. Emphasize hierarchy, not decoration.
Motion --t-fast / --t-base / --ease Interactions should feel quick, consistent, and unobtrusive.

Typography System

Role Spec Usage
H1 28-32px / 700 / -0.01em Page headline or hero title only.
H2 22-24px / 600 Primary section title.
H3 18-20px / 600 Card title, major subsection heading.
Body 14.5px / 400 / 1.6 General text and labels across pages.
Small 12px / 500 / uppercase / 0.06em Status labels, chips, table metadata.
Numeric Inter + tabular figures KPI values, percentages, counts, currency and chart labels.

Theming Strategy

Theme is controlled through data-theme on the root HTML element. 

<html lang="en" data-theme="light"> ... </html>

// theme.js approach
const savedTheme = localStorage.getItem("lumora-theme") || "light";
document.documentElement.setAttribute("data-theme", savedTheme);

Best practices:

  • Never create component-level dark overrides if token-level override already solves it.
  • Keep dark mode deltas centralized in assets/css/themes/dark.css.
  • Do not hardcode light color values in component files.

Responsive Contract

Range Breakpoint Shell Behavior
xs <576px Sidebar becomes off-canvas drawer. Content is single-column.
sm >=576px Basic two-column widget opportunities.
md >=768px Sidebar rail mode supported (collapsed navigation).
lg >=992px Full sidebar (260px) is default desktop behavior.
xl >=1200px Dense dashboard grids (3-4 columns) become primary pattern.
xxl >=1400px Content max width around 1440 with stable gutters.

CSS Architecture

CSS follows BEM-ish naming and explicit state classes.

Pattern Example Purpose
Block .stat-card Standalone reusable component.
Element .stat-card__value Scoped child inside a block.
Modifier .stat-card--success Visual/behavioral variant.
State .is-active .has-error Runtime state applied by JS or backend.
Utility .u-num Single-purpose helper.
Do not style JavaScript hooks. If hook classes are needed, prefix with js-.

JavaScript Architecture

Module Responsibility Notes
app.js Boot orchestration Initializes shared behaviors when DOM is ready.
theme.js Light/Dark preference Persists to localStorage and updates root attribute.
sidebar.js Sidebar collapse/off-canvas Handles desktop rail + mobile drawer transitions.
topbar.js Topbar interactions Search, notifications, quick actions behavior.
auth.js Auth UX helpers OTP input, password strength and auth affordances.
js/pages/* Page-specific logic Keep feature scripts isolated per page domain.
Rule: shared behaviors must remain framework-agnostic and page-neutral. Put page assumptions only in page scripts.

Component Library Inventory

Growing
Component CSS File Scope Status
buttons.css Button families, icons, segmented groups complete
card.css Card surfaces, stat cards complete
table.css Data tables, status chips, empty states complete
form.css Fields, controls, validation, OTP, strength complete
avatar-badge.css Avatars, chips, badges, menu accents complete
modal.css / tabs.css / progress.css Core interactive UI patterns complete
alert-toast.css / chart.css / timeline.css Feedback and analytical visuals complete
kanban.css / chat.css / email.css App-level interaction layouts complete
calendar.css / file-manager.css / todo-list.css Planning and productivity modules complete
traffic-source.css / tickets.css / social-card.css Dashboard widgets and ops views complete
settings-drawer.css / pricing-table.css Configuration + monetization UI complete
rating.css / stepper.css / skin-switcher.css / breadcrumb.css Flow controls + global page UX complete
All current component files are now import-wired through assets/css/app.css.

Partials and Composition Model

Partials reduce page duplication and enforce structural consistency.

partials/head.htmlMeta + font + CSS includes partials/sidebar.htmlPrimary app navigation partials/topbar.htmlGlobal top actions and profile partials/footer.htmlFooter and meta text partials/settings-drawer.htmlTheme and skin controls partials/widgets/*Reusable dashboard widget markup

When introducing a new widget, add its HTML partial and then add matching CSS module in assets/css/components/.

Icon Policy (Critical)

Lumora uses Font Awesome Free 6.7.2 only. Pro-only icons will render blank and silently break UI quality.
  • Allowed: fa-solid, fa-regular, brands available in Free package.
  • Forbidden: any Pro-only classes (example previously seen: fa-shield-check).
  • Validation: test icon-heavy pages after icon changes to ensure no missing glyph boxes.

Quality Gate Checklist

Gate Target Verification Method
HTML validity No structural errors W3C validation on representative pages.
Responsive behavior No horizontal scrolling at 360/768/1024/1440 Manual browser resize + device emulation.
Accessibility Keyboard reachable controls + visible focus Tab-only navigation smoke run.
Contrast AA compliance in light and dark theme Contrast checking across high-traffic screens.
Performance Lean initial render Audit blocking resources and component payload.
Consistency No hardcoded random styles Review token and component usage before merge.

Troubleshooting Reference

Symptom Likely Cause Fix
Component styles missing Module not imported in app.css Add ordered import in assets/css/app.css.
Icon not visible Pro-only Font Awesome icon used Replace with Free equivalent icon.
Dark mode broken in one component Hardcoded light colors in component Replace with semantic tokens.
Sidebar overlaps content on mobile Missing mobile off-canvas class/state handling Verify sidebar.js and layout media rules.
Layout spacing inconsistent Ad-hoc spacing values used Use spacing scale tokens --sp-*.

Roadmap Status (From PLAN.md)

In Execution
Milestone Scope Status
M0 Foundation, shell, token system done
M1 Authentication pages done
M2 Dashboards (multiple domains) done
M3 Users and access pages done
M4 E-commerce module done
M5 Apps (chat/email/calendar/kanban/file manager) done
M6 UI Kit pages and documentation support in progress
M7+ QA hardening and future polish planned