Appearance
Theme Engine
Everything about theming resolves to one idea: attributes on <html> select token values. There is no theme JavaScript in the render path.
The attribute contract
html
<html lang="en"
dir="ltr"
data-bs-theme="dark"
data-av-preset="aurora"
data-av-layout="vertical"
data-av-density="comfortable"
data-av-radius="rounded"
data-av-sidebar="expanded"
data-av-topbar="sticky"
data-av-width="fluid"
data-av-contrast="normal"
data-av-motion="full">| Attribute | Values | Default | Controls |
|---|---|---|---|
data-bs-theme | light | dark | light | Colour mode (Bootstrap-native) |
data-av-preset | aurora oxford pine matsuba frost deepsea urbanite jewel heritage kuri catawba granite storm | aurora | Colour: palette, greys, canvas, rail |
data-av-style | auto clean editorial soft tactile bold glass brutal flat luxe organic blueprint duotone bento | auto (the preset's own) | Construction: surfaces, shadows, shapes, display face, tiles, charts |
data-av-layout | 10 arrangements — vertical rail two-column horizontal mega stacked detached floating bottom overlay | vertical | Shell arrangement — see Layout Modes |
data-av-nav-skin | plain tint ink | preset's own choice | Navigation surface treatment, independent of colour mode |
data-av-density | compact comfortable spacious | comfortable | Spacing multiplier |
data-av-radius | sharp subtle rounded pill | rounded | Corner radius scale |
data-av-sidebar | expanded collapsed hidden | expanded | Sidebar state |
data-av-topbar | static sticky hidden auto-hide | sticky | Topbar behaviour |
data-av-width | fluid boxed | fluid | Content width |
data-av-contrast | normal high | normal | Accessibility contrast boost |
data-av-depth | rich plain | rich | Surface treatment. rich uses the style's KPI recipe and stronger chart fills; plain forces outline KPI tiles and lighter fills |
data-av-motion | full reduced off | full | User motion override |
dir | ltr rtl | ltr | Text direction |
Every one is optional. Omit an attribute and the default applies.
Why attributes on <html> and not classes on <body>
| Reason | Detail |
|---|---|
Available before <body> parses | The boot script can set them at the very top of <head> |
| Multiple independent axes | Classes would collide: .dark.aurora.compact versus orthogonal attributes |
| Selector clarity | [data-av-density="compact"] states intent; .compact does not |
| Bootstrap compatibility | 5.3 already uses data-bs-theme; we follow the same pattern |
| No specificity inflation | Attribute selectors are 0-1-0, the same as a class |
The boot script
The single most important 15 lines in the entire product. It must be inline, synchronous, and the first script in <head>.
html
<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'); // suppresses transitions during the initial paint
requestAnimationFrame(function () {
requestAnimationFrame(function () { d.classList.remove('av-booting'); });
});
})();
</script>Why it cannot be deferred, async, or in an external file
❌ External / deferred script
HTML parsed → CSS applied → page painted LIGHT → script runs → attribute set → repaint DARK
↑ user sees a white flash
✅ Inline synchronous script in <head>
HTML parse pauses → script runs → attribute set → CSS applied → page painted DARK onceThe flash is roughly 100–300 ms of full-screen white. On a dark-mode admin panel opened at night, it is the difference between "polished" and "broken".
The cost is ~0.4 ms of parser-blocking execution. Do not try to optimise it away.
CSP
An inline script needs a nonce under a strict CSP:
html
<script nonce="{{ csp_nonce }}"> … </script>Content-Security-Policy: script-src 'self' 'nonce-{{ csp_nonce }}'Never use 'unsafe-inline'. See Security.
.av-booting
Prevents transitions from firing during the first paint. Without it, applying the theme animates every colour on every element simultaneously.
scss
.av-booting,
.av-booting *,
.av-booting *::before,
.av-booting *::after {
transition: none !important;
animation-duration: 0.01ms !important;
}The boot script removes the class two frames later. It does not wait for the runtime, so a page that loads no runtime (an error page) gets its hover states back too.
The class stops the theme from animating its way in. It does not make the first render still: the stat cards rise in one after another on load. That entrance carries a delay longer than the two frames, so it starts once the class is gone. prefers-reduced-motion: reduce and data-av-motion="reduced" or "off" remove it.
How presets work
A preset redefines the primitive ramps. Everything downstream follows automatically.
scss
@layer tokens {
[data-av-preset="aurora"] {
--av-primary-50: oklch(97% .014 258);
--av-primary-500: oklch(63% .176 258);
--av-primary-600: oklch(55% .190 258);
--av-primary-700: oklch(47% .172 258);
--av-accent-500: oklch(66% .16 195);
}
[data-av-preset="kuri"] {
--av-primary-50: oklch(97% .006 53);
--av-primary-500: oklch(62% .07 53);
--av-primary-600: oklch(48% .075 53);
--av-primary-700: oklch(41% .06 55);
--av-accent-500: oklch(72% .07 215);
}
}Because --av-color-primary aliases --av-primary-600, and every button, link, badge, focus ring, and chart references --av-color-primary, a preset switch re-themes the entire application with a single attribute change and zero JavaScript.
A preset may also change
The tint of every grey, the canvas, the rail and the eight chart colours, in both colour modes:
scss
[data-av-preset="storm"] {
--av-neutral-500: oklch(63% .014 135); /* greys tinted toward sage */
--av-surface-base: oklch(93% .017 68); /* a warm ivory canvas */
--av-sidebar-bg: oklch(26% .034 249); /* an ink rail in storm blue */
--av-chart-1: oklch(30% .036 249); /* the first of eight chart colours */
}Corners, shadows, the display face, the KPI tile recipe and the chart shapes are not the preset's: they belong to the UI style the preset wears by default, which data-av-style overrides.
Full catalogue: Theme Presets.
The theme object
AdminVora.theme is a thin wrapper in src/js/adminvora.js: it writes attributes on <html> and persists them to localStorage under adminvora.prefs.
| Keys it accepts | mode, preset, style, layout, nav-skin, density, radius, sidebar, topbar, width, contrast, motion, depth, dir |
|---|
set(key, value)writesdata-av-<key>(ordata-bs-themeformode,dirfordir), saves, and emitsav:theme:change— plusav:theme:modewhen the mode changes. An unknown key throws.apply(prefs)sets several keys at once with transitions suppressed for one paint.- While
modeissystem, the theme follows the OS colour scheme live. - A change in another tab is applied here with
{ persist: false }, so tabs do not write-loop. [data-av-theme-toggle]and[data-av-theme-set="key:value"]buttons work with no JavaScript of your own.
Public API
js
AdminVora.theme.get('preset'); // 'aurora'
AdminVora.theme.set('preset', 'urbanite');
AdminVora.theme.toggle(); // light ⇄ dark
AdminVora.theme.apply({ mode: 'dark', preset: 'urbanite', density: 'compact' });
AdminVora.theme.reset(); // clear all preferences
AdminVora.on('av:theme:change', ({ key, value }) => console.log(key, '→', value));Declarative triggers
html
<button data-av-theme-toggle aria-label="Toggle colour mode">…</button>
<button data-av-theme-set="preset:urbanite">Urbanite</button>
<button data-av-theme-set="density:compact">Compact</button>
<button data-av-theme-set="dir:rtl">العربية</button>Preventing transition flash on change
When several tokens change at once, animating every colour looks like a glitch.
scss
.av-theming,
.av-theming *,
.av-theming *::before,
.av-theming *::after {
transition: none !important;
}The double requestAnimationFrame in apply() guarantees the class survives one full paint before removal. A single rAF fires before the style recalculation completes and the flash still occurs.
Server-side rendering
Render the preferences into the HTML so there is nothing to correct on the client.
Laravel
blade
<html lang="{{ app()->getLocale() }}"
dir="{{ $prefs['dir'] ?? 'ltr' }}"
data-bs-theme="{{ $prefs['resolved'] ?? 'light' }}"
data-av-preset="{{ $prefs['preset'] ?? 'aurora' }}"
data-av-layout="{{ $prefs['layout'] ?? 'vertical' }}">php
// app/Http/Middleware/ShareThemePreferences.php
public function handle($request, Closure $next)
{
View::share('prefs', $request->user()?->theme_preferences
?? json_decode($request->cookie('adminvora.prefs') ?? '{}', true));
return $next($request);
}Django
django
<html lang="{{ LANGUAGE_CODE }}"
data-bs-theme="{{ request.av_prefs.resolved|default:'light' }}"
data-av-preset="{{ request.av_prefs.preset|default:'aurora' }}">The boot script still runs — it reconciles localStorage with what the server rendered, so a user who changes the theme in one tab sees it in the next navigation even before the server knows.
Important — when the server renders the attributes,
mode: 'system'still needs the client to resolveprefers-color-scheme. Keep the boot script.
Cross-tab sync
js
addEventListener('storage', (e) => {
if (e.key !== 'adminvora.prefs' || !e.newValue) return;
AdminVora.theme.apply(JSON.parse(e.newValue), { persist: false });
});persist: false prevents a write loop between tabs.
Adding a custom preset
1. Add an entry to PRESETS
Every preset is an entry in PRESETS in tools/presets.mjs. You supply a hue and a chroma and the curve fills in the ramp; overrides pins the steps the curve should not decide. The default style and the palette are required; Theme Presets lists them.
js
// tools/presets.mjs, inside PRESETS
acme: {
hue: 340, chroma: .20,
overrides: { 500: 'oklch(62% 0.200 340)', 600: 'oklch(54% 0.210 340)' },
accent: 'oklch(70% 0.160 20)', neutral: [340, .02],
style: 'soft',
palette: ['oklch(54% 0.2 340)', 'oklch(58% 0.1 200)', 'oklch(50% 0.12 280)', 'oklch(60% 0.12 60)',
'oklch(52% 0.08 150)', 'oklch(56% 0.14 20)', 'oklch(46% 0.05 250)', 'oklch(60% 0.08 100)']
},Optional surfaces and sidebar fields give the preset its own canvas and rail; the shipped presets show both.
2. Build and register
bash
npm run tokens && npm run build:cssNothing is registered at runtime: a preset exists because tokens.css carries a [data-av-preset="…"] block for it, which npm run tokens writes from PRESETS in tools/presets.mjs. Add it there and run the build, and the attribute works. The customizer lists its presets in html/_partials/customizer.html; add a swatch there to offer the new one.
3. Verify
Add the name to PRESETS in tests/lib/server.mjs so the suites cover it, then:
bash
npm run check:tokens # every var(--av-…) resolves
npm run test:contrast # 4.5:1 for every preset in both modestest:contrast names the element and the pair that fails. The customizer's preset picker is checked by npm run check:inventory, which fails until the new preset is offered there too.
Theme debugging
js
AdminVora.theme.get('preset');
// Inspect a resolved token
getComputedStyle(document.documentElement).getPropertyValue('--av-color-primary');
// Dump every AdminVora token currently in effect
Object.fromEntries(
[...document.styleSheets]
.flatMap((s) => { try { return [...s.cssRules]; } catch { return []; } })
.filter((r) => r.selectorText === ':root')
.flatMap((r) => [...r.style])
.filter((p) => p.startsWith('--av-'))
.map((p) => [p, getComputedStyle(document.documentElement).getPropertyValue(p).trim()])
);Read next: Dark Mode.