Appearance
Buttons & Actions
Variants
html
<!-- Solid — one primary action per view -->
<button class="av-btn av-btn--primary">Save changes</button>
<button class="av-btn">Secondary</button>
<button class="av-btn av-btn--soft-success">Approve</button>
<button class="av-btn av-btn--danger">Delete</button>
<!-- Outline — secondary actions -->
<button class="av-btn av-btn--outline">Cancel</button>
<button class="av-btn av-btn--outline-danger">Remove</button>
<!-- Soft — tertiary, low-emphasis, great in dense toolbars -->
<button class="av-btn av-btn--soft-primary">Filter</button>
<button class="av-btn av-btn--soft-danger">Archive</button>
<!-- Ghost — icon bars, table row actions -->
<button class="av-btn av-btn--ghost">Details</button>
<!-- Link — inline, in prose -->
<button class="av-btn av-btn--link">Learn more</button>scss
// src/scss/components/_button.scss
@layer components {
// Soft is the tertiary emphasis step: a tinted surface, no border.
// The role list lives in abstracts/_variants.scss, so adding a status role
// touches one file instead of being added to four components and forgotten
// in a fifth.
@each $role in $status-with-primary {
.av-btn--soft-#{$role} {
@include soft-surface($role, $bordered: false);
}
}
[class*="av-btn--soft-"]:hover { filter: brightness(0.96); }
[data-bs-theme="dark"] [class*="av-btn--soft-"]:hover { filter: brightness(1.25); }
.av-btn--ghost { background: transparent; color: var(--av-text-secondary); }
.av-btn--ghost:hover { background: var(--av-surface-sunken); color: var(--av-text-primary); }
}Dark mode brightens rather than darkens.
brightness(0.96)on a near-black tinted surface moves it towards the page background and the hover reads as nothing happening, so the dark rule inverts to1.25. One filter cannot serve both grounds.
Emphasis hierarchy
Solid ██████ One per view. The action the user came to perform.
Outline ▒▒▒▒▒▒ The alternative. Cancel, Back, secondary paths.
Soft ░░░░░░ Tertiary. Filters, toggles, bulk actions.
Ghost ······ Utility. Icon bars, row actions, close buttons.
Link ‾‾‾‾‾‾ Inline in text.Important — two solid buttons next to each other create a decision the user should not have to make. If both are equally important, neither is primary.
Sizes
html
<button class="av-btn av-btn--primary av-btn--sm">Small</button>
<button class="av-btn av-btn--primary">Default</button>
<button class="av-btn av-btn--primary av-btn--lg">Large</button>| Size | Height (comfortable) | Font | Padding-x | Use |
|---|---|---|---|---|
av-btn--sm | 32px (--av-control-sm) | 12px | 12px | Table rows, toolbars, chips |
| default | 40px (--av-control-md) | 14px | 24px | Everywhere |
av-btn--lg | 48px (--av-control-lg) | 16px | 24px | Auth screens, primary CTAs, mobile |
Buttons and fields share one height scale. --av-control-2xs to --av-control-lg are 24, 28, 32, 40 and 48px, and inputs, selects and Tom Select use --av-control-md too, so a button beside a field is the same height by construction. The scale follows data-av-density (0.9 on compact, 1.1 on spacious) and grows by 1.1 under a coarse pointer. Set --av-btn-height yourself for a button that has to line up with something the scale does not cover.
Four of the nine numbers in this table used to be wrong — the default was written as 38px and the large as 44px, which are the previous scale, and
--smwas credited with a 13px font it has never had. A size table is the kind of page a reader believes without measuring, and three list pages had meanwhile been overriding the row-action button to 30px inline while six others used--smas documented. Measured fromsrc/scss/components/_button.scssandtokens.css.
Icons
html
<!-- Leading icon -->
<button class="av-btn av-btn--primary">
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14"/></svg>
New order
</button>
<!-- Trailing icon (for "continue" semantics) -->
<button class="av-btn av-btn--primary">
Continue
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M4 12h15M13 6l6 6-6 6"/></svg>
</button>
<!-- Icon only — aria-label is REQUIRED -->
<button class="av-btn av-btn--ghost av-btn--icon" aria-label="Delete order 1042">
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M5 7h14M10 7V5h4v2M7 7l1 13h8l1-13"/></svg>
</button>scss
.av-btn {
display: inline-flex;
align-items: center;
justify-content: center;
gap: var(--av-space-2);
white-space: nowrap;
}
.av-btn--icon {
--av-btn-size: var(--av-size-control-md);
inline-size: var(--av-btn-size);
block-size: var(--av-btn-size);
padding: 0;
position: relative;
&.av-btn--sm { --av-btn-size: var(--av-size-control-sm); }
&.av-btn--lg { --av-btn-size: var(--av-size-control-lg); }
/* Hit area meets 44px without enlarging the visual control */
&::after {
content: '';
position: absolute;
inset: calc((var(--av-size-touch-min) - var(--av-btn-size)) / -2);
}
}There is no generic flip utility. An arrow that must reverse under dir="rtl" is handled by the component that owns it, because the only properties that need reversing — transform, clip-path and gradient angles — have no logical form. The pattern is to carry the direction in a custom property and let the [dir="rtl"] rule flip that one value, which is how the sidebar's active-row sweep and the auth panel's diagonal both work. A blanket scaleX(-1) class is the wrong tool: it reverses text and shadows inside the icon too.
Loading state
html
<button class="av-btn av-btn--primary" data-av-loading data-av-loading-text="Saving…">
Save changes
</button>js
// The shipped runtime — src/js/adminvora.js, `startLoading` / `stopLoading`.
// `data-av-loading` runs `startLoading` on click; in your own code you call
// the same two steps around real work, as `AdminVora.loading.start/stop`.
const loadingLabels = new WeakMap();
function startLoading(el) {
const text = el.dataset.avLoadingText;
el.style.minInlineSize = `${el.offsetWidth}px`; // measure before the label changes
if (text) {
// The label is *moved*, never overwritten — see the note below.
const stash = document.createDocumentFragment();
while (el.firstChild) stash.appendChild(el.firstChild);
loadingLabels.set(el, stash);
el.append(text);
el.dataset.avLoadingMode = 'replace';
}
el.classList.add('is-loading');
el.setAttribute('aria-busy', 'true');
el.setAttribute('aria-disabled', 'true');
AdminVora.a11y.announce(text || 'Working…');
}
function stopLoading(el) {
const stash = loadingLabels.get(el);
if (stash) {
el.textContent = '';
el.append(stash);
loadingLabels.delete(el);
delete el.dataset.avLoadingMode;
}
el.classList.remove('is-loading');
el.removeAttribute('aria-busy');
el.removeAttribute('aria-disabled');
el.style.minInlineSize = '';
}The CSS contract is the is-loading class alone, so a button can be driven by something other than this runtime and still look right:
scss
.av-btn.is-loading { pointer-events: none; position: relative; }
.av-btn.is-loading::before {
content: '';
position: absolute;
inset-block-start: 50%;
inset-inline-start: 50%;
margin-block-start: -8px;
margin-inline-start: -8px;
inline-size: 16px;
block-size: 16px;
border: 2px solid currentColor;
border-block-start-color: transparent;
border-radius: var(--av-radius-full);
color: var(--av-text-on-primary);
animation: av-btn-spin 700ms linear infinite;
}
/* No progress text: the label hides behind the spinner and the width holds. */
.av-btn.is-loading:not([data-av-loading-mode="replace"]) { color: transparent; }
/* With progress text: the spinner becomes a flex item beside the label and
inherits the button's own `gap`. */
.av-btn.is-loading[data-av-loading-mode="replace"]::before {
position: static;
margin: 0;
flex: none;
}| Detail | Why |
|---|---|
min-inline-size locked to the original width | "Save changes" → "Saving…" would shrink the button and shift the layout |
aria-busy="true" | A spinner is invisible to a screen reader; without this the button simply goes quiet |
aria-disabled="true", not the disabled property | See below |
announce() | The visual change has no textual counterpart otherwise |
The spinner is ::before | See below |
Three decisions worth the words
aria-disabled, never disabled. The DOM property drops the element from the tab order and blurs it, so pressing Enter on Publish throws focus to <body> and hands it back nowhere when the work finishes — a keyboard user loses their place on every save. .av-btn[aria-disabled="true"] already carries the same dimmed painting as :disabled, so only the focus behaviour differs. Re-entry is prevented by the is-loading check at the call site rather than by the browser.
The spinner is ::before, and that is the whole of a bug this shipped with..av-btn--primary::after is the hover sheen — inset: 0, opacity: 0, z-index: var(--av-z-below). A spinner written on that same pseudo-element inherits all three, because specificity only arbitrates a property that both rules declare, and the sheen declares three the spinner never mentions. The result was rendered, sized and animating, while being transparent, painted behind the gradient and pinned to the top-left corner: every primary button in the product went blank the moment it was pressed — no label, no spinner, a filled slab with a toast appearing beside it. npm run test:buttons photographs a busy button and requires ink on it that moves.
The label is moved into a DocumentFragment, not overwritten. The checkout's pay button is Pay <span data-av-total-text>€284.52</span>, and a textContent swap destroys that span and gives back a flat text node — after which the wizard updates a total that is no longer in the document. Moving the nodes out and back keeps their identity, so anything holding a reference still holds the same element.
Button group and split button
html
<div class="av-btn-group" role="group" aria-label="View mode">
<button class="av-btn av-btn--outline is-active" aria-pressed="true">List</button>
<button class="av-btn av-btn--outline" aria-pressed="false">Grid</button>
<button class="av-btn av-btn--outline" aria-pressed="false">Board</button>
</div>
<div class="av-btn-group">
<button class="av-btn av-btn--primary">Save</button>
<div class="av-dropdown">
<button class="av-btn av-btn--primary av-btn--icon" type="button"
data-av-dropdown-toggle aria-expanded="false" aria-haspopup="menu">
<span class="av-visually-hidden">More save options</span>
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="m6 9 6 6 6-6"/></svg>
</button>
<ul class="av-dropdown__menu" role="menu">
<li role="none"><button class="av-dropdown__item" type="button" role="menuitem">Save and continue</button></li>
<li role="none"><button class="av-dropdown__item" type="button" role="menuitem">Save as draft</button></li>
<li role="none"><button class="av-dropdown__item" type="button" role="menuitem">Save and duplicate</button></li>
</ul>
</div>
</div>aria-pressed is required on toggle buttons. .active alone is a visual class with no semantics.
Action row
html
<div class="av-actions">
<button class="av-btn av-btn--primary" type="button">Approve</button>
<button class="av-btn av-btn--outline" type="button">Reject</button>
</div>The row of buttons that answers whatever sits above it — a message, a review, a contact card, a file preview. A wrapping flex row with one gap, and nothing else: it owns no spacing outside itself, so a caller that needs the row set off from the content above supplies that with its own rhythm (.av-pt-5, or the panel's own padding).
Unlike .av-btn-group, the buttons stay separate controls with their own edges. Use the group when the buttons are one segmented choice, and this when they are several independent actions.
It was
.av-message-actionsfor a while, because the mail reading pane needed it first — and that class carries the pane's edge padding, so all four other callers switched the padding off again inline. Naming a composition after the first screen to want it is how a component acquires a screen's layout, and how the pages that borrow it acquire inline styles.
Segmented control
html
<div class="av-segmented" role="radiogroup" aria-label="Date range">
<input type="radio" name="range" id="r7" value="7" checked>
<label class="av-btn av-btn--sm" for="r7">7 days</label>
<input type="radio" name="range" id="r30" value="30">
<label class="av-btn av-btn--sm" for="r30">30 days</label>
<input type="radio" name="range" id="r90" value="90">
<label class="av-btn av-btn--sm" for="r90">90 days</label>
</div>scss
.av-segmented {
display: inline-flex;
padding: 3px;
gap: 2px;
background: var(--av-surface-sunken);
border-radius: var(--av-radius-md);
.btn {
--bs-btn-bg: transparent;
--bs-btn-border-color: transparent;
--bs-btn-color: var(--av-text-muted);
border-radius: calc(var(--av-radius-md) - 3px);
}
.btn-check:checked + .btn {
background: var(--av-surface-raised);
color: var(--av-text-primary);
box-shadow: var(--av-shadow-xs);
font-weight: var(--av-font-weight-medium);
}
.btn-check:focus-visible + .btn {
outline: var(--av-focus-width) solid var(--av-focus-color);
outline-offset: 1px;
}
}Native radios inside give correct keyboard behaviour (←/→ moves the selection) and correct semantics for free. Never build this with <button> elements.
Floating action button
html
<button class="av-fab" type="button" data-av-drawer="quick-add" aria-label="Create new">
<svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14"/></svg>
</button>scss
.av-fab {
position: fixed;
inset-block-end: max(var(--av-space-6), env(safe-area-inset-bottom));
inset-inline-end: var(--av-space-6);
z-index: var(--av-z-sticky);
inline-size: 56px;
block-size: 56px;
border: 0;
border-radius: var(--av-radius-full);
background: var(--av-color-primary);
color: var(--av-text-on-primary);
box-shadow: var(--av-shadow-lg);
display: grid;
place-items: center;
transition: transform var(--av-duration-fast) var(--av-ease-standard),
box-shadow var(--av-duration-fast) var(--av-ease-standard);
&:hover { transform: scale(1.06); box-shadow: var(--av-shadow-xl); }
&:active { transform: scale(.97); }
/* Sits above the mobile bottom nav */
@media (max-width: 991.98px) {
inset-block-end: calc(56px + env(safe-area-inset-bottom) + var(--av-space-4));
}
@media (prefers-reduced-motion: reduce) { transition: none; &:hover { transform: none; } }
}A FAB must not be the only way to perform an action — it is invisible to keyboard users until they tab to the end of the page. Always mirror it in the page header.
Destructive actions
html
<button class="av-btn av-btn--outline-danger"
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-variant="danger">
Delete
</button>Rules for destructive actions:
| Rule | Reason |
|---|---|
| Never solid red unless it is the only action | Red draws the eye; a red primary competes with the real primary |
| Always confirm irreversible operations | |
| The confirm button repeats the verb ("Delete order", not "OK") | Users click "OK" without reading |
| The confirm text states the consequence | "This cannot be undone" |
| Cancel is the default-focused button | An accidental Enter must not destroy data |
| Prefer undo over confirm where possible | A toast with "Undo" is better UX than a dialog |
js
// Undo pattern — better than a confirm dialog for reversible actions
async function archiveOrder(id) {
row.hidden = true;
const toast = AdminVora.toast.show({
message: 'Order archived',
duration: 8000,
action: { label: 'Undo', run: () => { row.hidden = false; clearTimeout(commit); } }
});
const commit = setTimeout(() => fetch(`/api/orders/${id}/archive`, { method: 'POST' }), 8000);
}Disabled
html
<button class="av-btn av-btn--primary" disabled>Save</button>
<!-- When the user needs to know WHY -->
<span data-av-tooltip="Complete all required fields to save">
<button class="av-btn av-btn--primary" disabled aria-describedby="saveHint">Save</button>
</span>
<span id="saveHint" class="av-visually-hidden">Complete all required fields to save</span>disabled elements do not fire pointer events, so a tooltip must be on a wrapper. And because they are removed from the tab order, a screen-reader user may never discover them — always provide the reason in adjacent text or via aria-describedby.
Note — consider not disabling. An enabled button that shows validation errors on click is often better UX than a disabled button that gives no feedback about what is missing.
Options
data-av-loading
| Attribute | Status | Meaning |
|---|---|---|
data-av-loading | 🟢 | Starts the busy state on click and leaves it on. A submit button's page navigates away; anything else ends it with AdminVora.loading.stop(el). Emits av:loading:start with { el }. (The demo pages stop it after 1.6 s and raise a toast; that is src/demo/demo.js, not the runtime.) |
data-av-loading-text | 🟢 | Progress label. Present → the label is replaced and the spinner sits beside it; absent → the label hides behind a centred spinner and the width holds. |
data-av-loading-mode | 🟢 | Written by the runtime, not by you. replace while a -text button is busy; the CSS reads it to move the spinner inline. |
API
There is no per-element instance to read back. The public API is theme, toast, confirm, loading, a11y, utils, on, emit, init, destroy and version.
AdminVora.loading is the same two steps the data-av-loading hook runs, so the label swap, the held width and the announcement all match:
js
const btn = document.querySelector('#save');
AdminVora.loading.start(btn);
try {
await fetch('/settings', { method: 'POST', body: new FormData(btn.form) });
} finally {
AdminVora.loading.stop(btn);
}Accessibility checklist
- [ ]
<button type="button">for actions,<a>for navigation — never<div onclick> - [ ]
typeattribute always explicit (default issubmit, which surprises people) - [ ] Icon-only buttons have
aria-label - [ ] Toggle buttons have
aria-pressed - [ ] Expanding buttons have
aria-expanded+aria-controls - [ ] Loading buttons have
aria-busyand announce the change - [ ] Focus ring is visible on every variant, including on coloured backgrounds
- [ ] Text contrast ≥ 4.5:1 in every theme and mode
- [ ] Minimum 44×44px hit area (via
::afterexpansion if visually smaller) - [ ] Disabled reason is communicated somewhere reachable
Read next: Forms & Inputs.