Sidebar navigation

Live variants

default

Markup

<j3w1-sidebar-nav id="example-sidebar-nav-default"><nav class="sidebar-nav" aria-label="Sections">
  <ul class="sidebar-nav-list">
    <li class="sidebar-nav-item"><a class="sidebar-nav-link sidebar-nav-current" href="#example-sidebar-nav-default-sn-overview" aria-current="page"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><rect x="2.5" y="2.5" width="11" height="11"></rect></svg></span><span class="sidebar-nav-label">Overview</span></a></li>
    <li class="sidebar-nav-item"><a class="sidebar-nav-link sidebar-nav-link-demo-target" href="#example-sidebar-nav-default-sn-tokens"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><circle cx="8" cy="8" r="5.5"></circle></svg></span><span class="sidebar-nav-label">Tokens</span></a></li>
    <li class="sidebar-nav-item">
      <button class="sidebar-nav-link sidebar-nav-group" type="button" aria-expanded="false" aria-controls="example-sidebar-nav-default-sn-components"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path d="M2.5 4h11M2.5 8h11M2.5 12h11"></path></svg></span><span class="sidebar-nav-label">Components</span><span class="sidebar-nav-chevron" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path d="M6 4l4 4-4 4"></path></svg></span></button>
      <ul class="sidebar-nav-list sidebar-nav-sublist" id="example-sidebar-nav-default-sn-components" hidden="">
        <li class="sidebar-nav-item"><a class="sidebar-nav-link" href="#example-sidebar-nav-default-sn-actions"><span class="sidebar-nav-label">Actions</span></a></li>
        <li class="sidebar-nav-item"><a class="sidebar-nav-link" href="#example-sidebar-nav-default-sn-forms"><span class="sidebar-nav-label">Forms</span></a></li>
      </ul>
    </li>
    <li class="sidebar-nav-item"><a class="sidebar-nav-link" href="#example-sidebar-nav-default-sn-ports"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path d="M3 8h10M9 4l4 4-4 4"></path></svg></span><span class="sidebar-nav-label">Ports</span></a></li>
  </ul>
</nav><p id="example-sidebar-nav-default-sn-overview" tabindex="-1" class="j3w1-example-target">Example destination: sn overview</p><p id="example-sidebar-nav-default-sn-tokens" tabindex="-1" class="j3w1-example-target">Example destination: sn tokens</p><p id="example-sidebar-nav-default-sn-actions" tabindex="-1" class="j3w1-example-target">Example destination: sn actions</p><p id="example-sidebar-nav-default-sn-forms" tabindex="-1" class="j3w1-example-target">Example destination: sn forms</p><p id="example-sidebar-nav-default-sn-ports" tabindex="-1" class="j3w1-example-target">Example destination: sn ports</p></j3w1-sidebar-nav>

collapsed

Markup

<j3w1-sidebar-nav id="example-sidebar-nav-collapsed"><nav class="sidebar-nav sidebar-nav-collapsed" aria-label="Sections">
  <ul class="sidebar-nav-list">
    <li class="sidebar-nav-item"><a class="sidebar-nav-link sidebar-nav-current" href="#example-sidebar-nav-collapsed-sn-overview" aria-current="page" aria-label="Overview" title="Overview"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><rect x="2.5" y="2.5" width="11" height="11"></rect></svg></span><span class="sidebar-nav-label">Overview</span></a></li>
    <li class="sidebar-nav-item"><a class="sidebar-nav-link sidebar-nav-link-demo-target" href="#example-sidebar-nav-collapsed-sn-tokens" aria-label="Tokens" title="Tokens"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><circle cx="8" cy="8" r="5.5"></circle></svg></span><span class="sidebar-nav-label">Tokens</span></a></li>
    <li class="sidebar-nav-item">
      <button class="sidebar-nav-link sidebar-nav-group" type="button" aria-expanded="false" aria-controls="example-sidebar-nav-collapsed-sn-components" aria-label="Components" title="Components"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path d="M2.5 4h11M2.5 8h11M2.5 12h11"></path></svg></span><span class="sidebar-nav-label">Components</span><span class="sidebar-nav-chevron" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path d="M6 4l4 4-4 4"></path></svg></span></button>
      <ul class="sidebar-nav-list sidebar-nav-sublist" id="example-sidebar-nav-collapsed-sn-components" hidden="">
        <li class="sidebar-nav-item"><a class="sidebar-nav-link" href="#example-sidebar-nav-collapsed-sn-actions" aria-label="Actions" title="Actions"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><rect x="3" y="5" width="10" height="6"></rect></svg></span><span class="sidebar-nav-label">Actions</span></a></li>
        <li class="sidebar-nav-item"><a class="sidebar-nav-link" href="#example-sidebar-nav-collapsed-sn-forms" aria-label="Forms" title="Forms"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path d="M3 5h10M3 8h6M3 11h8"></path></svg></span><span class="sidebar-nav-label">Forms</span></a></li>
      </ul>
    </li>
    <li class="sidebar-nav-item"><a class="sidebar-nav-link" href="#example-sidebar-nav-collapsed-sn-ports" aria-label="Ports" title="Ports"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path d="M3 8h10M9 4l4 4-4 4"></path></svg></span><span class="sidebar-nav-label">Ports</span></a></li>
  </ul>
</nav><p id="example-sidebar-nav-collapsed-sn-overview" tabindex="-1" class="j3w1-example-target">Example destination: sn overview</p><p id="example-sidebar-nav-collapsed-sn-tokens" tabindex="-1" class="j3w1-example-target">Example destination: sn tokens</p><p id="example-sidebar-nav-collapsed-sn-actions" tabindex="-1" class="j3w1-example-target">Example destination: sn actions</p><p id="example-sidebar-nav-collapsed-sn-forms" tabindex="-1" class="j3w1-example-target">Example destination: sn forms</p><p id="example-sidebar-nav-collapsed-sn-ports" tabindex="-1" class="j3w1-example-target">Example destination: sn ports</p></j3w1-sidebar-nav>

nested

Markup

<j3w1-sidebar-nav id="example-sidebar-nav-nested"><nav class="sidebar-nav" aria-label="Sections">
  <ul class="sidebar-nav-list">
    <li class="sidebar-nav-item"><a class="sidebar-nav-link" href="#example-sidebar-nav-nested-sn-overview"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><rect x="2.5" y="2.5" width="11" height="11"></rect></svg></span><span class="sidebar-nav-label">Overview</span></a></li>
    <li class="sidebar-nav-item">
      <button class="sidebar-nav-link sidebar-nav-group" type="button" aria-expanded="true" aria-controls="example-sidebar-nav-nested-sn-components"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path d="M2.5 4h11M2.5 8h11M2.5 12h11"></path></svg></span><span class="sidebar-nav-label">Components</span><span class="sidebar-nav-chevron" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path d="M6 4l4 4-4 4"></path></svg></span></button>
      <ul class="sidebar-nav-list sidebar-nav-sublist" id="example-sidebar-nav-nested-sn-components">
        <li class="sidebar-nav-item"><a class="sidebar-nav-link" href="#example-sidebar-nav-nested-sn-actions"><span class="sidebar-nav-label">Actions</span></a></li>
        <li class="sidebar-nav-item"><a class="sidebar-nav-link sidebar-nav-current" href="#example-sidebar-nav-nested-sn-navigation" aria-current="page"><span class="sidebar-nav-label">Navigation</span></a></li>
        <li class="sidebar-nav-item"><a class="sidebar-nav-link sidebar-nav-link-demo-target" href="#example-sidebar-nav-nested-sn-display"><span class="sidebar-nav-label">Display</span></a></li>
      </ul>
    </li>
    <li class="sidebar-nav-item"><a class="sidebar-nav-link" href="#example-sidebar-nav-nested-sn-ports"><span class="sidebar-nav-icon" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path d="M3 8h10M9 4l4 4-4 4"></path></svg></span><span class="sidebar-nav-label">Ports</span></a></li>
  </ul>
</nav><p id="example-sidebar-nav-nested-sn-overview" tabindex="-1" class="j3w1-example-target">Example destination: sn overview</p><p id="example-sidebar-nav-nested-sn-actions" tabindex="-1" class="j3w1-example-target">Example destination: sn actions</p><p id="example-sidebar-nav-nested-sn-navigation" tabindex="-1" class="j3w1-example-target">Example destination: sn navigation</p><p id="example-sidebar-nav-nested-sn-display" tabindex="-1" class="j3w1-example-target">Example destination: sn display</p><p id="example-sidebar-nav-nested-sn-ports" tabindex="-1" class="j3w1-example-target">Example destination: sn ports</p></j3w1-sidebar-nav>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@4.0.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/sidebar-nav.css';
import '@j3w1/ui/register/sidebar-nav';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@4.0.0 j3w1-ui copy sidebar-nav --out ./vendor/j3w1/sidebar-nav

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.
`open`	`boolean`	Native details expansion when this component contains details.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.

events

Name	Type / signature	Meaning
`j3w1-toggle`	`CustomEvent`	A native disclosure or navigation group changed.

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Specimen density

Specimen profile

Sidebar navigation `sidebar-nav`

Family: Navigation
Maturity: stable
Priority: R1
Since: 0.1.0
Native control: native nav with nested ul lists; groups are buttons with aria-expanded — APG pattern
specified
demonstrated

A vertical list of section links with optional nested groups; the current section carries a 2px inline-start indicator and bright text, and the rail collapses to icons.

Report an issue with this component

Open component workbench

Tokens

Focus a role to inspect its values; follow its link for persistent usage and source details.

Part	Role	Value	Use
`root.bg`	`color.surface.default`approveduse	`#0d0707`	D-041 surface.default: color.primitive.modern.panel.
`root.border`	`color.border.divider`approveduse	`#482b2b`	D-041 border.divider: color.primitive.modern.divider.
`link.text`	`color.text.default`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`link.bg-hover`	`color.interaction.hover.bg`approveduse	`#1c1010`	D-041 interaction.hover.bg: color.primitive.modern.hover.
`link.bg-pressed`	`color.interaction.pressed.bg`observeduse	`#420f0c`	Pressed fill.
`link.ring`	`color.interaction.focus.ring`observeduse	`#e53935`	1px dashed focus ring on controls and rows.
`link.indicator`	`color.border.selected-indicator`observeduse	`#e53935`	2px indicator bar on the selected tab or nav item.
`link.indicator-inactive`	`color.border.selected-indicator-inactive`observeduse	`#9e231f`	Indicator bar when the container is not focused.
`current.text`	`color.text.bright`approveduse	`#ffa2a7`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`selected.bg`	`color.interaction.selection.bg`approveduse	`#531310`	Selected row, tab, workspace; D-027 recessed the fill, leaving the 2px indicator and the check to carry selection.
`selected.text`	`color.interaction.selection.text`observeduse	`#f4eeee`	Text on the selection.
`selected.ring`	`color.interaction.focus.ring`observeduse	`#e53935`	1px dashed focus ring on controls and rows.
`selected.inactive-bg`	`color.interaction.selection.inactive-bg`observeduse	`#420f0c`	Selection while the container is not focused.
`selected.inactive-text`	`color.interaction.selection.inactive-text`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`icon.stroke`	`color.icon.default`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`group.chevron`	`color.icon.decorative`approveduse	`#986f72`	D-041 icon.decorative: color.primitive.modern.control.

State matrix

Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).

State	Default	Collapsed	Nested
`default`	Overview Tokens Ports	Overview Tokens Ports	Overview Actions Navigation Display Ports
`hover`
`focus-visible`
`current`
`selected`
`selected+container-inactive`
`expanded`
`collapsed`

Moves between the sections of an application: the primary navigation of a settings panel, admin area or documentation site. Tabs switch views inside one section; a tree browses data, not sections.

A nav on color.surface.default with a 1px color.border.divider inline-end edge; otherwise parts as listed in the anatomy.

State	Visual	Non-colour channel
default	text `color.text.default`; no fill; transparent inline-start edge	—
hover	→ `color.interaction.hover.bg`	cursor: pointer
focus-visible	1px dashed `color.interaction.focus.ring` at −2px	the ring
current	2px `color.border.selected-indicator` inline-start bar; text `color.text.bright`	`aria-current="page"`; the bar
selected	`color.interaction.selection.bg` with `color.interaction.selection.text`; 1px dashed `color.interaction.focus.ring` at −2px when focused	`aria-selected` on a listbox-style rail; the on-fill text
selected+container-inactive	`color.interaction.selection.inactive-bg` with `color.interaction.selection.inactive-text`; no ring	lightness drop between the two fills
expanded	chevron rotated 90°; sublist shown	`aria-expanded="true"`; the children are present
collapsed	labels visually hidden; icons centred; current bar and fills unchanged	labels remain for assistive technology and as tooltips

current is where the user is; selected is what the user chose in a rail that drives a detail pane. A rail is one or the other, never both.

As in the key table; toggling a group leaves focus on its button. No arrow keys: the rail is a list of links, not a tree.

aria-label on the nav distinguishes the landmark. A rail that drives a detail pane is a listbox with aria-selected, not links. A closed sublist is hidden, so its links leave the tab order. Collapsed labels are clipped, not display: none, so names survive; icon-only links also get a title. Text meets 4.5:1; the indicator 3:1. Rows are at least 24 CSS pixels tall in compact.

The chevron is an SVG. Toolkits without logical borders draw the bar on the left in LTR and on the right in RTL explicitly. Hosts that cannot hide labels while keeping their names show the full rail.

A filled or rounded current item. The indicator on the inline-end edge. A current item marked by bold alone. Labels removed from the DOM when collapsed. Hidden children left in the tab order. A rail that scrolls horizontally. Icon-only links without an accessible name. Hover that changes the text colour.

Contrast report

13 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.

Pair	State	Kind	Foreground	Background	Ratio	Min	Result
sidebar-nav default text	default	text	`color.text.default` `#e99499`	`color.surface.default` `#0d0707`	8.72	4.5	pass
sidebar-nav hover text	hover	text	`color.text.default` `#e99499`	`color.interaction.hover.bg` `#1c1010`	8.10	4.5	pass
sidebar-nav focus-visible text	focus-visible	text	`color.text.default` `#e99499`	`color.surface.default` `#0d0707`	8.72	4.5	pass
sidebar-nav focus-visible outline	focus-visible	ui	`color.interaction.focus.ring` `#e53935`	`color.surface.default` `#0d0707`	4.73	3	pass
sidebar-nav current text	current	text	`color.text.bright` `#ffa2a7`	`color.surface.default` `#0d0707`	10.45	4.5	pass
sidebar-nav current border	current	ui	`color.border.selected-indicator` `#e53935`	`color.surface.default` `#0d0707`	4.73	3	pass
sidebar-nav selected text	selected	text	`color.interaction.selection.text` `#f4eeee`	`color.interaction.selection.bg` `#531310`	12.47	4.5	pass
sidebar-nav selected+container-inactive text	selected+container-inactive	text	`color.interaction.selection.inactive-text` `#e99499`	`color.interaction.selection.inactive-bg` `#420f0c`	7.02	4.5	pass
sidebar-nav expanded text	expanded	text	`color.text.default` `#e99499`	`color.surface.default` `#0d0707`	8.72	4.5	pass
sidebar-nav collapsed text	collapsed	text	`color.text.default` `#e99499`	`color.surface.default` `#0d0707`	8.72	4.5	pass
ring on a selected item when focused	selected	ui	`color.interaction.focus.ring` `#e53935`	`color.interaction.selection.bg` `#531310`	3.38	3	pass
group chevron (decorative; aria-expanded carries the state)	—	ui	`color.icon.decorative` `#986f72`	`color.surface.default` `#0d0707`	4.62	1	pass
rail edge (decorative)	—	ui	`color.border.divider` `#482b2b`	`color.surface.default` `#0d0707`	1.58	1	pass

Keys

Key	Action
`Tab / Shift+Tab`	Moves through links and group buttons in document order; hidden children are skipped.
`Enter`	Follows a link or toggles a group.
`Space`	Toggles a group.

For agents

Component JSON ·Implementation brief ·Build a task kit ·

Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-STATE-MATRIX

j3w1 / theme

j3w1 / command

Live variants

default

collapsed

nested

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Sidebar navigation `sidebar-nav`

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Live variants

default

collapsed

nested

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Sidebar navigation sidebar-nav

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Sidebar navigation `sidebar-nav`