Appearance
Sidebar
The primary navigation. Menu schema, states, keyboard model, and the accessibility details most templates get wrong.
Markup
The shipped tree, from html/_partials/sidebar.html. The same tree serves all ten data-av-layout arrangements — see Layout Modes — so nothing here is specific to the vertical rail.
html
<aside class="av-sidebar" id="avSidebar">
<div class="av-sidebar__brand">
<a href="/" class="av-brand">
<img class="av-brand__mark" src="/src/img/logo-mark.svg" alt="" width="32" height="32">
<span class="av-brand__text">AdminVora</span>
</a>
<button class="av-btn av-btn--ghost av-btn--icon av-sidebar-collapse" type="button"
data-av-sidebar-toggle
aria-label="Collapse sidebar" aria-expanded="true" aria-controls="avSidebar">
<svg class="av-icon av-icon--sm" aria-hidden="true" viewBox="0 0 24 24">
<path d="M15 6l-6 6 6 6"/>
</svg>
</button>
</div>
<nav class="av-sidebar__nav" aria-label="Main">
<ul class="av-menu">
<li class="av-menu__group">
<details class="av-menu__disclosure" open>
<summary class="av-menu__title" id="avGroupCommerce">
<span class="av-menu__title-text">Commerce</span>
<svg class="av-icon av-menu__caret" aria-hidden="true" viewBox="0 0 24 24"
fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"/></svg>
</summary>
<ul class="av-menu__group-list" aria-labelledby="avGroupCommerce">
<li class="av-menu__item av-menu__item--active">
<a class="av-menu__link" href="/orders" aria-current="page">
<svg class="av-icon av-menu__icon" aria-hidden="true" viewBox="0 0 24 24">
<path d="M6 7h12l-1 13H7L6 7z"/><path d="M9 7a3 3 0 0 1 6 0"/>
</svg>
<span class="av-menu__label">Orders</span>
<span class="av-menu__badge">12</span>
</a>
</li>
<li class="av-menu__item">
<a class="av-menu__link" href="/products">
<svg class="av-icon av-menu__icon" aria-hidden="true" viewBox="0 0 24 24">
<path d="M12 3l8 4.5v9L12 21l-8-4.5v-9L12 3z"/>
</svg>
<span class="av-menu__label">Products</span>
</a>
</li>
</ul>
</details>
</li>
</ul>
</nav>
<div class="av-sidebar__footer">
<p class="av-field-line__hint">You have used <strong>82%</strong> of your plan.</p>
<div class="av-progress" role="progressbar" aria-valuenow="82" aria-valuemin="0"
aria-valuemax="100" aria-label="Plan usage">
<div class="av-progress__bar" style="inline-size: 82%"></div>
</div>
<a class="av-btn av-btn--primary av-btn--block" href="/billing">Upgrade</a>
</div>
</aside><details>/<summary>, not a button and a class
This is the decision the rest of the page follows from, and it replaces what an earlier revision specified — <button aria-expanded> plus .av-menu__item--has-children, .av-menu__item--open and .av-menu__sub. None of those exists, and the platform element is better on every axis that matters:
| What you would have written | What <details> gives you |
|---|---|
aria-expanded toggled in JavaScript | Owned by the element, and correct before any script runs |
aria-controls pointing at the <ul> | Implicit in the parent/child relationship |
| A click handler, and a keyboard handler beside it | Enter and Space on the <summary>, from the platform |
A --open class kept in step with the state | The [open] attribute, which is the state |
An is-open style hook | .av-menu__disclosure[open], which cannot disagree with itself |
The group heading is a <summary class="av-menu__title">, so it is focusable, announced with its expanded state, and operable with no JavaScript at all. A menu that works with the runtime removed is the property this buys, and it is why the six bar layouts can re-lay-out the same markup without re-implementing any of it.
The list carries aria-labelledby pointing at the summary's id, so the group of links is named by its heading rather than being an anonymous <ul>.
There is one level of grouping. Depth beyond two levels is what the two-column layout exists for.
The collapse control is .av-btn.av-btn--ghost.av-btn--icon.av-sidebar-collapse. Its chevron is drawn pointing the right way and the rail's own rules handle RTL.
The sidebar is found by class, and the nav scrolls natively — there is no custom scrollbar library.
Critical details
| Detail | Why |
|---|---|
Parents are <button>, not <a href="#"> | They perform an action, not navigation. A # link puts a junk entry in history and is announced as a link. |
aria-expanded on the parent button | The only way a screen reader knows the submenu state |
aria-controls pointing at the <ul> id | Associates the button with what it controls |
aria-current="page" on the active link | Announced as "current page"; .is-active alone is invisible to AT |
alt="" on the logo image | The adjacent text is the accessible name; a duplicate would be announced twice |
av-menu__title with aria-hidden="true" | Visual grouping label; it is not a heading and should not be announced as content |
| Badge inside the link | Announced as part of the link name: "Orders 12" |
States
| State | Attribute / class | Effect |
|---|---|---|
| Expanded | data-av-sidebar="expanded" | 264px, labels visible |
| Collapsed | data-av-sidebar="collapsed" | 72px, icons only, flyout on hover/focus |
| Hidden | data-av-sidebar="hidden" | 0px, off-canvas |
| Mobile open | data-av-sidebar="mobile-open" | Overlays with a backdrop, below lg |
| Item active | .av-menu__item--active + aria-current="page" | Highlighted |
| Group open | .av-menu__item--open + aria-expanded="true" | Submenu visible |
| Hovered | :hover | Background tint |
scss
.av-menu__link {
display: flex;
align-items: center;
gap: var(--av-space-3);
min-block-size: var(--av-menu-item-height, 42px);
padding-inline: var(--av-space-3);
border-radius: var(--av-radius-md);
color: var(--av-text-secondary);
font-size: var(--av-font-size-sm);
font-weight: var(--av-font-weight-medium);
text-decoration: none;
inline-size: 100%;
text-align: start;
background: none;
border: 0;
position: relative;
transition: background-color var(--av-duration-fast) var(--av-ease-standard),
color var(--av-duration-fast) var(--av-ease-standard);
&:hover { background: var(--av-surface-sunken); color: var(--av-text-primary); }
}
.av-menu__item--active > .av-menu__link {
background: var(--av-color-primary-subtle);
color: var(--av-color-primary-text);
font-weight: var(--av-font-weight-semibold);
/* The active indicator bar */
&::before {
content: '';
position: absolute;
inset-inline-start: calc(var(--av-space-3) * -1);
inset-block: 25%;
inline-size: 3px;
border-radius: 0 var(--av-radius-full) var(--av-radius-full) 0;
background: var(--av-color-primary);
}
}
[dir="rtl"] .av-menu__item--active > .av-menu__link::before {
border-radius: var(--av-radius-full) 0 0 var(--av-radius-full);
}Opening and closing a group
There is no animation, and display is the whole mechanism.
scss
.av-menu__disclosure[open] > .av-menu__group-list { display: flex; }
.av-menu__disclosure[open] .av-menu__caret { rotate: 180deg; }
/* Everything that is not `display` stays unconditional — it costs nothing while
the list is hidden and keeps the two rules from drifting. */
.av-menu__group-list {
flex-direction: column;
gap: 2px;
padding: 0;
margin: 0;
list-style: none;
}Setting display only on the open state is not tidiness — it is the trap this rule was written around. A browser hides the contents of a closed <details> with its own display: none, and an author display declaration beats a UA one at any specificity. An unconditional display: flex left every group rendered and the whole feature silently inert: all 52 links visible with five of six groups shut. It is the same shape as [hidden] losing to an author display, which this codebase fixed globally in @layer utilities.
Keyboard model — the platform's
There is no sidebar module. What you get is what <summary> gives you, which is the reason the element was chosen:
| Key | Action |
|---|---|
| Tab | Move to the next focusable item — every group heading and every visible link |
| Enter / Space | Follow a link, or toggle the group under focus |
| Esc | Close the off-canvas sidebar and return focus to the toggle |
Arrow-key roving, type-ahead and Home/End are not implemented. That is a gap rather than a decision, and it is worth being precise about its size: the navigation is fully operable by keyboard without them, because every control is in the tab order and announced with its state. What is missing is the faster path through a long menu.
Adding it means owning aria-expanded and the roving tabindex in JavaScript, which is what the platform is currently doing for free. Weigh that before starting.
Collapse behaviour
Every [data-av-sidebar-toggle] button does one of two things, decided at click time:
- Off-canvas (below 992px, or
data-av-layout="overlay"at any width): opens or closes the drawer by togglingis-mobile-openon.av-sidebar, shows[data-av-sidebar-backdrop], and moves focus to the first menu link. Esc or a click on the backdrop closes it. - Otherwise: flips the persisted
sidebarpreference betweenexpandedandcollapsedthroughAdminVora.theme.set('sidebar', …), which writesdata-av-sidebaron<html>, and emitsav:sidebar:togglewith{ collapsed, source }.
Crossing the breakpoint always closes the drawer and never touches the desktop preference, so a visitor who collapsed the sidebar on desktop still finds it collapsed when they return to a wide window.
Collapsed rail, and the group that must not close with it
scss
[data-av-sidebar="collapsed"] .av-menu__label,
[data-av-sidebar="collapsed"] .av-menu__title-text,
[data-av-sidebar="collapsed"] .av-menu__caret,
[data-av-sidebar="collapsed"] .av-brand__text { display: none; }
[data-av-sidebar="collapsed"] .av-menu__link { justify-content: center; padding-inline: 0; }The interaction worth knowing. The collapsed rail hides every section heading, and a closed <details> hides its own list — so a group the visitor had shut would take its icons with it and leave a gap where half the navigation used to be. initShell forces every group open while the rail is showing and restores what the visitor had on the way out. Neither half is optional: forcing open without saving loses their arrangement, and saving without forcing open loses the icons.
For labels that fly out of the rail on hover and focus, use data-av-layout="rail" — a different axis, described in Layout Modes. data-av-sidebar="collapsed" simply drops the labels; rail keeps them reachable.
Off-canvas, and the two routes into it
The rail goes off-canvas below 992px or whenever data-av-layout="overlay" is set, at any width.
js
const offCanvas = () =>
!mq.matches || document.documentElement.getAttribute('data-av-layout') === 'overlay';Both routes have to be asked about at click time, and this is a bug that shipped once. The toggle originally checked the media query alone, so in overlay at desktop width its only navigation control silently wrote the collapse preference instead of opening the drawer. The layout also changes under a live page, so the check cannot be made at bind time.
The off-canvas state is the is-mobile-open class on .av-sidebar — not a data-av-sidebar value. Opening it moves focus to the first menu link; Esc and the backdrop both close it and return focus to the toggle. Leaving mobile clears the state and leaves the desktop preference untouched, and switching layouts clears it too — otherwise leaving overlay while the drawer is showing strands a rail above the content with its backdrop still up.
The off-canvas breakpoint, 992px, is a constant.
Events
| Event | Detail |
|---|---|
av:sidebar:toggle | { collapsed, source } |
av:sidebar:group-toggle | { item, open } |
There are no sidebar open/close events. The off-canvas rail is the is-mobile-open class; observe it, or listen for av:theme:change.
Checklist
- [ ] Group headings are
<summary>, soaria-expandedand the keyboard model come from the platform - [ ] The group list carries
aria-labelledbypointing at its summary - [ ]
displayon.av-menu__group-listis set only under[open]— an unconditional one beats the UA rule and renders every group - [ ] The active link has
aria-current="page", in the HTML the server sent - [ ]
<nav>hasaria-label="Main", and the logo<img>hasalt="" - [ ] Every page source declares
nav,subornavUnlisted, and the build fails if the value reads nothing - [ ] No two sidebar rows share a label
- [ ] The collapsed rail forces groups open and restores what the visitor had
- [ ] The toggle asks about both routes to off-canvas — narrow viewport and
overlaylayout — at click time - [ ] Works at 320px; backdrop click and Esc close it and restore focus
Read next: Topbar.