Skip to content

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:

  1. reads the saved theme preferences,
  2. scans the document for data-av-* hooks and binds each element once — an element records what claimed it in data-av-init, so a second scan never double-binds,
  3. 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,
  4. emits av:boot, av:content and av: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 ​

MechanismUsed forExample
is-* classTransient UI state written by JSis-open, is-invalid, is-mobile-open
has-* classStructural variant set by the authorhas-icon
data-av-stateEnumerated state with more than two valuesidle, loading, empty
ARIA attributeAnything a screen reader must knowaria-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.

ConcernServer-rendered (Blade, Django, Rails)Client-rendered (React, Vue)
InitialisationAutomatic at page loadAdminVora.init() after each navigation
CleanupThe page unloadsAdminVora.destroy(el) before removing a subtree
DataRendered into the markupRendered into the markup by your components
ThemeBoot scriptBoot script

Budgets and measured sizes: Performance.

Read next: CSS Architecture.

Documentation for @creativeigniter/adminvora