Appearance
Your First Page
Build a real screen — KPI cards, a chart, and a searchable data grid — from an empty file. Roughly 15 minutes.
Every snippet here is markup this build actually ships, lifted from html/_partials/ and html/pages/. Paste one into a page carrying adminvora.css and it is styled.
Step 1 — The document shell
html
<!doctype html>
<html lang="en" data-bs-theme="light" data-av-preset="aurora">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Orders · AdminVora</title>
<script>
(function () {
var d = document.documentElement, s;
try { s = JSON.parse(localStorage.getItem('adminvora.prefs') || '{}'); } catch (e) { s = {}; }
var mode = s.mode || 'system';
var dark = mode === 'dark' ||
(mode === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
d.setAttribute('data-bs-theme', dark ? 'dark' : 'light');
['preset','style','layout','nav-skin','density','radius','sidebar','topbar','width','contrast','motion','depth']
.forEach(function (k) { if (s[k]) d.setAttribute('data-av-' + k, s[k]); });
if (s.dir) d.setAttribute('dir', s.dir);
d.classList.add('av-booting');
requestAnimationFrame(function () {
requestAnimationFrame(function () { d.classList.remove('av-booting'); });
});
})();
</script>
<link rel="icon" href="/adminvora/img/favicon.svg" type="image/svg+xml">
<link rel="stylesheet" href="/adminvora/css/adminvora.min.css">
</head>
<body>
<a href="#main" class="av-skip-link">Skip to main content</a>
<div class="av-shell">
<!-- sidebar goes here (step 2) -->
<div class="av-main">
<!-- topbar goes here (step 3) -->
<main class="av-content" id="main" tabindex="-1">
<div class="container-fluid">
<!-- page content goes here (steps 4–6) -->
</div>
</main>
<footer class="av-footer">
<span>© 2026 Acme Inc.</span>
<span>v1.0.0</span>
</footer>
</div>
</div>
<button class="av-sidebar-backdrop" type="button" data-av-sidebar-backdrop
aria-label="Close navigation" hidden></button>
<script src="/adminvora/js/adminvora.js" defer></script>
</body>
</html>What each part does
| Element | Purpose |
|---|---|
data-av-* on <html> | Theme preference contract — read by CSS, written by the Customizer |
| Boot script | Applies stored preferences before first paint; prevents theme flash |
.av-skip-link | WCAG 2.4.1 bypass block; visually hidden until focused |
.av-shell | CSS Grid container defining the sidebar and main regions |
.av-content | The only element that scrolls. The document itself stays one viewport tall |
#main with tabindex="-1" | Makes the skip-link target programmatically focusable |
.av-sidebar-backdrop | The dismiss target behind the off-canvas sidebar below 992px |
One stylesheet, not two.
dist/css/adminvora.min.cssalready containstokens.css. The split pair undersrc/css/exists so you can regenerate tokens against a custom palette; a consumer links the single file.
Never defer or externalise the boot script. Both reintroduce exactly the flash of the wrong theme it prevents. It is the first script in
<head>and it is synchronous on purpose.
Step 2 — Sidebar
html
<aside class="av-sidebar" id="avSidebar">
<div class="av-sidebar__brand">
<a href="/" class="av-brand">
<img class="av-brand__mark" src="/adminvora/img/logo-mark.svg" alt="" width="32" height="32">
<span class="av-brand__text">Acme</span>
</a>
<button class="av-btn av-btn--ghost av-btn--icon av-sidebar-collapse" style="--av-btn-height: 30px"
type="button" data-av-sidebar-toggle
aria-label="Collapse sidebar" aria-expanded="true" aria-controls="avSidebar">
<svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24"><path d="M15 6l-6 6 6 6"/></svg>
</button>
</div>
<nav class="av-sidebar__nav" aria-label="Main">
<ul class="av-menu">
<li class="av-menu__group">
<details class="av-menu__disclosure" open>
<summary class="av-menu__title" id="avGroupShop">
<span class="av-menu__title-text">Shop</span>
<svg class="av-icon av-menu__caret" aria-hidden="true" viewBox="0 0 24 24"><path d="m6 9 6 6 6-6"/></svg>
</summary>
<ul class="av-menu__group-list" aria-labelledby="avGroupShop">
<li class="av-menu__item">
<a class="av-menu__link" href="/dashboard">
<svg class="av-icon av-menu__icon" aria-hidden="true" viewBox="0 0 24 24">
<rect x="3" y="3" width="7.5" height="7.5" rx="1.5"/>
<rect x="13.5" y="3" width="7.5" height="7.5" rx="1.5"/>
<rect x="3" y="13.5" width="7.5" height="7.5" rx="1.5"/>
<rect x="13.5" y="13.5" width="7.5" height="7.5" rx="1.5"/>
</svg>
<span class="av-menu__label">Dashboard</span>
</a>
</li>
<li class="av-menu__item av-menu__item--active">
<a class="av-menu__link" href="/orders" aria-current="page">
<svg class="av-icon av-menu__icon" aria-hidden="true" viewBox="0 0 24 24">
<path d="M6 7h12l-1.2 13H7.2L6 7z"/><path d="M9 10V7a3 3 0 0 1 6 0v3"/>
</svg>
<span class="av-menu__label">Orders</span>
</a>
</li>
</ul>
</details>
</li>
</ul>
</nav>
</aside>Sections are <details>/<summary>, not a JavaScript disclosure. A menu that needs a working bundle in order to open is the wrong trade in the one region that has to survive the bundle failing — the same reasoning that keeps the error pages off the app bundle entirely. Mark the group holding the current page open, and the rail arrives in the right state with no script at all.
The active row needs both halves: av-menu__item--active paints it, aria-current="page" announces it. Neither implies the other, and shipping one without the other is the most common accessibility defect in an admin sidebar.
Step 3 — Topbar
html
<header class="av-topbar">
<div class="av-topbar__start">
<button class="av-btn av-btn--ghost av-btn--icon av-topbar__menu-btn" type="button"
data-av-sidebar-toggle aria-label="Open navigation"
aria-controls="avSidebar" aria-expanded="false">
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M4 6h16M4 12h16M4 18h16"/></svg>
</button>
<button class="av-search-trigger" type="button" data-av-palette-open
aria-label="Search pages and commands">
<svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24">
<circle cx="10.5" cy="10.5" r="6.5"/><path d="M15.5 15.5L21 21"/>
</svg>
<span class="av-search-trigger__text">Search…</span>
<span class="av-search-trigger__kbd"><kbd class="av-kbd">Ctrl</kbd><kbd class="av-kbd">K</kbd></span>
</button>
</div>
<div class="av-topbar__end">
<button class="av-btn av-btn--ghost av-btn--icon" type="button"
data-av-theme-toggle data-av-tooltip="Toggle colour mode" aria-label="Toggle colour mode">
<svg class="av-icon av-mode-icon--light" aria-hidden="true" viewBox="0 0 24 24">
<circle cx="12" cy="12" r="4"/>
<path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/>
</svg>
<svg class="av-icon av-mode-icon--dark" aria-hidden="true" viewBox="0 0 24 24">
<path d="M21 13A8.5 8.5 0 1 1 11 3a7 7 0 0 0 10 10z"/>
</svg>
</button>
<div class="av-dropdown">
<button class="av-topbar__profile" type="button" data-av-dropdown-toggle
aria-expanded="false" aria-haspopup="menu" aria-label="Account menu">
<span class="av-avatar" aria-hidden="true">JC</span>
<span class="av-topbar__profile-meta" aria-hidden="true">
<span class="av-topbar__profile-name">Jane Cooper</span><br>
<span class="av-topbar__profile-role">Administrator</span>
</span>
</button>
<ul class="av-dropdown__menu" role="menu">
<li class="av-dropdown__label" role="presentation">Signed in as jane@…</li>
<li role="none"><a class="av-dropdown__item" href="/settings" role="menuitem">Settings</a></li>
<li class="av-dropdown__divider" role="separator"></li>
<li role="none">
<a class="av-dropdown__item av-dropdown__item--danger" href="/logout" role="menuitem">Sign out</a>
</li>
</ul>
</div>
</div>
</header>Dropdowns are data-av-dropdown-toggle on a .av-dropdown wrapper. There is no Bootstrap in this build and no data-bs-toggle; initDropdowns() delegates from document, so markup that arrives later already works.
The divider is a <li class="av-dropdown__divider" role="separator">, not an <hr>. A menu is a list, and an <hr> between list items is not.
A control that acts on the open panel rather than dismissing it opts out of close-on-click with
data-av-dropdown-keep. Without it, "mark all read" closes the panel before its own result can be seen.
Step 4 — Page header and KPI cards
html
<div class="av-page-header">
<div>
<ol class="av-breadcrumb" aria-label="Breadcrumb">
<li><a href="/">Home</a></li>
<li aria-current="page">Orders</li>
</ol>
<h1 class="av-page-header__title">Orders</h1>
<p class="av-page-header__subtitle">1,284 orders this month · +12.4% vs last month</p>
</div>
<div class="av-page-header__actions">
<button class="av-btn av-btn--outline" type="button">
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24">
<path d="M12 3v12M7 11l5 5 5-5M4 21h16"/>
</svg>
Export
</button>
<a class="av-btn av-btn--primary" href="/orders/new">
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14"/></svg>
New order
</a>
</div>
</div>
<div class="av-grid av-grid--stats" style="margin-block-end: var(--av-space-4)">
<div class="av-stat-card">
<div class="av-stat-card__head">
<span class="av-stat-card__label">Revenue</span>
<span class="av-stat-card__icon">
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24">
<path d="M17 7H9.5a3.5 3.5 0 0 0 0 7H14a3.5 3.5 0 0 1 0 7H6M4 10h8M4 14h8"/>
</svg>
</span>
</div>
<div class="av-stat-card__value" data-av-money="4825000">€48,250.00</div>
<div class="av-stat-card__foot">
<span class="av-trend av-trend--up">
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24">
<path d="M3 17l6-6 4 4 8-8"/><path d="M15 7h6v6"/>
</svg>
12.4%
</span>
<span>vs last month</span>
</div>
</div>
<!-- repeat for Orders, Customers, Refunds -->
</div>av-grid av-grid--stats is the row. There is no row/col-* system here — the utility layer is deliberately small, and the stat row is a named grid rather than four column classes you have to keep in step. See Layout Anatomy.
Money is written as integer minor units. data-av-money="4825000" with the formatted string as the no-JS fallback in the element's own text; initMoney() reformats it at runtime through Intl.NumberFormat. Never format currency by hand — the thousands separator, the symbol position and the decimal mark all change with the locale.
The top accent bar on a stat card is driven off the icon's role modifier with :has(), so the bar and the icon cannot disagree.
Step 5 — A chart
html
<div class="av-card" style="margin-block-end: var(--av-space-4)">
<div class="av-card__header">
<div>
<h2 class="av-card__title">Revenue over time</h2>
<p class="av-card__subtitle">This period against the one before it</p>
</div>
<span class="av-badge av-badge--success-soft">+12.4%</span>
</div>
<div class="av-card__body">
<div data-av-chart
style="--av-chart-height: 320px"
data-av-chart-options='{
"type": "area",
"series": [{ "name": "Revenue", "data": [31, 40, 28, 51, 42, 62, 74] }],
"categories": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
"stroke": { "curve": "smooth", "width": 2 }
}'></div>
</div>
</div>Charts are ApexCharts, vendored locally and lazy-loaded when the element scrolls into view. Colours come from the resolved tokens, so a preset or mode change re-themes the chart in place.
Two things will bite you:
labelsmust be absent, notundefined. Apex reads.lengthoff it while laying out a bar and throws. The same applies toformatter: an explicitundefinedreplaces Apex's default rather than falling back to it, and radar calls the value straight out of aforEachwith no guard.- More than two series takes the categorical ramp. The brand pair is two colours and Apex cycles it, so a third series silently repeats the first.
data-av-chart-srcanddata-av-chart-seriesdo not exist in this build. Earlier versions of this page showed both. The runtime readsdata-av-chart-optionsanddata-av-chart-fallback, and nothing else — fetch the data yourself and write the options attribute, or render it server-side. Full options: Charts.
Step 6 — A data grid
Start with real server-rendered rows so the page works before JavaScript arrives:
html
<div class="av-card">
<div class="av-table-wrap">
<table class="av-table">
<caption class="av-visually-hidden">Orders, filterable and sortable</caption>
<thead>
<tr>
<th scope="col" class="av-table__check">
<input type="checkbox" data-av-grid-select-all aria-label="Select all visible orders">
</th>
<th scope="col">Order</th>
<th scope="col">Customer</th>
<th scope="col">Status</th>
<th scope="col" class="av-table__num">Total</th>
<th scope="col">Date</th>
<th scope="col" class="av-table__actions-cell">
<span class="av-visually-hidden">Actions</span>
</th>
</tr>
</thead>
<tbody>
<tr data-av-status="paid">
<td class="av-table__check">
<input type="checkbox" data-av-grid-row-check aria-label="Select order #1042">
</td>
<th scope="row" data-av-key="order" data-av-value="1042">
<a href="/orders/1042">#1042</a>
</th>
<td data-av-key="customer" data-av-value="Sarah Kim">
<span class="av-table__person">
<span class="av-avatar av-avatar--sm" aria-hidden="true">SK</span>
<span>
<span class="av-table__link">Sarah Kim</span><br>
<span class="av-table__person-meta">sarah@northwind.io</span>
</span>
</span>
</td>
<td data-av-key="status" data-av-value="Paid">
<span class="av-badge av-badge--success-soft">Paid</span>
</td>
<td class="av-table__num" data-av-key="total" data-av-value="1240">€1,240.00</td>
<td data-av-key="date" data-av-value="2026-08-12">
<time datetime="2026-08-12">12 Aug 2026</time>
</td>
<td class="av-table__actions-cell">
<div class="av-dropdown">
<button class="av-btn av-btn--ghost av-btn--icon" style="--av-btn-height: 30px"
type="button" data-av-dropdown-toggle aria-expanded="false"
aria-haspopup="menu" aria-label="Actions for order #1042">
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24">
<circle cx="12" cy="5" r="1"/><circle cx="12" cy="12" r="1"/><circle cx="12" cy="19" r="1"/>
</svg>
</button>
<ul class="av-dropdown__menu" role="menu">
<li role="none"><a class="av-dropdown__item" href="/orders/1042" role="menuitem">View order</a></li>
<li class="av-dropdown__divider" role="separator"></li>
<li role="none">
<button class="av-dropdown__item av-dropdown__item--danger" type="button" role="menuitem">
Delete
</button>
</li>
</ul>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>data-av-value is what the grid sorts on, not the cell's text. €1,240.00 sorts as a string between €1,199 and €13; 1240 sorts as a number. Dates are the same problem in a different costume — the visible 12 Aug 2026 and the sortable 2026-08-12 are different strings on purpose.
.av-table-wrap is the scroll container, and it needs min-inline-size: 0 on any grid or flex ancestor. A grid item's automatic minimum size is its content's min-content width, so a wide table grows its track past the viewport instead of scrolling inside its own wrapper.
A dropdown inside a scroll container cannot be rescued with
z-index—overflowdoes not consult it.initDropdownspromotes the menu to a popover on first open, which puts it in the top layer, above every stacking context and outside every scroll container, with no change to your markup.
Step 7 — Adding your own behaviour
The runtime exposes theme, toast, confirm, loading, a11y, utils, on, emit, init, destroy and version on window.AdminVora. Bind your own behaviour to a data- hook and use the event bus to talk to the rest of the page:
js
// app.js
document.addEventListener('change', async (event) => {
const el = event.target.closest('[data-av-order-status] select');
if (!el) return;
const root = el.closest('[data-av-order-status]');
const { orderStatusUrl: url, orderStatusId: id, orderStatusCurrent: current } = root.dataset;
root.classList.add('is-busy');
try {
const res = await fetch(url, {
method: 'PATCH',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]').content
},
body: JSON.stringify({ status: el.value })
});
if (!res.ok) throw new Error(res.statusText);
AdminVora.toast.success('Status updated');
AdminVora.emit('order:status-changed', { id, status: el.value });
} catch {
AdminVora.toast.error('Could not update status');
el.value = current;
} finally {
root.classList.remove('is-busy');
}
});html
<div data-av-order-status
data-av-order-status-url="/api/orders/1042/status"
data-av-order-status-id="1042"
data-av-order-status-current="paid">
<select class="av-select">
<option value="pending">Pending</option>
<option value="paid" selected>Paid</option>
<option value="shipped">Shipped</option>
</select>
</div>Delegating from document is not a shortcut here — it is the pattern the built-in modules use for anything that must survive markup arriving later, and it needs no re-scan at all.
After a client-side navigation
js
// Turbo, htmx, or your router's after-render hook
AdminVora.destroy(oldRoot); // dispose vendor instances — a chart holds a resize observer
AdminVora.init(newRoot); // bind modules in the subtree that changeddestroy() releases the data-av-init claims so markup that is moved rather than destroyed can be bound again on arrival. It does not detach listeners; those go with the elements.
There is no way to register your own module with the runtime. Bind your own behaviour after
av:contentfires, and use thedata-av-*hooks,init(root)anddestroy(root)for everything the runtime already provides.
Checklist before you call it done
- [ ] Page renders and is usable with JS disabled
- [ ] Every interactive element is reachable with Tab and shows a focus ring
- [ ] Toggle dark mode — check contrast on badges, muted text, and chart gridlines
- [ ] Toggle RTL (
dir="rtl") — check icon direction and table alignment - [ ] Resize to 320 px — no horizontal scroll on either the document or
.av-content - [ ] Every image has
alt(emptyalt=""for decorative), every icon hasaria-hidden="true" - [ ] The active menu row carries
av-menu__item--activeandaria-current="page"
Read next: CLI & Scripts.