Side Navigation

When to Use

Anatomy

Four regions, top to bottom. Only the list is required.

Variants

Two, matching M3's collapsed and expanded rail. Labels show in both — M3 keeps them, and so do we. What changes is where the label sits and what the active indicator wraps.

<?= ws_sidenav([
    ['label' => 'Home',       'icon' => 'home',              'href' => '/'],
    ['label' => 'Strategize', 'icon' => 'knight',            'href' => '/strategist/app.php', 'active' => true],
    ['label' => 'Plan',       'icon' => 'calendar_view_day', 'href' => '/planner/'],
    ['label' => 'Facilitate', 'icon' => 'groups',            'href' => '/facilitator/'],
    ['label' => 'Synthesize', 'icon' => 'hub',               'href' => '/synthesize/'],
    ['type'  => 'divider'],
    ['label' => 'Library',      'icon' => 'auto_stories', 'href' => '/library/'],
    ['label' => 'Rescue Cards', 'icon' => 'stacks',       'href' => '/library/collections/', 'badge' => 37],
    ['label' => 'More', 'icon' => 'more_horiz', 'expands' => true, 'id' => 'navMore', 'children' => [...]],
], ['variant' => 'rail']) ?>

States

Every state below is rendered live. Hover and focus are interactive — tab through the rail to see the focus ring and the tooltip appear together.

API

ws_sidenav(array $items, array $options = [])

Item shape

Accessibility

• Landmark. Renders a <nav> with aria-label. If a page carries more than one nav, every label must differ or screen-reader users get an undifferentiated list.
• List semantics. Items sit in a <ul>/<li>, so AT announces "list, 8 items" and users can jump by item.
• Current page. aria-current="page", not just a colour class. M3's indicator is a filled pill rather than a tint, so the state reads as a shape and survives greyscale; a forced-colors block maps it to Highlight.
• Keyboard. Plain Tab order — these are links in a landmark, which is what APG prescribes for site navigation. No roving tabindex, because arrow-key trapping in a nav surprises more users than it helps. The disclosure is a real button: Enter and Space both toggle it.
• The rail's labels. Visible, as M3 prescribes — an icon-only rail forces everyone to learn a glyph vocabulary. Where 80px truncates a longer name the tooltip backs it up on hover and focus, so it is reachable from the keyboard. The tooltip is aria-hidden: it repeats the label, and exposing it would double-read.
• Disabled links. HTML has no disabled for anchors, so the component sets aria-disabled="true" and tabindex="-1" rather than leaving a focusable dead control.
• Icons. Decorative in every case — the label carries the meaning, so SVGs render inline and the ligature fallback is aria-hidden.
• Motion. All transitions drop under prefers-reduced-motion: reduce.
• Contrast, measured not assumed. Rest label #57534E on #FAFAF9 is 7.3:1; active label #2C2416 on the #FEE2E2 indicator is 12.5:1; badge #FFFFFF on #C73E3E is 5.0:1. All clear AA. Two earlier pairings did not and were changed: red #C73E3E on the indicator measured 4.11:1, and a --phase-learn badge measured 3.82:1.
• The indicator is a tint, so it is never the only cue. At 1.17:1 against the surface, M3's tonal pill is deliberately quiet — it is backed by a weight change to semibold and by aria-current="page", and it maps to Highlight under forced colours.

Tokens consumed