Skip to content

Topbar ​

Search, colour mode, messages, notifications and the account menu. Plus the command palette, which is the part people notice.

The whole bar is one partial — html/_partials/topbar.html, 54 lines — included by shell-open. Change it there and every page that uses the shell changes with it.


Regions ​

┌──────────────────────────────────────────────────────────────────┐
│ [☰] [ Search… Ctrl K ]  (●Healthy)(Disk 84%)(Online 12)  [🌓][✉][🔔] [FP ▾] │
└──────────────────────────────────────────────────────────────────┘
  start                    vitals (optional)              end

Two flex children, plus the optional vitals strip between them (below). __end takes margin-inline-start: auto, so anything added to __start grows leftwards from the search field rather than pushing the account menu off the bar.

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">
    <!-- colour mode, messages drawer, notifications drawer, account menu -->
  </div>
</header>
scss
.av-topbar {
  grid-area: topbar;
  display: flex;
  align-items: center;
  gap: var(--av-space-3);
  min-block-size: var(--av-topbar-height);
  padding-inline: var(--av-space-4);
  background: var(--av-surface-raised);
  border-block-end: 1px solid var(--av-border-subtle);
  z-index: var(--av-z-topbar);
}
.av-topbar__start { display: flex; align-items: center; gap: var(--av-space-2); min-inline-size: 0; }
.av-topbar__end { display: flex; align-items: center; gap: var(--av-space-1); margin-inline-start: auto; }

grid-area: topbar is the first declaration, and it says where this class can live: inside the shell's grid, nowhere else. min-inline-size: 0 on __start is the one that is easy to leave out — a flex item's automatic minimum size is its content's min-content width, so without it a long search field grows the bar past the viewport instead of shrinking inside it.

There is no data-av-topbar attribute. The bar is part of the shell grid; it does not scroll away, auto-hide or take a behaviour option. If you want auto-hide, that is a feature to add to the shell, not a value to write into markup expecting the runtime to read it.

Vitals strip ​

.av-vitals puts live readings in the bar's free middle: health, load, memory, disk, people online, queued work. Each reading is a link to the page that explains it, so the strip is a way in rather than a second dashboard. The partial is html/_partials/vitals.html.

html
<div class="av-vitals" role="group" aria-label="System status">
  <ul class="av-vitals__list">
    <li class="av-vitals__entry">
      <a class="av-vitals__item" href="/admin/health">
        <span class="av-dot av-dot--success" aria-hidden="true"></span>
        <span class="av-vitals__value">Healthy</span>
      </a>
    </li>
    <li class="av-vitals__entry av-vitals__entry--secondary">
      <a class="av-vitals__item av-vitals__item--warning" href="/admin/health">
        Disk <span class="av-vitals__value">84%</span>
        <span class="av-vitals__meter" style="--av-vitals-value: 84" aria-hidden="true"></span>
      </a>
    </li>
  </ul>
  <button class="av-vitals__summary" type="button" data-av-drawer-open="#avVitalsDrawer"
          aria-haspopup="dialog" aria-label="System status: one warning. Show details">
    <span class="av-dot av-dot--warning" aria-hidden="true"></span>
    <span aria-hidden="true">Status</span>
  </button>
  <dialog class="av-drawer" id="avVitalsDrawer" aria-labelledby="avVitalsDrawerTitle">…</dialog>
</div>
ClassWhat it does
.av-vitalsTakes the room between __start and __end and is a size container
.av-vitals__entryOne list item. --secondary shows from a 27rem strip, --tertiary from 40rem
.av-vitals__itemOne reading. Quiet at rest (no border or fill) so the strip reads as one line of figures; a link when it leads somewhere, a <span> when it does not
.av-vitals__item--warning, --dangerBorder, number and meter turn together: a reading only draws a border when it needs attention
.av-vitals__valueThe number, in tabular figures so the pill does not jitter as it changes
.av-vitals__meterA small bar for a share of a whole; set --av-vitals-value from 0 to 100
.av-vitals__summaryBelow a 15rem strip the list hides and this button opens the details drawer

The breakpoints are container queries on the strip, not media queries, because the room in the middle depends on the sidebar posture as much as on the window. You decide the order and which readings can go first; the strip never measures text. When a reading turns --warning or --danger, drop its --secondary or --tertiary class, so a problem is never the reading that got hidden. The list keeps to one row: a reading that still does not fit wraps out of sight whole rather than spilling over the search field, and readings marked --warning or --danger move to the front first.

The strip holds no data and does not poll. Your app writes the values, the state modifiers and the summary's accessible name on its own timer, and keeps the drawer's readings in step. The drawer is an ordinary .av-drawer; the demo fills it with .av-usage rows and an .av-detail-list.

The translucency is deliberate ​

scss
@supports (backdrop-filter: blur(1px)) {
  .av-topbar {
    background: var(--av-glass-bg);
    backdrop-filter: blur(var(--av-glass-blur)) saturate(180%);
    box-shadow: 0 1px 0 var(--av-glass-border), var(--av-shadow-sm);
  }
}

Content does not scroll under this bar, so the blur has nothing to soften. The translucency is the point: it lets the shell's ambient mesh tint the bar, so it belongs to the page instead of capping it. Browsers without backdrop-filter keep the opaque --av-surface-raised rule above.


Search trigger ​

.av-search-trigger is a button, not an input. It opens the palette; it never accepts typing. The same control appears on the help centre, where a search box that filtered nothing would be the worst kind of dead control.

Its text colour is the one measured decision in this file:

scss
.av-search-trigger {
  /* --av-text-subtle on the sunken fill measures 2.74:1 at its worst (harbour,
     light) and clears 4.5:1 in none of the 32 preset/mode combinations — the
     widest contrast failure in the product, on the one control every page
     carries. It reads as placeholder text, but it is a button with a label,
     and a label is held to 4.5:1. --av-text-secondary is the first token that
     clears it everywhere (worst 5.39:1); --av-text-muted does not (3.82:1). */
  color: var(--av-text-secondary);
}
/* Hover must move *towards* contrast: it used to drop from subtle to muted,
   which reads as a lift only because both were unreadable. */
.av-search-trigger:hover { border-color: var(--av-border-strong); color: var(--av-text-primary); }

Below 768px the label and the shortcut hint are hidden and the trigger loses its border, leaving the magnifier alone — an icon button in everything but markup. aria-label="Search pages and commands" is on the button itself for exactly that state, so the accessible name survives the visible one disappearing.


Command palette ​

Ctrl+K / ⌘+K, from anywhere. The markup is html/_partials/palette.html, included once by shell-close.

html
<dialog class="av-palette" data-av-palette aria-label="Command palette">
  <div class="av-palette__inner">
    <div class="av-palette__search">
      <svg class="av-icon" 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>
      <input class="av-palette__input" id="avPaletteInput" type="text" role="combobox"
             placeholder="Search pages, commands…" aria-label="Search pages and commands"
             aria-expanded="true" aria-controls="avPaletteResults"
             aria-autocomplete="list" aria-activedescendant=""
             autocomplete="off" spellcheck="false">
      <kbd class="av-kbd">Esc</kbd>
    </div>

    <ul class="av-palette__results" id="avPaletteResults" role="listbox" aria-label="Results"></ul>
    <p class="av-visually-hidden" role="status" aria-live="polite" data-av-palette-status></p>

    <footer class="av-palette__footer">
      <span><kbd class="av-kbd">↑</kbd><kbd class="av-kbd">↓</kbd> navigate</span>
      <span><kbd class="av-kbd">↵</kbd> select</span>
      <span><kbd class="av-kbd">Esc</kbd> close</span>
    </footer>
  </div>
</dialog>

It is a native <dialog> opened with showModal(). The focus trap, the backdrop, Escape and the inert rest-of-page are all the platform's — there is no trapFocus() call, because there is nothing left for one to do. cancel is intercepted only so the closing animation gets its 140ms before close() fires.

The results list ships empty. Every row is built by the module on the first keystroke, which is why there is no static markup for one to copy.

Sources ​

Routes and commands live in one table in src/js/adminvora.js. A page that wants its own replaces them outright:

js
window.AdminVoraConfig = Object.assign(window.AdminVoraConfig || {}, {
  palette: {
    sources: [
      { id: 'pages', label: 'Pages', items: [
        { label: 'Orders', hint: 'Go to', keywords: ['commerce', 'sales', 'table'],
          icon: '<path d="M6 7h12l-1.2 13H7.2L6 7z"/>',
          href: 'html/pages/apps/orders.html' }
      ]},
      { id: 'actions', label: 'Actions', items: [
        { label: 'Toggle colour mode', icon: '<circle cx="12" cy="12" r="4"/>',
          run: () => AdminVora.theme.toggle() }
      ]}
    ]
  }
});

Four things about that object are load-bearing.

Object.assign, never a plain assignment. The palette partial is included from shell-close, so it runs after the page's own content. A page that writes window.AdminVoraConfig = { … } above it has its config silently destroyed, and the page still boots — just without whatever it configured.

icon is the inner SVG markup, not a name. The module wraps it in <svg class="av-icon av-icon--sm" viewBox="0 0 24 24">…</svg>. There is no sprite and no icon: 'tabler:plus' resolver; see Iconography.

href or run, not both. An item with no run gets one built for it that navigates to AdminVoraConfig.root + href. Resolving the root here rather than in markup is the whole reason this partial replaced 73 per-page copies of the same 199 lines.

Sources are static. items is an array; there is no async search(query) hook. Wiring a remote source means fetching your records and rebuilding sources before the palette opens.

Matching ​

Fuzzy subsequence matching with score weighting.

js
function score(needle, haystack) {
  const n = needle.toLowerCase();
  const h = haystack.toLowerCase();
  if (!n) return 1;
  if (h.startsWith(n)) return 1000 - h.length;      // prefix beats everything
  if (h.includes(n)) return 500 - h.indexOf(n);     // substring next

  let si = 0, total = 0, streak = 0;
  for (let i = 0; i < h.length && si < n.length; i++) {
    if (h[i] === n[si]) {
      streak++;
      total += streak * 3;
      if (i === 0 || h[i - 1] === ' ' || h[i - 1] === '-') total += 10;   // word boundary
      si++;
    } else {
      streak = 0;
    }
  }
  return si === n.length ? total : 0;
}

The label and each keyword are scored separately, and the best of them wins at 0.8 weight:

js
const keywordBest = (item.keywords || [])
  .reduce((best, k) => Math.max(best, score(query, k) * 0.8), 0);
return { item, s: Math.max(score(query, item.label), keywordBest) };

Concatenating the keywords into one haystack instead would let an item with many keywords out-score a direct hit on another item's label. Eight results, then stop.

Accessibility ​

The palette is a combobox with a listbox popup, not a dialog containing a text field.

RequirementHow
role="combobox" on the inputAuthored in the partial
aria-controls → the listbox idaria-controls="avPaletteResults"
aria-activedescendant = highlighted option idSet to av-pal-<n> on every render and arrow key
role="listbox" / role="option"The <ul> in markup, each <li> by the module
aria-selected on the active optionRewritten across all options on every move
Focus trap, backdrop, EscapeNative <dialog> + showModal()
Focus restored on closelastFocus captured in open()
Result count announced[data-av-palette-status], a visually-hidden role="status"
js
function highlight(index) {
  const items = [...list.querySelectorAll('.av-palette__item')];
  if (!items.length) return;
  active = (index + items.length) % items.length;      // wraps at both ends
  items.forEach((el, i) => el.setAttribute('aria-selected', String(i === active)));
  input.setAttribute('aria-activedescendant', items[active].id);
  items[active].scrollIntoView({ block: 'nearest' });
}

Important — do not move DOM focus to the options. Focus stays in the input; the visual and announced selection is carried entirely by aria-activedescendant. Moving focus breaks typing.

The status line is the half that is easy to skip. Without it, a screen-reader user types and hears nothing at all, because the results appear somewhere they are not focused.

Keyboard ​

KeyAction
Ctrl/⌘+KOpen, or close if already open
↑ / ↓Move the highlight (wraps)
EnterRun the highlighted item
EscClose, restore focus
TabClose — do not trap somebody who wanted to leave
Ctrl/⌘+1..9Run result N directly

Running an item closes the dialog first and navigates 60ms later, so the browser finishes the close before the page is replaced.


Colour mode ​

One button holding two icons; CSS decides which is on screen.

html
<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>
scss
.av-mode-icon--dark { display: none; }
[data-bs-theme="dark"] .av-mode-icon--dark { display: block; }
[data-bs-theme="dark"] .av-mode-icon--light { display: none; }

No JavaScript in the render path: [data-av-theme-toggle] is delegated from document, and it writes the attribute the CSS above is already selecting on. The accessible name stays "Toggle colour mode" in both states, because the icon shows the current mode and the action is the same either way — a name that flips between "Switch to dark" and "Switch to light" is a name that goes stale the moment something else changes the mode. See Dark Mode.


Notifications ​

Notifications are a drawer, not a dropdown. A dropdown is the right shape for a short list of commands; this is a feed with inline actions, cards and a footer, and at that size a menu anchored to a 32px button is fighting its own geometry.

The trigger and the panel stay inside one [data-av-notifications] wrapper, because initNotifications reads both from it — which is why moving from dropdown to drawer needed none of the module's code.

html
<div class="av-notif" data-av-notifications>
  <button class="av-btn av-btn--ghost av-btn--icon" type="button"
          data-av-drawer-open="#avNotifDrawer" data-av-notif-trigger
          aria-haspopup="dialog" aria-label="Notifications, 3 unread">
    <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24">
      <path d="M6 17v-6a6 6 0 0 1 12 0v6l1.5 2.2H4.5L6 17z"/><path d="M10 21a2 2 0 0 0 4 0"/>
    </svg>
    <span class="av-notif__badge av-notif__badge--pulse" data-av-notif-badge aria-hidden="true">3</span>
  </button>

  <dialog class="av-drawer" id="avNotifDrawer" aria-labelledby="avNotifDrawerTitle">
    <div class="av-drawer__inner av-feed" data-av-notif-filter-group>
      <div class="av-drawer__header">
        <h2 class="av-drawer__title" id="avNotifDrawerTitle">
          Notifications
          <span class="av-badge av-badge--primary-soft" data-av-notif-total>3 new</span>
        </h2>
      </div>

      <div class="av-feed__tabs" role="group" aria-label="Filter notifications">
        <button class="av-feed__tab" type="button" data-av-notif-filter="all" aria-pressed="true">All</button>
        <button class="av-feed__tab" type="button" data-av-notif-filter="unread" aria-pressed="false">Unread</button>
        <button class="av-feed__tab" type="button" data-av-notif-filter="mention" aria-pressed="false">Mentions</button>
      </div>

      <div class="av-drawer__body">
        <ul class="av-feed__list" data-av-notif-list>
          <li class="av-feed__group">Today</li>
          <li class="av-feed__item is-unread" data-av-notif-item data-av-notif-kind="mention">
            <span class="av-avatar av-avatar--sm av-feed__avatar" aria-hidden="true">PR</span>
            <div class="av-feed__body">
              <p class="av-feed__title">
                <strong>Priya Raman</strong> asked you to approve access to
                <strong>Northwind Trading</strong>
              </p>
              <p class="av-feed__meta">
                <span class="av-visually-hidden">Unread. </span>
                <time datetime="2026-08-13T05:10:00Z" data-av-relative-time>13 August 2026</time>
                · Members
              </p>
            </div>
          </li>
        </ul>

        <div class="av-empty" data-av-notif-empty hidden>
          <h3 class="av-empty__title">Nothing here</h3>
          <p class="av-empty__text">You are up to date.</p>
        </div>
      </div>

      <div class="av-drawer__footer av-feed__foot">
        <button class="av-btn av-btn--primary" type="button" data-av-notif-mark-all>
          Mark all as read
        </button>
      </div>
    </div>
  </dialog>
</div>

One writer for the count ​

The unread number appears in four places — the badge, the "3 new" pill, the trigger's accessible name, and whether the Mark-all button is usable. Every one of them is derived from the same walk of the list by a single function:

js
function sync() {
  const unread = items().filter((i) => i.classList.contains('is-unread')).length;
  const any = items().length > 0;

  badge.textContent = unread > 9 ? '9+' : String(unread);
  badge.hidden = unread === 0;
  // The pulse is an unread signal, so it stops the moment the tray is clear.
  badge.classList.toggle('av-notif__badge--pulse', unread > 0);

  total.textContent = unread ? `${unread} new` : 'All read';
  trigger.setAttribute('aria-label',
    unread ? `Notifications, ${unread} unread` : 'Notifications, none unread');

  markAll.disabled = unread === 0;
  list.hidden = !any;
  empty.hidden = any;
}

A printed count beside a list the reader can change is a second writer for a number the list already knows, and it is the defect that has recurred most often in this codebase. sync() is the answer: nothing anywhere else touches those four surfaces, and tests/msgs.mjs asserts all four agree.

The badge is aria-hidden="true" because the count is already in the button's accessible name. Announced twice, it reads as "Notifications 3 unread 3".

Reading is the same gesture as opening — clicking a row clears its is-unread and re-syncs, rather than making the reader find a separate control. Mark all as read announces what it did and then moves focus to the trigger, because it has just disabled itself and focus would otherwise fall back to the document.

Filters that filter ​

[data-av-notif-filter-group] is initNotifFilters, shared with the audit log and the public FAQ:

html
<div data-av-notif-filter-group data-av-notif-noun="question">
  <button data-av-notif-filter="billing" aria-pressed="false">Billing</button>
  <p data-av-notif-group>Billing</p>
  <div data-av-notif-item data-av-notif-kind="billing">…</div>
</div>
AttributeRole
data-av-notif-filter-groupThe scope. Rows, headings, chips and the empty state are found inside it
data-av-notif-filterOn a chip: all, unread, or a value matched against a row's kind
data-av-notif-itemA filterable row
data-av-notif-kindWhat that row is, for the third filter type
data-av-notif-groupA heading that hides when every row beneath it does
data-av-notif-emptyShown when nothing survived
data-av-notif-nounThe word in the announcement. Defaults to notification

A heading belongs to the rows after it and before the next heading, so the module walks forward from each one rather than indexing the list — that survives rows being added or reordered.

data-av-notif-noun is why the FAQ announces "12 questions shown" rather than "12 notifications shown". A module hard-coded to its first caller's noun is the one thing a generalised module gets wrong in a way only a screen-reader user ever hears.

Warning — notification text is user-generated. Build rows with createElement and textContent, or clone a row already in the list. Never a template string or innerHTML.


Account menu ​

html
<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">FP</span>
    <span class="av-topbar__profile-meta" aria-hidden="true">
      <span class="av-topbar__profile-name">Florin Pinta</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 florin@…</li>
    <li role="none">
      <a class="av-dropdown__item" href="../apps/settings.html" 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="../auth/login.html" role="menuitem">
        Sign out
      </a>
    </li>
  </ul>
</div>

The name and role block is aria-hidden="true" and the button carries aria-label="Account menu". Both the avatar initials and the printed name would otherwise be read before the word that says what the control does — "FP Florin Pinta Administrator", and no menu mentioned.

role="menu" needs role="none" on the <li> wrappers, or the list's implicit listitem roles sit between the menu and its items and the whole structure stops being a menu.

Below 576px .av-topbar__profile-meta is hidden and the trigger is the avatar alone. The accessible name is on the button, so it survives that.

Important — this template signs out with a link because it is a static demo with no server. In a real application, sign-out is a <form method="post">, never <a href="/logout">. A GET logout can be fired by a prefetch, an <img> on a hostile page or a link scanner. It is a CSRF-adjacent bug that ships in a surprising number of admin templates.

html
<li role="none">
  <form method="post" action="/logout">
    <input type="hidden" name="_token" value="…">
    <button class="av-dropdown__item av-dropdown__item--danger" type="submit" role="menuitem">
      Sign out
    </button>
  </form>
</li>

Hooks and events ​

HookRead byWhat it does
data-av-sidebar-toggleinitShellOpens the off-canvas rail; keeps aria-expanded in step
data-av-palette-openinitPaletteOpens the command palette
data-av-paletteinitPaletteThe <dialog> itself
data-av-palette-statusinitPaletteLive region for the result count
data-av-theme-toggledelegated from documentFlips the resolved colour mode
data-av-tooltipdelegated from documentHover/focus label
data-av-dropdown-toggledelegated from documentOpens the menu that follows it
data-av-drawer-openinitDrawerSelector of the <dialog> to show
data-av-notificationsinitNotificationsThe wrapper holding trigger and panel
data-av-notif-*initNotifications, initNotifFiltersCount, filters and rows — see the table above
data-av-relative-timeinitRelativeTimeRewrites a <time> as "2w ago"; the datetime attribute is left alone
EventDetail
av:palette:open{}
av:palette:run{ item }
av:sidebar:togglethe sidebar's new state
av:theme:modethe resolved mode

There is no av:topbar:hide, no av:notifications:read and no av:palette:close. Subscribe with AdminVora.on(name, handler).


Checklist ​

  • [ ] <header> maps to the banner landmark
  • [ ] Every icon-only button has an aria-label that survives its text being hidden at narrow widths
  • [ ] The unread count is in the trigger's accessible name; the badge that repeats it is aria-hidden
  • [ ] One function writes every surface showing that count
  • [ ] The palette uses combobox semantics with aria-activedescendant, and focus never leaves the input
  • [ ] The result count reaches a live region — otherwise typing announces nothing
  • [ ] AdminVoraConfig is merged with Object.assign, never assigned over
  • [ ] Filter chips actually narrow the list and say how many rows survived
  • [ ] Notification content is built with textContent or cloned, never a template string
  • [ ] Sign-out is a POST form in any real deployment
  • [ ] .av-topbar__start keeps min-inline-size: 0

Read next: Page Header & Footer.

Documentation for @creativeigniter/adminvora