Skip to content

The Customizer ​

A live theming panel that writes preference attributes onto <html>, persists them under one localStorage key, and is read back before first paint by the boot script. It is the demonstration surface for the theme engine: every control in it is a thin wrapper around AdminVora.theme.set(), and nothing it does is unavailable to your own code.


What it is for ​

AudienceUse
EvaluatorsTry every preset × style × navigation layout × colour mode without reading a line of CSS
DevelopersFind the combination you want, then pin it as attributes on <html>
End usersExpose the axes that are genuine preferences — colour mode, density, contrast, reduced motion

It is a demonstration and development tool by default. Ship it to end users only with the axes you deliberately want them to change.


Where it lives ​

FileRole
html/_partials/customizer.htmlThe edge trigger and the panel
html/_partials/boot.htmlReads the stored preferences before first paint
src/scss/components/_customizer.scssPanel, swatches and navigation previews
src/js/adminvora.js — initCustomizer()Opening, closing, syncing and writing

The partial is pulled in by the closing shell partials — shell-close, shell-close-app, public-close, and auth-close for a page that opts in with "customizer": true, so almost every page carries it. The exceptions: the six utility and error screens, which deliberately never fetch the runtime so that they still render when the bundle is what broke, and the two auth variants that leave it out.


Two ways in ​

The panel has a fixed edge tab of its own, and a page may add its own trigger anywhere:

html
<button class="av-customizer-trigger" type="button" data-av-customizer-open
        aria-label="Customise theme" aria-controls="avCustomizer">
  <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24">
    <circle cx="8" cy="6" r="2"/><path d="M2 6h4M10 6h12"/>
    <circle cx="16" cy="12" r="2"/><path d="M2 12h12M18 12h4"/>
    <circle cx="10" cy="18" r="2"/><path d="M2 18h6M12 18h10"/>
  </svg>
</button>
html
<!-- Anywhere on the page: a second trigger, same attribute -->
<button class="av-btn av-btn--outline" type="button" data-av-customizer-open>Change theme</button>

initCustomizer() binds every [data-av-customizer-open] on the page, not the first one. index.html, ui-overview.html and ui-layout.html each ship a header button and the partial's edge tab; binding only the first match left the edge tab — the control that looks most like the way in — inert on those three pages. A button that looks live and does nothing is worse than no button, because the visitor concludes the feature is broken rather than absent.

The icon turns slowly, and the animation is dropped under prefers-reduced-motion: reduce. At rest the tab is 24px wide, the width of the content gutter, so it never covers a card's last column (it used to cover the CRM leaderboard's Value column); it widens on hover and focus. Below 576px it leaves the edge for a round button in the bottom corner.


The panel ​

html
<aside class="av-customizer" id="avCustomizer" data-av-customizer
       role="dialog" aria-modal="false" aria-labelledby="avCustomizerTitle" hidden>
  <header class="av-customizer__header">
    <h2 class="av-customizer__title" id="avCustomizerTitle">Customise</h2>
    <button class="av-btn av-btn--ghost av-btn--icon" style="--av-btn-height: 34px"
            type="button" data-av-drawer-close aria-label="Close">
      <svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24">
        <path d="M6 6l12 12M18 6L6 18"/>
      </svg>
    </button>
  </header>

  <div class="av-customizer__body">
    <!-- one <fieldset class="av-customizer__group"> per axis; see below -->
  </div>

  <footer class="av-customizer__footer">
    <button class="av-btn av-btn--outline" type="button" data-av-customizer-reset>Reset</button>
  </footer>
</aside>

The panel is hidden until opened; is-open drives the slide. It is fixed to the inline-end edge and transforms in from translateX(100%) — translateX(-100%) under dir="rtl", because a transform has no logical form.


The axes ​

Eight <fieldset> groups and the footer, in the order they appear:

LegendControlWritesValues
Colour mode.av-segmenteddata-bs-themelight, dark, system (default)
Theme.av-swatch-griddata-av-presetEvery preset, aurora default
Style.av-swatch-griddata-av-styleauto (the preset's own) and every style; each swatch is a miniature drawn in that style (.av-style-swatch--<name>)
Navigation.av-swatch-grid.av-swatch-grid--pairdata-av-layout10 layouts, vertical default
Navigation surface.av-segmenteddata-av-nav-skinplain (default), tint, ink
Corners.av-segmenteddata-av-radiussharp, subtle, rounded (default), pill
Density.av-segmenteddata-av-densitycompact, comfortable (default), spacious
Content width.av-segmenteddata-av-widthfluid (default), boxed
Accessibility.av-switch ×4data-av-contrast, data-av-depth, data-av-motion, diron/off pairs
Footer.av-btnclears everythingdata-av-customizer-reset

AdminVora.theme.set() accepts thirteen keys; the panel exposes eleven of them. sidebar is written by the sidebar's own collapse toggle rather than by a control here, and topbar is accepted by the theme module but no stylesheet rule reads it today — an axis with a name and no behaviour, recorded here rather than implied to work.

Enumerations with words: .av-segmented ​

html
<fieldset class="av-customizer__group">
  <legend class="av-customizer__legend">Density</legend>
  <div class="av-segmented" role="radiogroup" aria-label="Density">
    <label><input type="radio" name="av-density" value="compact">Compact</label>
    <label><input type="radio" name="av-density" value="comfortable" data-av-default>Default</label>
    <label><input type="radio" name="av-density" value="spacious">Spacious</label>
  </div>
</fieldset>

The radio is visually hidden by the component (position: absolute; opacity: 0), never removed from the accessibility tree, and the selected state is drawn from :has(input:checked). The name is the contract: av-<key>, and the runtime derives the theme key from it by stripping av-.

Enumerations you have to see: .av-swatch ​

A preset is a look, so its chip shows the three things that tell presets apart: the rail, the canvas and the primary. The chip carries the preset's own attribute, so that preset's tokens paint it and it cannot drift from the theme it previews:

html
<label class="av-swatch">
  <input type="radio" name="av-preset" value="kuri">
  <span class="av-swatch__chip" data-av-preset="kuri"></span>
  <span class="av-swatch__name">Kuri</span>
</label>

A layout is an arrangement, so its chip is a wireframe rather than a word. "Detached" and "rail" name nothing a visitor can picture, and the whole point of the axis is that it is seen:

html
<label class="av-swatch">
  <input type="radio" name="av-layout" value="rail">
  <span class="av-nav-preview av-nav-preview--rail"></span>
  <span class="av-swatch__name">Rail</span>
</label>

.av-nav-preview draws both shapes from pseudo-elements — no extra markup, no image — and answers to the active preset like everything else. Its insets are logical, so the previews mirror under dir="rtl" alongside the layouts they describe.

Booleans: .av-switch ​

html
<fieldset class="av-customizer__group">
  <legend class="av-customizer__legend">Accessibility</legend>
  <div class="av-customizer__stack">
    <label class="av-switch">
      <input type="checkbox" id="avPrefContrast" data-av-pref="contrast"
             data-on="high" data-off="normal">
      High contrast
    </label>
    <label class="av-switch">
      <input type="checkbox" id="avPrefDepth" data-av-pref="depth"
             data-on="rich" data-off="plain" data-av-default>
      Rich surfaces
    </label>
  </div>
</fieldset>

data-av-pref names the theme key; data-on and data-off are the two values it toggles between. A switch never writes a bare true/false, because the attribute it sets is an enumerated axis that CSS selects on — [data-av-depth="plain"] has to be a state you can target, not the absence of one.


data-av-default ​

Every axis has a value that is in force when no attribute is present. The attribute is absent in that state, so a naive input.checked = theme.get(key) === input.value leaves the whole group showing nothing selected the first time the panel is opened.

data-av-default marks the option that "no attribute" means:

js
function sync() {
  el.querySelectorAll('input[name^="av-"]').forEach((input) => {
    const key = input.name.replace('av-', '');
    const current = theme.get(key) ?? input.dataset.avDefault;
    input.checked = current === input.value ||
      (!theme.get(key) && input.hasAttribute('data-av-default'));
  });
  el.querySelectorAll('[data-av-pref]').forEach((input) => {
    input.checked = theme.get(input.dataset.avPref) === input.dataset.on;
  });
}

Keep the marker on whichever option the stylesheet falls back to. Moving a default in SCSS without moving data-av-default gives you a panel that reports a setting the page is not using.

It is read in one branch only — the one that walks input[name^="av-"]. On a switch it is inert: the [data-av-pref] branch derives checked from the attribute's value alone. A switch carried one for a while, claiming rich as the default for data-av-depth; the switch was right anyway, because data-av-depth="rich" is written into every page's <html> tag, but the marker itself did nothing and the next person to read that markup would have trusted it. npm run check:customizer now fails on a data-av-default outside a radio group, on a group with none or with two, on a control naming a key theme.set() would throw on, and on a control writing an attribute no stylesheet rule selects.

That last one is the important half. A key that is not in KEYS throws on the visitor's first click; an attribute nothing reads fails silently and for ever — the panel reports the new setting, the attribute is on <html>, and the page is identical. data-av-topbar is exactly that today: accepted by theme.set(), painted by the boot script, read by nothing. It is harmless only because no control offers it.


The runtime ​

initCustomizer() runs once per page. It is not a per-element module and takes no claim through scan() — there is one panel.

js
function initCustomizer() {
  const el = document.querySelector('[data-av-customizer]');
  if (!el) return;

  const triggers = [...document.querySelectorAll('[data-av-customizer-open]')];
  let lastFocus = null;

  function open() {
    lastFocus = document.activeElement;
    el.hidden = false;
    // Next frame, so the transition from translateX(100%) actually runs.
    requestAnimationFrame(() => el.classList.add('is-open'));
    sync();
    el.querySelector('button, input')?.focus({ preventScroll: true });
  }

  function close() {
    el.classList.remove('is-open');
    el.addEventListener('transitionend', () => {
      if (!el.classList.contains('is-open')) el.hidden = true;
    }, { once: true });
    lastFocus?.focus({ preventScroll: true });
  }

  triggers.forEach((t) => t.addEventListener('click',
    () => (el.classList.contains('is-open') ? close() : open())));
  el.querySelector('[data-av-drawer-close]')?.addEventListener('click', close);
  document.addEventListener('keydown', (e) => {
    if (e.key === 'Escape' && el.classList.contains('is-open')) close();
  });

  // One delegated listener for every control in the panel.
  el.addEventListener('change', (e) => {
    const input = e.target;
    if (input.name?.startsWith('av-')) {
      theme.set(input.name.replace('av-', ''), input.value);
    }
    if (input.dataset.avPref) {
      theme.set(input.dataset.avPref, input.checked ? input.dataset.on : input.dataset.off);
    }
  });

  el.querySelector('[data-av-customizer-reset]')
    ?.addEventListener('click', () => { theme.reset(); sync(); });

  on('av:theme:change', sync);
  sync();
}

Two details worth copying if you write your own panel:

  • One change listener on the panel, not one per control. The presets, styles and layouts alone are dozens of radios in this panel; delegation keeps that at one binding, and keeps working when you add an axis.
  • sync() is subscribed to av:theme:change, so the panel follows the theme rather than owning it. A keyboard shortcut, a data-av-theme-set button elsewhere on the page, or another browser tab writing the same localStorage key all move the controls. Without that subscription the panel is a second writer for state the document already holds, and the two drift apart the first time anything else sets a value.

The panel is hidden while closed, so its controls are out of the tab order until it opens.


Persistence ​

Everything goes through AdminVora.theme, which writes one key:

js
localStorage['adminvora.prefs'];
// '{"mode":"dark","preset":"urbanite","layout":"rail","nav-skin":"ink",
//   "density":"compact","width":"boxed","contrast":"high","depth":"plain","dir":"ltr"}'

Only keys with a value are recorded, which is every key whose attribute is on <html> at the moment of the write — including depth, which every page states in its own opening tag, and dir, which theme.get() answers 'ltr' for when the attribute is absent. The inline boot script in <head> reads that key synchronously and paints the attributes before first paint; the runtime then hydrates mode from the same snapshot. Never defer or externalise the boot script — both reintroduce the flash of the wrong theme it exists to prevent. See Theme Engine → The boot script.

Changes in one tab reach the others through the storage event, applied with { persist: false } so that two open tabs do not write to each other in a loop.

Reset ​

js
AdminVora.theme.reset();

Removes the storage key, drops every data-av-* axis attribute, sets dir back to ltr and mode back to system, then emits av:theme:reset and av:theme:change. The panel's Reset button calls it and re-syncs, so the controls fall back to their data-av-default options in the same frame.


Keeping a combination ​

There is no export button. The panel writes attributes, and the attributes are the artefact, so pinning a combination is a copy rather than a code generator:

  1. Set the panel to the combination you want.
  2. Read the attributes off <html> in devtools, or read localStorage['adminvora.prefs'].
  3. Write them into your own document's opening tag.
html
<html lang="en" dir="ltr"
      data-bs-theme="dark"
      data-av-preset="urbanite"
      data-av-layout="rail"
      data-av-nav-skin="tint"
      data-av-density="compact"
      data-av-radius="subtle"
      data-av-width="boxed"
      data-av-depth="plain">

Attributes written into the markup hold only until the boot script runs — it paints the stored snapshot over them. If you want a fixed theme rather than a starting one, drop the customizer partial and the boot script together, or apply the values server-side and stop persisting.

Applying several at runtime is one call, which suppresses transitions for the whole batch:

js
AdminVora.theme.apply({
  mode: 'dark', preset: 'urbanite', layout: 'rail', density: 'compact'
});

Shipping to production ​

Remove it ​

Drop {{> customizer }} from the closing shell partial and rebuild:

bash
npm run build:html

The panel's CSS lives in src/scss/components/_customizer.scss; drop its @use from src/scss/adminvora.scss if you want the bytes back as well. initCustomizer() returns immediately when no [data-av-customizer] element is present, so nothing in the runtime needs to change.

Ship a reduced version ​

Delete the <fieldset class="av-customizer__group"> blocks for the axes you do not want to expose. Colour mode, density, contrast and reduced motion are real accessibility affordances that users benefit from controlling; letting them repaint your brand usually is not. Nothing else has to change — the runtime iterates over the controls that are present.

Gate it server-side ​

The partial is plain markup, so a template can include it conditionally:

blade
@can('manage-branding')
  @include('adminvora.partials.customizer')
@endcan

Accessibility ​

RequirementImplementation
Keyboard operableEvery control is a native <input type="radio"> or <input type="checkbox"> in a <fieldset>/<legend> group
GroupingEach axis is a <fieldset> with a <legend>; the control row carries role="radiogroup" and an aria-label
Escape closesA document keydown listener, active only while is-open
Focus inThe first button, input in the panel is focused on open
Focus outFocus returns to whichever element was active when the panel opened
Out of the tab order when closedThe panel is hidden, not merely translated off-screen
Not a modalaria-modal="false"

The panel is deliberately not aria-modal="true". A modal would trap focus and hide the page from assistive technology, which defeats the point: the visitor needs to perceive the page changing as they adjust it. The trade is stated rather than hidden — Tab does leave the panel, and that is the intended behaviour, not a missing focus trap.

Two limits worth knowing before you extend it:

  • Changes are not announced. Assistive technology reports the control's own state change; nothing describes what happened to the page, so an axis whose effect is not visible at the control — density, say — is silent. If you expose the panel to end users, add a live region.
  • The listeners are bound without { signal }, because a singleton has no teardown path in this zero-build runtime. AdminVora.destroy(root) does not detach them.

Panel styles ​

scss
// src/scss/components/_customizer.scss
@layer components {
  .av-swatch {
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: var(--av-space-1);
    padding: var(--av-space-2);
    border: 1px solid var(--av-border-subtle);
    border-radius: var(--av-radius-md);
    cursor: pointer;
    transition:
      border-color var(--av-duration-fast) var(--av-ease-standard),
      box-shadow var(--av-duration-fast) var(--av-ease-standard);
  }

  .av-swatch input { position: absolute; opacity: 0; pointer-events: none; }

  .av-swatch__chip {
    inline-size: 100%;
    block-size: 26px;
    border-radius: var(--av-radius-sm);
    background: linear-gradient(135deg, var(--c1) 0 55%, var(--c2) 55% 100%);
    box-shadow: inset 0 0 0 1px oklch(var(--av-shadow-color) / .06);
  }

  .av-swatch:has(input:checked) {
    border-color: var(--av-color-primary);
    box-shadow: 0 0 0 1px var(--av-color-primary);
  }

  .av-swatch:has(input:focus-visible) {
    outline: var(--av-focus-width) solid var(--av-focus-color);
    outline-offset: var(--av-focus-offset);
  }
}

:has(input:checked) keeps the selected state entirely in CSS — no class toggling in JS, and it stays correct when a radio is set programmatically by sync() rather than clicked.

The navigation previews are the same idea applied to layout. Each draws two rectangles, and the pair has to be unmistakable at 34px:

scss
@layer components {
  .av-nav-preview {
    position: relative;
    inline-size: 100%;
    block-size: 34px;
    border-radius: var(--av-radius-sm);
    background: var(--av-surface-sunken);
    box-shadow: inset 0 0 0 1px oklch(var(--av-shadow-color) / .08);
    overflow: hidden;
  }

  // ::before is the navigation, ::after the content it leaves room for.
  .av-nav-preview::before,
  .av-nav-preview::after {
    content: '';
    position: absolute;
    border-radius: var(--av-radius-xs);
    background: var(--av-color-primary);
  }

  .av-nav-preview--rail::before {
    inset-block: 4px; inset-inline-start: 4px; inline-size: 5px;
  }
  .av-nav-preview--rail::after {
    inset-block: 4px; inset-inline: 13px 4px;
    background: var(--av-border-default);
  }
}

mega and stacked both put a bar along the top, so the second shape is the only thing telling them apart: mega drops a deep translucent panel, stacked lays a second thin rail. Drawn the other way round they read as the same picture, which is the failure this axis exists to avoid.

Read next: Layout Anatomy.

Documentation for @creativeigniter/adminvora