Appearance
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) endTwo 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>| Class | What it does |
|---|---|
.av-vitals | Takes the room between __start and __end and is a size container |
.av-vitals__entry | One list item. --secondary shows from a 27rem strip, --tertiary from 40rem |
.av-vitals__item | One 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, --danger | Border, number and meter turn together: a reading only draws a border when it needs attention |
.av-vitals__value | The number, in tabular figures so the pill does not jitter as it changes |
.av-vitals__meter | A small bar for a share of a whole; set --av-vitals-value from 0 to 100 |
.av-vitals__summary | Below 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.
| Requirement | How |
|---|---|
role="combobox" on the input | Authored in the partial |
aria-controls → the listbox id | aria-controls="avPaletteResults" |
aria-activedescendant = highlighted option id | Set 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 option | Rewritten across all options on every move |
| Focus trap, backdrop, Escape | Native <dialog> + showModal() |
| Focus restored on close | lastFocus 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
| Key | Action |
|---|---|
| Ctrl/⌘+K | Open, or close if already open |
| ↑ / ↓ | Move the highlight (wraps) |
| Enter | Run the highlighted item |
| Esc | Close, restore focus |
| Tab | Close — do not trap somebody who wanted to leave |
| Ctrl/⌘+1..9 | Run 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>| Attribute | Role |
|---|---|
data-av-notif-filter-group | The scope. Rows, headings, chips and the empty state are found inside it |
data-av-notif-filter | On a chip: all, unread, or a value matched against a row's kind |
data-av-notif-item | A filterable row |
data-av-notif-kind | What that row is, for the third filter type |
data-av-notif-group | A heading that hides when every row beneath it does |
data-av-notif-empty | Shown when nothing survived |
data-av-notif-noun | The 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
createElementandtextContent, or clone a row already in the list. Never a template string orinnerHTML.
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
| Hook | Read by | What it does |
|---|---|---|
data-av-sidebar-toggle | initShell | Opens the off-canvas rail; keeps aria-expanded in step |
data-av-palette-open | initPalette | Opens the command palette |
data-av-palette | initPalette | The <dialog> itself |
data-av-palette-status | initPalette | Live region for the result count |
data-av-theme-toggle | delegated from document | Flips the resolved colour mode |
data-av-tooltip | delegated from document | Hover/focus label |
data-av-dropdown-toggle | delegated from document | Opens the menu that follows it |
data-av-drawer-open | initDrawer | Selector of the <dialog> to show |
data-av-notifications | initNotifications | The wrapper holding trigger and panel |
data-av-notif-* | initNotifications, initNotifFilters | Count, filters and rows — see the table above |
data-av-relative-time | initRelativeTime | Rewrites a <time> as "2w ago"; the datetime attribute is left alone |
| Event | Detail |
|---|---|
av:palette:open | {} |
av:palette:run | { item } |
av:sidebar:toggle | the sidebar's new state |
av:theme:mode | the 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-labelthat 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
- [ ]
AdminVoraConfigis merged withObject.assign, never assigned over - [ ] Filter chips actually narrow the list and say how many rows survived
- [ ] Notification content is built with
textContentor cloned, never a template string - [ ] Sign-out is a POST form in any real deployment
- [ ]
.av-topbar__startkeepsmin-inline-size: 0
Read next: Page Header & Footer.