Sidebar / nav rail

In review

Live · web

Sidebar

dizyx · nockerl-design

Streaming · 2 tools running

nockerl-design · docs site

Designing the sidebar to the token-reactive standard.

Expanded · viewing nockerl-design · docs site. Tab in, arrow-key the rows, expand Tasks, collapse to the rail. The sidebar stays in the layout. The island is live.

Code

// Web: React, consuming @dizyx/nockerl-tokens. This is the spec plus the live demo above.
// It is not yet exported from @dizyx/nockerl-react.

export function Shell() {
  const [section, setSection] = useState('chat');
  const [collapsed, setCollapsed] = useState(false);
  return (
    <div className="layout">
      <Sidebar
        collapsed={collapsed}                 // expanded ↔ icon-only rail
        onToggleCollapse={() => setCollapsed((c) => !c)}
        selected={section}
        onSelect={setSection}
        sections={[
          { label: 'Workspace', items: [
            { id: 'home', label: 'Home', icon: <HomeIcon /> },
            { id: 'chat', label: 'Chat', icon: <ChatIcon />, dot: 'streaming' },
            { id: 'tasks', label: 'Tasks', icon: <TasksIcon />, badge: { count: 3, tone: 'attention' },
              children: [{ id: 'tasks-mine', label: 'Assigned to me' }, { id: 'tasks-review', label: 'In review' }] },
            { id: 'files', label: 'Files', icon: <FilesIcon />, badge: { count: 12 } },
          ] },
        ]}
        footer={<ProfileMenu name="Ada Lovelace" onSettings={openSettings} />}
      />
      <main>{/* the content region; the sidebar stays beside it, never over it */}</main>
    </div>
  );
}

// Android (Jetpack Compose). There is NO side rail on Android: the persistent nav
// lives as TOP CHROME inside com.nockerl.app.core.ui.MainScaffold (project + session
// rows that collapse under the title bar), not a vertical sidebar. The honest
// equivalent of the sidebar's section + selected-row vocabulary is that chrome:
import com.nockerl.app.core.ui.ProjectRow
import com.nockerl.app.core.ui.TopChromeBoundary
import com.nockerl.app.chat.ui.SessionChipsBar

// Inside MainScaffold's stacked top chrome:
ProjectRow(
    projectName = state.projectName,
    isWorkspaceScoped = state.isWorkspaceScoped,
    onOpenPicker = viewModel::openProjectPicker,   // the "sections" entry point
    onOpenFiles = viewModel::openFiles,
    onOpenTasks = viewModel::openTasks,
)
SessionChipsBar(/* horizontally-scrollable destinations; selected = cyan chip */)
TopChromeBoundary(                                 // 1.5dp cyan line + grab handle
    collapsed = headerCollapsed,
    onCollapsedChange = { headerCollapsed = it },  // collapse, but UP, not to a rail
)
// A vertical NavigationRail / PermanentNavigationDrawer is not used today; see drift.

// macOS SwiftUI. The ROW ships as `NockerlNavRow`, built to the NockerlNavItem canon.
// The sidebar SHELL stays app-side (a translucent panel reading the app's router) until
// a Swift nav-surface ships. Voice's hand-rolled SidebarRow has been retired.
//
// Scope: this sidebar belongs to one window, not to the app. Voice is menu-bar-first, so
// closing the window leaves a native status-item menu as the always-on navigation. That
// menu is a macOS affordance the framework deliberately does not model.
import NockerlDesign

// Width is a token, never a literal. `containerXs` resolves to 216pt.
private let sidebarWidth: CGFloat = NockerlSize.containerXs

// The palette resolves per color scheme rather than reading a global.
private var palette: NockerlPalette { NockerlPalette.resolve(effectiveScheme) }

private var sidebar: some View {
    VStack(alignment: .leading, spacing: 3) {
        // The brand slot is the packaged lockup at its default mark height, never the
        // mark plus a separate text run.
        HStack(spacing: 0) {
            NockerlLockup(product: "Voice")
            Spacer(minLength: 0)
        }
        .padding(.horizontal, 16)
        // macOS only: the window hides its title bar, so the brand clears the traffic
        // lights that float over the top-left corner. The web inherits none of this.
        .padding(.top, 50)
        .padding(.bottom, 16)

        ForEach(AppSection.navItems) { section in
            NockerlNavRow(section.title, selected: router.section == section) {
                router.section = section
            } icon: {
                Image(systemName: section.icon)
            }
            .padding(.horizontal, NockerlSpace.space2)  // padding rides the row, not the stack
        }
        Spacer(minLength: 0)
        // Settings is a peer destination held out of the main list and pinned, not a
        // separate footer vocabulary: same row component, same selected treatment.
        NockerlNavRow(AppSection.settings.title, selected: router.section == .settings) {
            router.section = .settings
        } icon: { Image(systemName: AppSection.settings.icon) }
            .padding(.horizontal, NockerlSpace.space2)
            .padding(.bottom, 14)
    }
    .frame(width: sidebarWidth, alignment: .leading)
    .background(palette.canvas.opacity(0.3))            // translucent: the facet field reads through
    .overlay(alignment: .trailing) { Rectangle().fill(palette.cardHairline).frame(width: 1) }
}

Why the panel is translucent. One background owns the whole window, and the sidebar is a translucent plane floating on top of it rather than an opaque panel with its own fill. That is the transferable principle. Voice keeps the tint at canvas opacity 0.3 and deliberately declined the heavier surface.translucency.sidebar token, which would thicken the veil until the faceted field stopped reading through. The hidden title bar and the traffic-light clearance above are macOS-only staging for that same effect.

Parameters

Prop	Type	Default	Description
`sections` *	`NavSection[]`		Grouped nav: `{ label, items }`. Each item is `{ id, label, icon, badge?, dot?, children? }` and renders as one focusable button. Grouping is framework-original and ships on no platform yet: the Swift sidebar is a flat list.
`selected` *	`string`		Active destination `id` (a leaf, meaning a child id when a sub-item is active). Selection reads by outline (law §6): accent border + accent ink + the icon, with no wash and never a stripe.
`onSelect` *	`(id: string) => void`		Fired when a (leaf) item is activated: click / Enter / Space.
`focus + keyboard` *	`behavior`		Every row stays in the focus chain and shows a visible focus ring, drawn with `outline` on `:focus-visible` (never a colored shadow, law §1). The shell owns roving `tabindex`, not the row: one row is tabbable at a time, arrow keys move between rows, `Home` / `End` jump to the ends, and `Enter` / `Space` activate. Full keyboard operability is law §14, so the macOS focus stance is prohibited here.
`collapsed`	`boolean`	`false`	Collapses the sidebar to the icon-only rail; labels + counts hide and each item exposes its label via tooltip / `aria-label`. Framework-original, not yet on Swift, whose panel is a fixed width with no rail.
`onToggleCollapse`	`() => void`		Toggles `collapsed` from the rail button. Framework-original, not yet on Swift.
`badge`	`{ count: number; tone?: 'neutral' \| 'attention' }`		Per-item trailing count. `neutral` = mono chip; `attention` = warm count (status signal). Right-aligned; collapses to a corner dot on the rail. Framework-original, not yet on Swift.
`children`	`NavSubItem[]`		Nested sub-items on an item, which turn its row into an expandable disclosure (`aria-expanded`), indented under the parent. Framework-original, not yet on Swift: `NockerlNavRow` is deliberately a strict subset with no children, chevron, or expansion state.
`footer`	`ReactNode`		Pinned to the bottom. The settings entry is a peer destination held out of the main list, rendered by the same row component with the same selected treatment, so no separate footer vocabulary is needed. The profile (avatar + name) is framework-original and ships nowhere today.

There is no Android sidebar component. The persistent nav is top chrome composed inside MainScaffold; these are the real load-bearing parameters of that chrome (the honest equivalent of the sidebar’s sections + selected-row + collapse).

Parameter	Type	Description
`ProjectRow.projectName` *	`String`	The active project, the chrome counterpart of the sidebar brand / section header.
`ProjectRow.onOpenPicker` *	`() -> Unit`	Opens the project picker sheet, the entry point to switch the nav scope.
`ProjectRow.onOpenFiles / onOpenTasks` *	`() -> Unit`	Destination buttons (Files / Tasks) → their bottom sheets (the nav items).
`SessionChipsBar`	`@Composable`	Horizontally-scrollable session destinations; the selected chip reads cyan (the selected-row equivalent).
`TopChromeBoundary.collapsed` *	`Boolean`	Whether the project + session rows collapse UP under the title bar, not into a vertical rail.
`TopChromeBoundary.onCollapsedChange` *	`(Boolean) -> Unit`	Drag / tap the 1.5dp cyan boundary handle to collapse / expand the chrome.

The ROW ships as NockerlNavRow. The sidebar SHELL stays app-side (a translucent panel reading the app’s router).

The state ladder. NockerlNavRow carries no wash on any state, which is the ratified “state by outline, not fill” position:

Rest: onChromeMuted ink at light weight, no border.
Hover (unselected only): the ink raises to onChrome and a neutral gray divider hairline border appears. Never cyan, because cyan is reserved for selection.
Selected: a thin accentPrimary border at 45%, accent ink, and a medium label weight. The leading icon stays, and there is no left rail and no stripe.

Weight is a selection signal here, so the resting weight is light and only the selected row steps up. It steps up to medium and no further: the type ramp caps at 500, so semibold is out of bounds.

Row metrics are the canon’s: min-height 40, padding 12/8/8, radius control. Press feedback is a 0.985 scale, a transform rather than a fill change.

Parameter	Type	Default	Description
`label` *	`String`		The destination name, also the row’s accessible name.
`selected`	`Bool`	`false`	Active destination (law §6): a thin accent border at `@0.45` + accent ink + a medium label weight, and no wash. The icon stays (never a check swap). Never a left rail and never a stripe.
`action` *	`() -> Void`		Whole-row tap: the row is ONE button with one accessible name.
`icon`	`@ViewBuilder`		Leading glyph slot (an SF Symbol `Image` or any view) in the canonical 20pt slot, tinted with the row’s ink. Omit for a label-only row (no phantom slot).
`focus (macOS only)`	`behavior`		Rows leave the focus chain (`focusable(false)` + `focusEffectDisabled`, macOS 14+). This is a macOS accommodation, not a cross-platform stance: Full Keyboard Access is off by default there, so a mouse-driven sidebar loses nothing. It must never be carried to the web, where it would put primary navigation out of reach of keyboard and assistive-technology users and fail law §14. The Swift sidebar also implements no arrow-key traversal; the keyboard route on macOS is the menu bar.

Cross-platform drift

The sidebar is the persistent, in-layout nav column, the inline role of the ONE nav-surface: NockerlNavSurface (= NockerlDrawer) is a single edge-anchored surface with mode: inline | overlay. inline is this persistent rail; overlay is the drawer (a scrim panel that opens / closes). App shell composes ONE nav-surface, not two. The sidebar never floats over content and never dims it. Its rail chrome (grouped sections, collapse-to-rail, footer) is the reference inline nav content, and the shell-level convergence lands with App shell.

Platforms are allowed to diverge while the migration runs. What follows is the honest state today, not a defect list.

Selection reads by outline on every platform. Accent border, accent ink, and the leading icon, with no wash, no left rail, and no stripe (law §6). Both the Swift row and the web row now carry it; the soft cyan wash the web once used is gone.
Hover on an already-selected row differs on purpose. Swift answers nothing: on macOS a selected sidebar row is inert under the pointer, Voice ships that, and it is approved. The web brightens the row’s existing cyan edge to full strength instead, because a pointer-first surface that answers nothing on hover reads as disabled. It reuses the channel selection already owns rather than adding a wash, so law §6 still holds, and a border colour is interpolatable, so law §7 does too. This is the platform behaviour honoured per law §9, not drift: the learning transfers, the macOS habit does not.
Android has no side rail. Voice and web use a vertical sidebar; Android’s persistent nav is top chrome (project + session rows that collapse up under the title bar). A NavigationRail / PermanentNavigationDrawer is not used today.
Collapse: web collapses to an icon-only rail (with tooltips). The Swift panel is a fixed containerXs width with no rail, and Android collapses the chrome upward, not sideways. Collapse is framework-original and has not shipped on Swift.
Grouped sections, sub-items, counts, and the profile footer are framework-original. None has shipped on Swift, whose sidebar is a flat list of five destinations. They are kept here as the reference web pattern, not reported as harvested from a shipping app.
Scope differs. The Swift sidebar belongs to one window, not to the app: Voice is menu-bar-first, and a native status-item menu remains after the window closes. That menu is a macOS affordance the framework does not model, and the web has no equivalent.
Keyboard support does not transfer. The Swift rows leave the focus chain and have no arrow-key traversal, which is defensible on macOS and prohibited on the web. See the Swift focus row above.