Appearance
Feedback & Overlays
Alerts, banners, toasts, dialogs, drawers, tooltips, and the rules for choosing between them.
The live reference for everything on this page is html/pages/ui/feedback.html, which renders each of these next to the markup that produced it. Press the buttons — the toasts, dialogs, drawers and banners there are the real components, not screenshots.
Choosing the right pattern
Is it a response to something the user just did?
├─ Yes → Does it need a decision?
│ ├─ Yes, and it is destructive/irreversible → Confirm dialog
│ ├─ Yes, and it needs input → Modal
│ └─ No → Toast
└─ No → Is it about the page's content?
├─ Yes → Inline alert
└─ No → Banner (application-wide)| Pattern | Interrupts | Persists | Use |
|---|---|---|---|
| Toast | No | 5s, or 8s with an action | "Saved", "Copied", "3 items deleted" |
| Inline alert | No | Until dismissed/resolved | "This order is on hold" |
| Banner | No | Until dismissed, and the dismissal is remembered | "Maintenance at 02:00 UTC" |
| Confirm | Yes | Until answered | "Delete 24 orders?" |
| Modal | Yes | Until closed | Editing a record, a focused sub-task |
| Drawer | Partly | Until closed | Filters, details, settings |
The line between an alert and a banner is not size, it is subject. An alert speaks about the thing next to it; a banner speaks about the whole application. That is why a banner spans the shell and remembers being dismissed, and why .av-alert deliberately has no dismissal memory — an inline alert describes state the page can re-derive on the next render.
Important — never use a modal for something the user did not initiate. A modal that appears on page load is the most-hated pattern in software.
Alerts
html
<div class="av-alert av-alert--warning-soft" role="alert">
<svg class="av-icon av-alert__icon" aria-hidden="true" viewBox="0 0 24 24">
<path d="M12 4l9 16H3l9-16z"/><path d="M12 10v4M12 17v.3"/>
</svg>
<div class="av-alert__body">
<h3 class="av-alert__title">Payment on hold</h3>
<p class="av-alert__text">
This order is awaiting fraud review. It ships automatically once cleared.
</p>
<div class="av-alert__actions">
<button class="av-btn av-btn--sm av-btn--soft-warning" type="button">Review now</button>
<button class="av-btn av-btn--sm av-btn--ghost" type="button">Dismiss</button>
</div>
</div>
<button class="av-close" type="button" 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>
</div>The title and the actions are both optional; a one-line alert is often the honest one. The close button is .av-close, shared with the toast and the dialog header — it is not a variant of .av-btn, because it carries no label and no padding of its own.
Parts
| Class | Role |
|---|---|
.av-alert | The flex container |
.av-alert__icon | Leading icon; takes the solid role colour so severity reads at a glance |
.av-alert__body | Grows, and carries min-inline-size: 0 so long content wraps instead of pushing |
.av-alert__title | Restates color: inherit, because the base :where(h1..h6) rule outranks the variant's inherited colour |
.av-alert__text | Body copy. A second __text is spaced from the pair, so a single paragraph is untouched |
.av-alert__actions | Trailing button row |
.av-close | The dismiss control |
Variants
Four roles, emitted from $status in abstracts/_variants.scss so a new role cannot be added to four components and forgotten in a fifth:
| Class | Use |
|---|---|
.av-alert--success-soft | Completed, confirmed |
.av-alert--warning-soft | Needs attention, not yet broken |
.av-alert--danger-soft | Failed, blocked |
.av-alert--info-soft | Neutral context |
There is no --primary-soft alert. Brand colour is not a severity, and an alert that carries it competes with the page's primary action for the same meaning.
Spacing modifiers
Page rhythm reaches only the direct children of the page body. An alert nested in a card body, a split pane or a plain <section> is outside it, so the gap is the author's to declare:
| Class | Use |
|---|---|
.av-alert--lead | An alert that introduces the block beneath it, inside a container the page rhythm does not reach |
.av-alert--inset | An alert in a container with no padding of its own, where every block supplies its own gutter |
Both were written as structural rules first and both were reverted, which is worth knowing before reaching for a third attempt. .av-alert + <block> has to name every block type that can follow an alert, and the one it forgets ships flush — the defect already on record for .av-field + .av-field. A blanket trailing margin is worse: it collapses harmlessly in block flow, but a parent that owns its gap through gap has nothing to collapse with, so it adds to it, and three stacked examples went from 16px to 32px the moment it compiled. A gap belongs either to the container or to the author, and here the container cannot know.
What makes the modifier reliable is not the modifier. tests/pages.mjs measures the rendered gap under every alert on every page and fails on a flush one, so forgetting it is a failing gate rather than a shipped page.
Links inside an alert
.av-alert__body a inherits the role's -text step and carries an underline. It does not keep the default link hue, and the reason is measured: the link colour is contrast-checked against the page surface, and an alert paints its own subtle fill underneath, so a link keeping its own hue lands on a ground nobody measured it against. tests/a11y.mjs caught exactly that — 0 → 1 violations — on the first alert in the product to contain a link. The underline carries the affordance the hue used to.
Roles
| Role | Use |
|---|---|
role="alert" | Errors and warnings — interrupts the screen reader immediately |
role="status" | Success and info — announced at the next pause |
| No role | An alert rendered with the page rather than inserted later |
Overusing role="alert" is a real accessibility problem: it interrupts whatever the user is reading. An alert that was in the HTML the server sent has already been read in document order and needs no role at all.
Banners
An application-wide notice that spans the shell. Dismissal is remembered in localStorage, keyed by the banner's own id, so two banners never share a dismissal — and one without an id is simply not persisted rather than silently sharing a key.
html
<div class="av-banner av-banner--warning" id="trial-ending">
<svg class="av-banner__icon" aria-hidden="true" viewBox="0 0 24 24" fill="none"
stroke="currentColor" stroke-width="2">
<circle cx="12" cy="12" r="9"/><path d="M12 8v5M12 16h.01"/>
</svg>
<div class="av-banner__body">
<span class="av-banner__title">Your trial ends in 5 days.</span>
Add a payment method to keep your projects active.
</div>
<div class="av-banner__actions">
<button class="av-btn av-btn--sm av-btn--primary" type="button">Add payment</button>
<button class="av-btn av-btn--sm av-btn--ghost" type="button"
data-av-banner-dismiss aria-label="Dismiss notice">Dismiss</button>
</div>
</div>| Class | Role |
|---|---|
.av-banner--info · --success · --warning · --danger | Tint the accent and the ground from the same token pair, so the icon and the wash can never disagree about severity |
.av-banner--sticky | Opt-in pinning. A banner pinned above a long form eats vertical space for the whole session, which is a worse trade than scrolling past it once |
data-av-banner-dismiss hides the banner, records the id, and announces "Notice dismissed." through the shared live region. A page-level notice that returns on every navigation is the fastest way to teach someone to stop reading banners.
Toasts
js
AdminVora.toast.success('Order #1042 saved');
AdminVora.toast.error('Could not save order'); // renders as type "danger"
AdminVora.toast.warning('Stock is low');
AdminVora.toast.info('Report is generating');
AdminVora.toast.show({
type: 'success',
title: 'Order archived',
message: 'Order #1042 moved to archive.',
duration: 8000,
action: { label: 'Undo', run: () => restoreOrder(1042) },
dismissible: true
});
AdminVora.toast.dismissAll();action is an object, not a string. { label, run } — the label names the button and run is called when it is pressed. Passing a bare string renders a button with no accessible name: 'Undo'.label is undefined, the template escapes it to an empty string, and what ships is a nameless control inside a message that disappears. It is the same defect tests/buttons.mjs exists to catch on confirm dialogs, one component along.
The icon is derived from type, and there are four.
Several toasts stack. At rest every toast but the newest tucks behind it with a sliver showing, so four messages take one toast's height; moving the pointer or focus into the stack fans them out to read. Up to four are kept. A toast's timer pauses on hover, on focus, and while the tab is hidden, and resumes with the time it had left, so a message is never dismissed while nobody could see it.
From markup
A button can raise a toast without any JavaScript of your own. A delegated listener on document reads four attributes, and data-av-toast carries the type, not the words:
html
<button class="av-btn av-btn--outline" type="button"
data-av-toast="success"
data-av-toast-title="Receipt sent"
data-av-toast-message="A copy of INV-2026-1042 went to sarah@northwind.io"
data-av-toast-action="Undo">
Send receipt
</button>| Attribute | Value |
|---|---|
data-av-toast | success, danger, warning or info — the type, and required |
data-av-toast-title | Optional heading |
data-av-toast-message | Optional body |
data-av-toast-action | Optional label for a single action button |
The markup hook carries a label but no behaviour: pressing the action raises a second toast reading "Restored", because a static demo has nothing to undo. In your own application, call AdminVora.toast.show() with a real run rather than reaching for the attribute.
Putting the sentence in data-av-toast is the mistake to avoid: nothing throws, the listener still fires, and the toast opens with no title, no message and a broken class name, because the sentence became the type. npm run test:pages fails on any value that is not one of the four.
The live region
Two regions are created lazily, on first use, and appended to <body>:
html
<div class="av-toast-region" role="region"
aria-label="Notifications" aria-live="polite" aria-atomic="false"></div>
<div class="av-toast-region" role="region"
aria-label="Errors" aria-live="assertive" aria-atomic="false"></div>type: 'danger' goes to the assertive region so an error interrupts; everything else is polite.
.av-toast-region sets pointer-events: none with auto on its children, so the empty area of the region never blocks clicks on the page beneath it. Below 576px the region spans the viewport and sits above the safe-area inset.
Rules
| Rule | Enforced by |
|---|---|
| Maximum 4 visible; older ones are hidden | MAX = 4 in the module |
| Never auto-dismiss a toast with an action under 8 seconds | Math.max(duration, 8000) when an action is present (WCAG 2.2.1) |
| Pause the timer on hover and on focus | mouseenter/mouseleave, focusin/focusout |
| Never stack duplicates — increment a counter instead | dedupe, on by default |
| Never put critical information only in a toast | Your judgement. It disappears, and the reader may have been looking elsewhere |
| Errors that need action go in an inline alert, not a toast | Your judgement |
Deduplication keys on type, title and message together, so "Saved" as a success and "Saved" as a warning are two toasts rather than a count of two. A repeat resets the timer and reveals .av-toast__count.
Reduced motion collapses the exit animation, so removal is also guaranteed by a timeout rather than by animationend alone — a toast that waits for an animation that never plays never leaves.
Confirm dialog
html
<button class="av-btn av-btn--outline-danger" type="button"
data-av-confirm
data-av-confirm-title="Delete order #1042?"
data-av-confirm-text="This permanently removes the order and its history. This cannot be undone."
data-av-confirm-accept="Delete order"
data-av-confirm-cancel="Keep order"
data-av-confirm-variant="danger">
Delete
</button>| Attribute | Default |
|---|---|
data-av-confirm | Required — the marker itself |
data-av-confirm-title | Are you sure? |
data-av-confirm-text | (none) |
data-av-confirm-accept | Confirm |
data-av-confirm-cancel | Cancel |
data-av-confirm-variant | danger |
data-av-confirm-require-input | (none) — the string that must be typed to enable the accept button |
The attribute is data-av-confirm-require-input, not data-av-confirm-type. That misspelling shipped on three irreversible actions, so the type-to-confirm step never once ran; check:hooks fails the build on any data-av-* in markup that nothing reads.
What happens on "yes". The click is cancelled before the dialog opens, so nothing happens while the question is on screen. After the accept button:
- a submit button submits its form with
form.requestSubmit(button), so the button's ownname/valueis sent and validation runs. A delete button outside its form works through the nativeform="delete-form"attribute; - a link (
<a href>) is followed; - the element dispatches
av:confirm:proceed(bubbling), for anything else:
html
<form id="delete-form" method="post" action="/orders/1042/delete"></form>
<button class="av-btn av-btn--outline-danger" type="submit" form="delete-form"
data-av-confirm data-av-confirm-title="Delete order #1042?" data-av-confirm-accept="Delete order">
Delete
</button>js
document.querySelector('#revoke').addEventListener('av:confirm:proceed', async () => {
const res = await fetch('/api/keys/42', { method: 'DELETE' });
AdminVora.toast.show(res.ok
? { type: 'success', message: 'Key revoked' }
: { type: 'danger', message: 'The key could not be revoked' });
});The runtime raises no toast of its own: whether the action worked is the server's answer.
The hook resolves to a boolean; issuing the request is the application's job — await AdminVora.confirm() and call fetch yourself.
focusCancel is a JavaScript option with no attribute, deliberately. Moving initial focus onto a destructive button is not a thing markup should be able to do in passing.
Those defaults were unreachable for most of this product's life, and the reason is worth knowing.
confirm()merged them with{ cancel: 'Cancel', ...opts }, and the delegated handler buildsoptsout ofdataset, so an attribute the author did not write arrived as an explicitundefined— which a spread copies straight over the default, because the key exists in the object. A destructuring default would have applied. Twenty of the twenty-three confirm dialogs in the demo shipped with a blank Cancel button: the safe choice in a destructive dialog, focused by default, announced as "button" with no name.withDefaults()drops undefined keys now, in one place rather than with??at each of the eight sites that read one, andnpm run test:buttonsopens every confirm dialog inhtml/pages/and requires each of its buttons to have a name.
js
const ok = await AdminVora.confirm({
title: 'Delete 24 orders?',
text: 'This permanently removes 24 orders. This cannot be undone.',
accept: 'Delete 24 orders',
cancel: 'Cancel',
variant: 'danger',
requireInput: 'DELETE' // must be typed to enable the accept button
});
if (ok) await bulkDelete(ids);| Detail | Why |
|---|---|
| The accept label repeats the verb and the object | Users click "OK" without reading |
| The text states the consequence | "This cannot be undone" |
| Cancel receives initial focus | An accidental Enter must not destroy data |
| Esc cancels | Native <dialog> |
requireInput for high-stakes actions | Typing "DELETE" forces engagement |
| Focus restored to the trigger on close | Native <dialog> |
requireInput moves initial focus to the field rather than to Cancel — a dialog that focuses Cancel when the next step is typing makes the reader hunt for a control the dialog just told them to use.
The accept button is neutered with aria-disabled, never the disabled property: it is the whole reason the dialog opened, and disabled drops it out of the tab order, so someone reading with the keyboard never learns it is there or why it will not act. The click is stopped by initActions's capture-phase guard on document, which already owns that rule for the whole product — a second guard inside the dialog would be a second writer for it. A bare aria-disabled with no enforcing guard is worse than disabled, because then nothing stops the click either.
For reversible actions, prefer the undo toast — it is faster and less annoying:
js
row.hidden = true;
const commit = setTimeout(() => fetch(url, { method: 'DELETE' }), 8000);
AdminVora.toast.show({
message: 'Order archived',
duration: 8000,
action: { label: 'Undo', run: () => { clearTimeout(commit); row.hidden = false; } }
});Modal
A modal is a native <dialog> opened with showModal(). That one decision supplies the focus trap, Esc, inerting of the page behind it and focus restore on close — four things that are individually easy to get almost right, and collectively the reason most hand-rolled modals are broken for keyboard users.
html
<button class="av-btn av-btn--outline" type="button" data-av-modal-open="#inviteDialog">
Invite a teammate
</button>
<dialog class="av-dialog" id="inviteDialog" aria-labelledby="inviteTitle">
<div class="av-dialog__inner">
<div class="av-dialog__header">
<h2 class="av-dialog__title" id="inviteTitle">Invite a teammate</h2>
<button class="av-close" type="button" data-av-modal-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>
</div>
<div class="av-dialog__body">
<div class="av-field">
<label class="av-field__label" for="inviteEmail">Email address</label>
<input class="av-input" type="email" id="inviteEmail" placeholder="you@company.com">
</div>
</div>
<div class="av-dialog__footer">
<button class="av-btn av-btn--ghost" type="button" data-av-modal-close>Cancel</button>
<button class="av-btn av-btn--primary" type="submit">Send invite</button>
</div>
</div>
</dialog>| Hook | Effect |
|---|---|
data-av-modal-open="<selector>" | Calls showModal() on the match, emits av:modal:show, and focuses its first input, textarea or select |
data-av-modal-close | Closes the nearest ancestor <dialog>, playing the exit animation |
Both are delegated from document, so a dialog inserted later works with no re-scan. Clicking the backdrop closes the dialog too: the backdrop is a pseudo-element and cannot be an event target, so the click lands on the <dialog> itself, and e.target === dlg is what separates it from a click on the panel.
Sizes
| Size | Class | Inline size |
|---|---|---|
| Small | .av-dialog--sm | min(400px, 100vw − 2rem) |
| Default | — | min(520px, 100vw − 2rem) |
| Large | .av-dialog--lg | min(800px, 100vw − 2rem) |
There is no extra-large or full-screen dialog. A dialog that fills the viewport is a page, and a page has a URL, a title and a back button that a dialog cannot give it.
Scrolling needs no modifier. .av-dialog is capped at min(85dvh, 720px), .av-dialog__inner inherits that cap as a flex column, and .av-dialog__body takes overflow-y: auto — so the header and footer stay put and the body scrolls, for every dialog, without anyone remembering to ask. dvh rather than vh, because on mobile Safari the URL bar changes the viewport and a dialog sized in vh is cut off by exactly that difference.
Parts
| Class | Role |
|---|---|
.av-dialog__inner | Flex column that inherits the height cap |
.av-dialog__header · __title · __body · __footer | The four regions |
.av-dialog__icon | The 44px round badge in a confirm dialog; --primary and --warning retint it |
.av-dialog restores margin: auto explicitly, because the reset's * { margin: 0 } kills the UA rule that centres a <dialog> — the one line without which every modal in the product sits in the top-left corner.
Rules
| Rule | Reason |
|---|---|
| Never open a modal on page load | |
| Never nest modals | Stacked focus traps are unrecoverable |
| Modals with forms should warn on dismiss if dirty | |
| Focus the first input, or the primary button if there is none | The open handler does the first half |
| Maximum one primary action |
Dirty-checking hangs off the native cancel event, which fires for Esc before the dialog closes:
js
dialog.addEventListener('cancel', async (e) => {
if (!isDirty(form)) return;
e.preventDefault();
const discard = await AdminVora.confirm({
title: 'Discard changes?',
accept: 'Discard',
variant: 'danger'
});
if (discard) { form.reset(); dialog.close(); }
});Preventing cancel is also what lets an exit animation play at all: the default yanks the element out of the top layer immediately, so the panel vanishes mid-slide.
Drawer and bottom sheet
Covered in Page Header & Footer.
Choose a drawer over a modal when:
- The content is a filter panel, detail view, or settings — things the user returns to
- The user needs to see the page context behind it
- The content is tall and list-like
Choose a modal when the task must be completed or abandoned before continuing.
The bottom sheet is .av-sheet, its own component — not a .av-drawer modifier. Changing the axis changes everything below it: the size is capped by viewport height rather than width, it rounds only its leading corners, and it carries a grab handle a side drawer has no use for. A modifier that rewrites six declarations is a second component wearing the first one's name.
The handle is aria-hidden decoration. A drag affordance that is the only way out is unusable by keyboard, so Esc, the backdrop and the close button all work.
Tooltips
A tooltip supplements a name; it never replaces one. Every icon-only control gets one without any extra markup: a button, link or role="button" whose name is an aria-label and which shows no text of its own displays that label as its tooltip. A name held in an .av-visually-hidden span inside the control counts too.
html
<!-- No tooltip markup: the label is the tooltip -->
<button class="av-btn av-btn--ghost av-btn--icon" type="button" aria-label="Recalculate totals">
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M4 12a8 8 0 1 0 2.6-5.9"/><path d="M4 4v4h4"/></svg>
</button>
<!-- Extra information that is not the name becomes the description -->
<button class="av-btn av-btn--outline" type="button"
data-av-tooltip="Exports the current filter, not the whole table">Export</button>
<!-- A real keyboard shortcut is drawn as keys after the label -->
<button class="av-btn av-btn--ghost av-btn--icon" type="button" aria-label="Search"
aria-keyshortcuts="Control+K Meta+K" data-av-palette-open>
<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>
</button>
<!-- Opt out, on the control or on a region that draws its own -->
<div data-av-tooltip="off"><!-- a map that draws its own --></div>| Attribute | Meaning |
|---|---|
data-av-tooltip="text" | Shows text. If it differs from the control's name, the bubble is linked with aria-describedby while it is open; if it matches, the bubble is aria-hidden so the name is not announced twice. |
data-av-tooltip="off" | No tooltip for this element or anything inside it. |
aria-keyshortcuts | Drawn as keys. Of space-separated alternatives, a Mac shows the Meta one and other systems the first without Meta. Only declare a shortcut the page really handles. |
title | An icon-only control with a title is left to the browser's own bubble. |
How it behaves:
- A pointer waits 400 ms before the first tooltip opens. After one has shown, neighbours open at once for a short spell, so running along a toolbar reads as one gesture.
- Keyboard focus opens it immediately; a mouse click that focuses the control does not.
- The pointer can move onto the bubble without it closing (WCAG 1.4.13). Esc, a click, a scroll or a resize closes it.
- A touch never opens one: on a phone the press is the action.
- The text is read when the bubble opens and watched while it is open, so a Play button that becomes Pause says so. Nothing is cached on the element, which makes it safe on markup a framework re-renders.
- It sits above the control, flips below when there is no room, and slides sideways to stay on screen. Under reduced motion it fades without moving.
- A native
disabledbutton fires no pointer events, so it is skipped and a wrapper'sdata-av-tooltipis used instead (see disabled buttons).
Progress
html
<!-- Determinate -->
<div class="av-channel">
<div class="av-channel__row">
<span class="av-channel__name">Upload</span>
<span class="av-channel__value">68%</span>
</div>
<div class="av-progress" role="progressbar" aria-valuenow="68"
aria-valuemin="0" aria-valuemax="100" aria-label="Upload progress">
<div class="av-progress__bar" style="inline-size: 68%"></div>
</div>
</div>
<!-- Indeterminate: no aria-valuenow, because there is no value -->
<div class="av-progress av-progress--indeterminate" role="progressbar" aria-label="Indexing">
<div class="av-progress__bar"></div>
</div>
<!-- Circular -->
<div class="av-progress-ring" style="--av-ring-value: 68" role="progressbar"
aria-valuenow="68" aria-valuemin="0" aria-valuemax="100" aria-label="Storage used">
<svg viewBox="0 0 44 44" aria-hidden="true">
<circle class="av-progress-ring__track" cx="22" cy="22" r="20"></circle>
<circle class="av-progress-ring__fill" cx="22" cy="22" r="20"></circle>
</svg>
<span class="av-progress-ring__label">68%</span>
</div>There is no progress module. The ring is CSS reading one custom property — --av-ring-value, a number from 0 to 100 — and .av-progress__bar takes its width from inline-size.
--av-ring-value in a style= attribute is a value, not a declaration, which is the line this repository draws: carrying data a component is designed to read is fine, restating declarations the class already makes is not.
| Custom property | Default | Effect |
|---|---|---|
--av-ring-size | 56px | Outer box; the SVG scales to fill it, so the viewBox stays 0 0 44 44 |
--av-ring-width | 5px | Stroke width of both circles |
--av-ring-value | 0 | 0–100; drives stroke-dashoffset against a 125.6 dasharray (2πr, r = 20) |
.av-channel is the label row above a bar — name on one side, value on the other, tabular-nums so a changing percentage does not shuffle its own digits.
Both the indeterminate sweep and the fill gradient are physical rather than logical: translate has no logical form, and 90deg points at the inline end in LTR and the inline start in RTL. Each carries its direction in a custom property that the [dir="rtl"] rule flips (--av-progress-flow), rather than duplicating keyframes. A progress indicator travelling backwards through the reading direction is the one place the ambiguity is unacceptable.
Progress bars over 3 seconds must show a percentage or an estimate. A bar with no number is worse than a spinner, because it implies information it does not provide.
Skeleton
html
<div class="av-card" aria-busy="true">
<div class="av-card__body">
<div class="av-demo-row" style="margin-block-end: var(--av-space-3)">
<div class="av-skeleton av-skeleton--circle" style="--size: 40px"></div>
<div style="flex: 1">
<div class="av-skeleton" style="--size: 40%; margin-block-end: 6px"></div>
<div class="av-skeleton" style="--size: 62%; block-size: 16px"></div>
</div>
</div>
<div class="av-skeleton" style="margin-block-end: 8px"></div>
<div class="av-skeleton" style="--size: 80%"></div>
</div>
</div>| Class / property | Effect |
|---|---|
.av-skeleton | 12px shimmer bar; --size sets the inline size, default 100% |
.av-skeleton--circle | --size becomes both dimensions, fully rounded, flex: none |
There is no --card, --text or --title modifier: a skeleton is a rectangle of a given size, and naming rectangles after the screens that first used them is how a component ends up with nine modifiers and no shape.
The skeleton must match the real content's shape — same avatar size, same line count, same widths. A mismatched skeleton causes a jarring shift on load, which is worse than no skeleton. Wrap it in aria-busy="true" so assistive technology knows the region is not final.
Tour
A guided walk across a screen: one card moves from element to element, with a ring on the one it is describing. You declare each step on the element it describes, so a step that is hidden or removed drops out of the walk.
html
<button class="av-btn av-btn--outline" type="button" data-av-tour-start="welcome">Take the tour</button>
<div class="av-card"
data-av-tour="welcome" data-av-tour-order="1" data-av-tour-title="Your figures"
data-av-tour-text="The four numbers this dashboard is about.">
<div class="av-card__body">Revenue, users, orders and conversion.</div>
</div>
<div class="av-card"
data-av-tour="welcome" data-av-tour-order="2" data-av-tour-title="Recent orders"
data-av-tour-text="The latest five, across every channel.">
<div class="av-card__body">Orders appear here as they arrive.</div>
</div>| Attribute | On | What it does |
|---|---|---|
data-av-tour-start | a button | Starts the tour of that name |
data-av-tour | each step's element | The tour the step belongs to |
data-av-tour-order | each step's element | The step's place in the walk |
data-av-tour-title, data-av-tour-text | each step's element | What the card says |
The card is a labelled dialog and takes focus at each step. Escape or Skip ends the tour and focus returns to the button that started it. The page is not dimmed: the ring is what marks the element. The runtime raises av:tour:start, av:tour:step (with index and target) and av:tour:end, each carrying the tour's name.
js
AdminVora.on('av:tour:end', ({ name }) => {
localStorage.setItem(`tour.${name}`, 'seen');
});The card's own words (Skip, Back, Next, Done and the step count) are English and are not configurable yet.
Empty and error states
Covered with full markup in Page Header & Footer.
The two rules worth repeating:
- An empty state without an action is a dead end. Always show the next step.
- "No items yet" and "No items match your filter" are different messages. Showing the first to someone with 5,000 records who made a typo is a bug.
Options
AdminVora.toast.show(options)
| Option | Default | Description |
|---|---|---|
type | 'info' | success · danger · warning · info. danger routes to the assertive region |
title | (none) | Optional heading |
message | (none) | Body text |
duration | 5000, or 8000 with an action | ms; 0 persists. An action raises anything below 8000 |
action | null | { label, run } — an object, never a string |
dismissible | true | Renders the close button |
dedupe | true | Collapses an identical type+title+message into a counter |
A string may be passed instead of the object, and becomes message.
The region is fixed at the bottom inline-end, the cap is 4, the timer always pauses on hover and focus, and the icon comes from the type.
AdminVora.confirm(options)
| Option | Default |
|---|---|
title | 'Are you sure?' |
text | '' |
accept | 'Confirm' |
cancel | 'Cancel' |
variant | 'danger' |
focusCancel | true — ignored when requireInput is set |
requireInput | null |
variant selects both the icon badge and the accept button: danger gives a danger badge and a danger button, anything else gives an info badge and a primary button.
Returns a Promise<boolean>.
Events
| Event | Detail |
|---|---|
av:toast:show | { id, type, message } |
av:toast:hide | { id } |
av:confirm:accept / av:confirm:cancel | { options } — the resolved options, after defaults |
av:modal:show | { el } |
av:modal:hidden | { el } |
The drawer and the banner emit no events. Listen for the native <dialog> close event on a drawer panel instead.
Accessibility checklist
- [ ]
role="alert"only for errors/warnings;role="status"for success/info; no role on an alert the server rendered - [ ] Toast regions are labelled live regions;
dangeruses the separate assertive one - [ ] Toast timers pause on hover and focus
- [ ] A toast action is
{ label, run }, so its button has a name - [ ] Dialogs have
aria-labelledbypointing at the title - [ ] Confirm dialogs focus Cancel by default, and the accept button uses
aria-disabled, neverdisabled - [ ] Progress bars have
role="progressbar"with all threearia-value*and a label - [ ] Indeterminate progress omits
aria-valuenow - [ ] Skeletons are inside
aria-busy="true"containers - [ ] No modals on page load; no nested modals
- [ ] Esc closes every overlay, and
cancelis prevented wherever an exit animation plays - [ ] Every icon-only control has an
aria-label, which is also its tooltip; nothing relies on a tooltip for its name
Read next: Data Display.