Skip to content

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">
AttributeValuesDefaultControls
data-bs-themelight | darklightColour mode (Bootstrap-native)
data-av-presetaurora oxford pine matsuba frost deepsea urbanite jewel heritage kuri catawba granite stormauroraColour: palette, greys, canvas, rail
data-av-styleauto clean editorial soft tactile bold glass brutal flat luxe organic blueprint duotone bentoauto (the preset's own)Construction: surfaces, shadows, shapes, display face, tiles, charts
data-av-layout10 arrangements — vertical rail two-column horizontal mega stacked detached floating bottom overlayverticalShell arrangement — see Layout Modes
data-av-nav-skinplain tint inkpreset's own choiceNavigation surface treatment, independent of colour mode
data-av-densitycompact comfortable spaciouscomfortableSpacing multiplier
data-av-radiussharp subtle rounded pillroundedCorner radius scale
data-av-sidebarexpanded collapsed hiddenexpandedSidebar state
data-av-topbarstatic sticky hidden auto-hidestickyTopbar behaviour
data-av-widthfluid boxedfluidContent width
data-av-contrastnormal highnormalAccessibility contrast boost
data-av-depthrich plainrichSurface treatment. rich uses the style's KPI recipe and stronger chart fills; plain forces outline KPI tiles and lighter fills
data-av-motionfull reduced offfullUser motion override
dirltr rtlltrText direction

Every one is optional. Omit an attribute and the default applies.

Why attributes on <html> and not classes on <body> ​

ReasonDetail
Available before <body> parsesThe boot script can set them at the very top of <head>
Multiple independent axesClasses would collide: .dark.aurora.compact versus orthogonal attributes
Selector clarity[data-av-density="compact"] states intent; .compact does not
Bootstrap compatibility5.3 already uses data-bs-theme; we follow the same pattern
No specificity inflationAttribute 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 once

The 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 acceptsmode, preset, style, layout, nav-skin, density, radius, sidebar, topbar, width, contrast, motion, depth, dir
  • set(key, value) writes data-av-<key> (or data-bs-theme for mode, dir for dir), saves, and emits av:theme:change — plus av:theme:mode when the mode changes. An unknown key throws.
  • apply(prefs) sets several keys at once with transitions suppressed for one paint.
  • While mode is system, 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 resolve prefers-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:css

Nothing 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 modes

test: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.

Documentation for @creativeigniter/adminvora