Appearance
Architecture Overview
How AdminVora is put together, and where the boundaries are.
The layers
┌──────────────────────────────────────────────────────────────────┐
│ YOUR APPLICATION │
│ Blade / Twig / Django templates / React / Vue / plain HTML │
└───────────────────────────────┬──────────────────────────────────┘
│ markup with .av-* classes and data-av-* hooks
┌───────────────────────────────▼──────────────────────────────────┐
│ STYLESHEET tokens.css + adminvora.css │
│ @layer tokens, reset, base, components, plugins, styles, utilities │
├──────────────────────────────────────────────────────────────────┤
│ RUNTIME src/js/adminvora.js — one file, no build step │
│ scans data-av-* hooks, lazy-loads vendors, AdminVora.* API │
├──────────────────────────────────────────────────────────────────┤
│ VENDORED ASSETS local, checksummed, never fetched from a CDN │
│ ApexCharts · Tabulator · Quill · CodeMirror · Leaflet · … │
└──────────────────────────────────────────────────────────────────┘The demo pages and starter kits are built from the same markup. Nothing in the stylesheet or the runtime knows which page it is on.
Values: tokens
tools/build-tokens.mjs holds the colour ramps, the scales and every preset, and writes src/css/tokens.css: custom properties in three tiers (primitive → semantic → component), all in @layer tokens. Nothing downstream hard-codes a colour, radius, shadow or duration — npm run lint:css fails if it does. See Design Tokens.
Appearance: the stylesheet
src/scss/adminvora.scss is a flat list of @use lines, one partial per component, compiled by Sass into adminvora.css. Every rule sits in a cascade layer:
@layer tokens, reset, base, components, plugins, styles, utilities;Layout partials live in components; plugins restyles the vendored libraries from tokens; utilities is last. Because every rule is layered, an unlayered rule of yours wins without needing specificity. There is no RTL stylesheet: logical properties make one stylesheet serve both directions. See CSS Architecture.
Theming: attributes on <html>
Every theme choice — mode, preset, layout, density, radius, contrast, motion, direction — is an attribute on <html> that selects custom properties. An inline script in <head> restores the saved choices before first paint, so there is no flash of the wrong theme. See Theme Engine.
Behaviour: the runtime
src/js/adminvora.js is one file loaded with <script defer>. At boot it:
- reads the saved theme preferences,
- scans the document for
data-av-*hooks and binds each element once — an element records what claimed it indata-av-init, so a second scan never double-binds, - lazy-loads a vendor (ApexCharts, Tabulator, Quill…) only for a page that has an element needing it, and charts only as they scroll into view,
- emits
av:boot,av:contentandav:ready.
It does not watch for content added later. After you insert markup — a client-side navigation, an htmx swap — call AdminVora.init(root); before removing markup that holds vendor widgets, call AdminVora.destroy(root). See JavaScript Architecture.
The demo pages also load src/demo/demo.js, the scripted behaviour of the demo screens (mail, chat, checkout…). It is not part of dist/ and reaches the runtime only through its public API.
State conventions
| Mechanism | Used for | Example |
|---|---|---|
is-* class | Transient UI state written by JS | is-open, is-invalid, is-mobile-open |
has-* class | Structural variant set by the author | has-icon |
data-av-state | Enumerated state with more than two values | idle, loading, empty |
| ARIA attribute | Anything a screen reader must know | aria-expanded, aria-busy, aria-invalid |
When JS sets an is-* class it sets the matching ARIA attribute too.
Server-rendered first
AdminVora is designed for server-rendered admin panels. Markup carries the data; the runtime enhances it. A table is a real <table> before the grid sorts it, a field is a real <textarea> before the editor mounts, and a chart's <noscript> holds its numbers — so every page works, in a reduced form, with JavaScript off.
| Concern | Server-rendered (Blade, Django, Rails) | Client-rendered (React, Vue) |
|---|---|---|
| Initialisation | Automatic at page load | AdminVora.init() after each navigation |
| Cleanup | The page unloads | AdminVora.destroy(el) before removing a subtree |
| Data | Rendered into the markup | Rendered into the markup by your components |
| Theme | Boot script | Boot script |
Budgets and measured sizes: Performance.
Read next: CSS Architecture.