Appearance
Page Header & Footer
The per-page header (breadcrumb, title, actions), the drawer and bottom sheet, the app footer, and the states a page shows when it has nothing to show.
This page describes what ships. Where the earlier specification promised something that was never built — a sticky header variant, a breadcrumb generated from the menu schema, a footer link bar — that is said plainly rather than left as a sample a reader would paste and watch do nothing.
Page header
Every content page opens with the same four parts, in the same order: breadcrumb, <h1>, an optional subtitle, and the actions that apply to the whole page. Eighty-one pages use it unchanged.
html
<div class="av-page-header">
<div>
<ol class="av-breadcrumb" aria-label="Breadcrumb">
<li><a href="../../index.html">Home</a></li>
<li>Account</li>
<li aria-current="page">API keys</li>
</ol>
<h1 class="av-page-header__title">API keys</h1>
<p class="av-page-header__subtitle">
Four live keys. Rotating a key keeps the old one working for 24 hours.
</p>
</div>
<div class="av-page-header__actions">
<a class="av-btn av-btn--outline" href="security.html">Security log</a>
<button class="av-btn av-btn--primary" type="button" data-av-modal-open="#newKey">
<svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24">
<path d="M12 5v14M5 12h14"/>
</svg>
Create key
</button>
</div>
</div>The wrapper around the first three is a plain <div>. It exists only to make the header a two-item flex row and carries no class, because a class with one declaration in it is a name to maintain for nothing.
scss
@layer components {
.av-page-header {
display: flex;
align-items: flex-end;
justify-content: space-between;
flex-wrap: wrap;
gap: var(--av-space-4);
margin-block-end: var(--av-space-6);
}
.av-page-header__title {
font-size: var(--av-font-size-2xl);
font-weight: var(--av-font-weight-bold);
letter-spacing: -0.015em;
margin: 0;
}
.av-page-header__subtitle {
font-size: var(--av-font-size-sm);
color: var(--av-text-muted);
margin: var(--av-space-2) 0 0;
}
/* Wraps because a detail page can carry three actions and a narrow viewport
would otherwise push the last one past the edge. */
.av-page-header__actions { display: flex; flex-wrap: wrap; gap: var(--av-space-2); }
}align-items: flex-end is what keeps the primary action level with the title however tall the left column grows, and flex-wrap on the header itself is what moves the whole action group onto its own line rather than compressing the title.
Both the actions and the breadcrumb are removed when the page is printed (src/scss/utilities/_print.scss): neither survives the transfer to paper, where there is nothing to click and no navigation to be positioned in.
Rules
| Rule | Reason |
|---|---|
Exactly one <h1> per page, and it is .av-page-header__title | Document outline and screen-reader page identification. tests/pages.mjs fails the build on a second one. |
The breadcrumb is an <ol class="av-breadcrumb"> with its own aria-label | An ordered list is the correct semantics, and the label is what distinguishes it from every other list on the page. |
The last crumb carries aria-current="page" and is not a link | It goes nowhere. A link to the page you are already on is a dead control. |
No earlier crumb claims aria-current | Two "current" items describe an impossible position. |
| Maximum two page-level actions | A third belongs in the toolbar beside the thing it acts on, or in an overflow menu. |
| The primary action is the last one (LTR) | Convention, and the shortest travel from the page's own scroll position. |
| The subtitle carries data, not decoration | "Four live keys. Rotating a key keeps the old one working for 24 hours." beats "Manage your API keys". |
The four breadcrumb rules are enforced by npm run check:breadcrumbs, which is in the lint chain. It reads html/_src and html/_partials and holds all 83 breadcrumbs to them. The rules were written down long before anything checked them, which is exactly how a page ships with its final crumb still linked to itself.
The UI-kit demonstration is deliberately not an <h1>
html/_src/ui-layout.html shows a page header inside a section of a page that already has its own <h1>. Its title is a <p class="av-page-header__title">, because a demonstration of a heading must not become a second real heading — the class supplies the appearance and the element supplies the outline, and only one of those is being demonstrated.
Not built
| Promised | State |
|---|---|
.av-page-header--sticky, .is-stuck and an IntersectionObserver sentinel | No such rule and no such script. A sticky page header has never shipped. |
.av-page-header__main, .av-page-header__title-row | Never existed. The wrapper is an unclassed <div>; a badge beside the title is a sibling of the <h1> inside it. |
src/js/utils/breadcrumb.js, generating the trail from the menu schema | No such file. Every breadcrumb is written in the page's own markup, which is why the gate above reads markup rather than a data structure. |
Drawer and bottom sheet
A drawer is a native <dialog> opened with showModal(). That is where the focus trap, Esc, the inerting of the rest of the page and the focus restore come from — four things that are easy to reimplement and easy to get subtly wrong. The component adds only where it sits and how it arrives.
html
<button class="av-btn av-btn--ghost av-btn--icon" type="button"
data-av-drawer-open="#avNotifDrawer"
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>
</button>
<dialog class="av-drawer" id="avNotifDrawer" aria-labelledby="avNotifDrawerTitle">
<div class="av-drawer__inner">
<div class="av-drawer__header">
<h2 class="av-drawer__title" id="avNotifDrawerTitle">Notifications</h2>
<button class="av-btn av-btn--ghost av-btn--icon" 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="M18 6 6 18M6 6l12 12"/>
</svg>
</button>
</div>
<div class="av-drawer__body">…</div>
<div class="av-drawer__footer">
<button class="av-btn av-btn--ghost" type="button" data-av-drawer-close>Close</button>
<button class="av-btn av-btn--primary" type="button">Apply</button>
</div>
</div>
</dialog>There is no role, no aria-modal and no hidden attribute to write. <dialog> supplies all three, and showModal() is what makes aria-modal true. The only ARIA the author owns is aria-labelledby pointing at the drawer's own title, and aria-haspopup="dialog" on the trigger.
Hooks
| Hook | Read by | Effect |
|---|---|---|
data-av-drawer-open="<selector>" | initDrawer | Clicking calls showModal() on the panel it names. |
data-av-drawer-close | initDrawer | Clicking runs the closing animation, then close(). |
Sizes and edges
| Class | Result |
|---|---|
.av-drawer | 26rem, pinned to the inline end — the right edge in English, the left in Arabic, with no mirrored rule. |
.av-drawer--wide | 30rem. For a drawer with an interior of its own: the messages panel puts a conversation rail beside a thread, and at 26rem the thread that is left is narrower than its own bubbles. |
.av-drawer--start | Pinned to the inline start instead. |
.av-sheet | The same dialog anchored to the block end: full width, capped at 85dvh, rounded on its leading corners, with a decorative grab handle. |
Width travels as --av-drawer-size rather than being restated per modifier, so the viewport clamp — min(var(--av-drawer-size), calc(100vw - var(--av-space-8))) — stays in one place. That is the half that matters at 320px.
The sheet is a separate component rather than a drawer modifier because changing the axis changes everything below it: the size is capped by viewport height rather than width, only the leading corners round, and it carries a handle a side drawer has no use for. The handle is aria-hidden, because a drag affordance that is the only way out is unusable by keyboard.
The three things initDrawer has to get right
js
const close = (panel) => {
if (!panel.open) return;
const ms = (parseFloat(getComputedStyle(panel).animationDuration) || 0) * 1000;
panel.classList.add('is-closing');
setTimeout(() => {
panel.classList.remove('is-closing');
// `isConnected` because a router can swap the panel away inside the
// delay, and close() on a detached dialog throws.
if (panel.isConnected && panel.open) panel.close();
}, ms);
};- The exit animation has to be waited out.
close()on a<dialog>is immediate, so the element vanishes mid-slide unless the call is deferred. The delay is read fromgetComputedStyle().animationDurationrather than hard-coded, so a reduced-motion preference that switches the animation off does not leave a drawer sitting open for a timeout that no longer matches anything. - Esc fires
cancelbefore the dialog closes. Preventing the default and routing throughclose()is what lets the exit animation play at all; the default removes the element from the top layer immediately. - A backdrop click lands on the
<dialog>itself.::backdropis a pseudo-element and cannot be an event target, soe.target === panelis true both for a click on the backdrop and for one on the panel's own padding. Telling them apart means comparing the pointer against the element's own box.
Direction
translate has no logical form, so the slide's direction travels as a custom property that the --start modifier and the RTL rule both flip — the same tactic the sidebar sweep and the auth panel use, and the one the directional-transform lint rule requires.
scss
.av-drawer { --av-drawer-from: 100%; }
.av-drawer--start { --av-drawer-from: -100%; }
[dir='rtl'] .av-drawer { --av-drawer-from: -100%; }
[dir='rtl'] .av-drawer--start { --av-drawer-from: 100%; }
@keyframes av-drawer-in { from { translate: var(--av-drawer-from) 0; } }
@keyframes av-drawer-out { to { translate: var(--av-drawer-from) 0; } }What ships in a drawer
Eight: notifications, messages (--wide), the cart, quick view (--wide), the data-grid filter panel (--wide), the category manager, and two demonstrations on the UI-kit layout page — one at each edge. One bottom sheet, on the feedback page.
The Customizer is not a drawer
The theme Customizer looks like one and is deliberately a different component: an <aside> with class="av-customizer", role="dialog", aria-modal="false" and hidden, opened and closed by initCustomizer through an is-open class and a CSS transition.
It has to be, because the whole point of it is watching the page change as you adjust a setting — which means it must not trap focus and must not inert the page behind it. A <dialog> opened with showModal() cannot be non-modal; that is the one thing the native element does not let you turn off. So the Customizer pays for its exception by reimplementing open, close, focus restore and Esc by hand.
It reuses one hook: its close button carries data-av-drawer-close, bound by initCustomizer itself rather than by initDrawer, which only ever scans .av-drawer, .av-sheet.
See Customizer for what its eight control groups write.
Footer
The footer is two spans.
html
<footer class="av-footer">
<span>© 2026 CreativeIgniter — AdminVora v1.0.0</span>
<span>Keys are shown once at creation — this list only ever shows the last four characters</span>
</footer>In html/_partials/shell-close.html both halves are build inputs: {{ version }} and {{ footnote }}.
scss
@layer components {
.av-footer {
grid-area: footer;
display: flex;
align-items: center;
justify-content: space-between;
gap: var(--av-space-4);
padding: var(--av-space-3) var(--av-content-padding);
border-block-start: 1px solid var(--av-border-subtle);
background: var(--av-surface-raised);
font-size: var(--av-font-size-xs);
color: var(--av-text-muted);
}
}Both inputs are single-writer by construction:
- The version comes from
package.json. It used to be the same string typed into two partials, the runtime and two documentation files, which is the printed-number-with-a-second-writer defect this codebase keeps re-learning. The two copies that cannot be templated — the runtime'sversionconstant and the docs site's version line — are held againstpackage.jsonbynpm run check:inventory, so releasing means editing one file and rebuilding. - The footnote is per page, declared in that page's own front matter in
html/_src. It is the sentence that belongs at the bottom of that screen: "An empty allowlist means every address is allowed — it is not a lockout", "Retained for 90 days, the same window as the security log". Pages with nothing specific to say fall back to a shared line.
The footer occupies the shell grid's footer area, so it sits below the scrolling content rather than inside it, and it is display: none in print.
Two shells exist: shell-close.html renders the footer, and shell-close-app.html omits it — an application screen that owns its own full-height layout (mail, chat, kanban, files) has no room for a footer and does not get one.
Not built
.av-footer__inner, __copy, __links, __version and a status-dot link to a status page were specified and never shipped. There is no .av-status-dot--success either; the shipped presence states are --online, --away, --busy and --offline.
Player bar
An audio player for apps that play sound: a music catalogue, podcasts, call recordings, voice notes. It docks as the last row of .av-main, under the footer, so it spans the content column whatever the sidebar is doing, and the page above it scrolls in the room that is left instead of hiding its last lines under the bar. It is markup and styles only: your app owns the <audio> element, plays and pauses it, and writes the state back (the play button's label and icon, aria-pressed on toggles, the two ranges' value and --av-range-fill). That keeps it framework-agnostic and safe to re-render.
html
<div class="av-main">
<header class="av-topbar">…</header>
<main class="av-content">…</main>
<footer class="av-footer">…</footer>
<div class="av-player" role="region" aria-label="Player">
<div class="av-player__inner">
<div class="av-player__media">
<span class="av-thumb"><img src="cover.jpg" alt=""></span>
<div class="av-player__text">
<span class="av-player__title">Night Drive</span>
<span class="av-player__subtitle">Nova Kade</span>
</div>
</div>
<div class="av-player__centre">
<div class="av-player__transport">
<button class="av-btn av-btn--ghost av-btn--icon av-btn--sm av-player__control av-player__control--step"
type="button" aria-label="Previous">…skip-back…</button>
<button class="av-btn av-btn--primary av-btn--icon" type="button" aria-label="Play">…media-play…</button>
<button class="av-btn av-btn--ghost av-btn--icon av-btn--sm av-player__control av-player__control--step"
type="button" aria-label="Next">…skip-forward…</button>
</div>
<div class="av-player__seek">
<span class="av-player__time">1:24</span>
<input class="av-range" type="range" name="seek" min="0" max="312" value="84" aria-label="Seek"
style="--av-range-fill: 27%">
<span class="av-player__time">5:12</span>
</div>
</div>
<div class="av-player__aside">
<button class="av-btn av-btn--ghost av-btn--icon av-btn--sm av-player__control" type="button"
aria-label="Mute">…volume…</button>
<input class="av-range av-player__volume" type="range" name="volume" min="0" max="100" value="80"
aria-label="Volume" style="--av-range-fill: 80%">
<button class="av-btn av-btn--ghost av-btn--icon av-btn--sm av-player__control" type="button"
aria-label="Close player">…close…</button>
</div>
</div>
</div>
</div>| Part | What it is |
|---|---|
.av-player | The bar. A size container named av-player; .is-minimised keeps only the media, play and the aside's buttons |
.av-player__media | Cover (an .av-thumb, 44px here) and two lines that truncate, so the bar never changes height |
.av-player__centre | Transport over the seek bar when the bar is at least 48rem wide; below that its children join the bar's own grid |
.av-player__control--step | Previous and next: hidden only when minimised |
.av-player__control--secondary | Shuffle, repeat, a queue button: shown only when the bar is at least 48rem wide |
.av-player__control[aria-pressed="true"] | A toggle that is on, in the primary colour |
.av-player__time | Tabular figures with room for 00:00, so the seek bar never shifts |
.av-player__aside | Volume and actions; shown from 48rem, and when minimised |
The icons media-play, media-pause, skip-back, skip-forward, repeat, shuffle, volume, volume-off and music are in the icon set for it. Give the seek range an aria-valuetext in words ("1 minute 24 seconds of 5 minutes 12 seconds"), because a screen reader otherwise reads raw seconds. Put the play button's state in its aria-label (Play or Pause), not in aria-pressed.
Below 48rem the bar has two rows: what is playing with previous, play and next beside it, then the seek bar across the full width. Volume hides there, since a phone has its own volume buttons.
Page states
Empty
html
<div class="av-empty" data-av-grid-empty hidden>
<span class="av-empty__icon">
<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>
</span>
<h2 class="av-empty__title">No accounts match your filter</h2>
<p class="av-empty__text">
Try a different search term, or clear the relationship filter to see all 14 accounts.
</p>
</div>.av-empty carries its own [hidden] rule, because an author display beats the UA's [hidden] at equal specificity and the flex column would otherwise keep the empty state on screen forever.
There is no single empty-state module. The element ships hidden and each list's own module owns its visibility through its own hook — data-av-grid-empty, data-av-cart-empty, data-av-notif-empty, data-av-cat-empty, data-av-file-empty, data-av-mail-empty, data-av-facet-empty, data-av-wishlist-empty, data-av-kanban-empty, data-av-moderation-empty. That is on purpose: the module that decides a list is empty is the only thing that knows why, and the copy differs accordingly.
Which is the point worth taking from the shipped examples — the message names the filter, not the feature. Showing "No products yet — add your first product" to someone who has 5,000 products and typed a typo is the most common version of this bug, and it is avoided by wording the empty state where the filtering happens rather than once in a shared component.
.av-empty has three elements: __icon, __title, __text. There is no __actions, no __details, no --compact and no --error modifier; an action below an empty state is a plain .av-btn sibling.
Loading
html
<div class="av-skeleton av-skeleton--circle" style="--size: 40px"></div>
<div class="av-skeleton" style="--size: 62%; block-size: 16px"></div>.av-skeleton is a shimmering bar that takes its width from --size and defaults to full width; --circle makes it a disc of that diameter. There is no --card modifier — a card skeleton is a stack of bars inside a real .av-card.
The shimmer animates background-position, so it costs no layout.
Error
A page-level error is not a variant of the empty state. It is .av-error, the component behind the six utility screens — 404, 403, 500, maintenance, offline and coming-soon — which are also the six pages tests/pages.mjs asserts must render without adminvora.js, because the case they exist for includes the bundle being what broke.
Read next: Responsive Strategy.