Sidebar anatomy

The kit rail as the apps assemble it: grouped nav, a collapse that frees room without losing discovery, and an identity footer.

What this solves

Discovery and gestalt hierarchy. Grouping and per-group counts let a reader find a destination without scanning every item, and the collapsed rail trades labels for room without losing the ability to find anything, since every link keeps a tooltip.

Use it when

The primary workspace rail in either app.Speedway's WorkspaceNav (WorkspaceNav.tsx:320-352), the kit Sidebar with the app's own nav data.
A narrow viewport or an explicit collapse.Any page below the lg breakpoint: the rail always renders icon-only there, whatever collapsed says.

Rendered

Fixture data; check both themes.

patterns/sidebar-anatomy/example.tsxCopy this into a fresh route and it renders as above.

1"use client";
2
3import { useState } from "react";
4import { Sidebar, type NavGroup } from "@versable-git/ui";
5
6// The rail as the apps assemble it: grouped nav, a per-group count that
7// renders only when known, a per-item count that renders only when known,
8// and an identity row riding the footer slot. Collapse is driven by the
9// kit's own toggle, the same hamburger a real rail exposes.
10const nav: NavGroup[] = [
11  {
12    label: "Catalog",
13    count: 15,
14    items: [
15      { label: "Home", href: "#home", Icon: "Dashboard" },
16      { label: "Jobs", href: "#jobs", Icon: "Table" },
17      { label: "Review", href: "#review", Icon: "Warning" },
18    ],
19  },
20  {
21    label: "Modules",
22    items: [
23      { label: "Workflow", href: "#workflow", Icon: "Refresh" },
24      { label: "Scrape", href: "#scrape", Icon: "CloudUpload" },
25    ],
26  },
27];
28
29const itemCounts: Record<string, number> = { "#jobs": 12, "#review": 3 };
30
31export function SidebarAnatomy() {
32  const [collapsed, setCollapsed] = useState(false);
33
34  return (
35    <div
36      className={`border-base-300 bg-base-100 h-96 overflow-hidden rounded-lg border transition-[width] duration-200 ${collapsed ? "w-16" : "w-64"}`}
37    >
38      <Sidebar
39        nav={nav}
40        activeHref="#jobs"
41        collapsed={collapsed}
42        onToggleCollapsed={() => setCollapsed((v) => !v)}
43        renderLink={({ href, className, children, ...rest }) => (
44          <a href={href} className={className} {...rest}>
45            <span className="flex w-full items-center justify-between gap-2">
46              <span className="flex items-center gap-2">{children}</span>
47              {itemCounts[href ?? ""] != null ? (
48                <span className="text-base-content/45 text-xs tabular-nums">{itemCounts[href ?? ""]}</span>
49              ) : null}
50            </span>
51          </a>
52        )}
53        footer={
54          <span className="flex items-center gap-2 px-1">
55            <span className="bg-primary/15 text-primary flex size-7 items-center justify-center rounded-full text-xs font-semibold">
56              JD
57            </span>
58            <span className="flex min-w-0 flex-col">
59              <span className="truncate text-sm font-medium">Jordan Diaz</span>
60              <span className="text-base-content/50 truncate text-xs">jordan@acme.test</span>
61            </span>
62          </span>
63        }
64      />
65    </div>
66  );
67}
68

Where it ships

speedway/app/components/WorkspaceNav.tsx:320-352the kit Sidebar carrying the app's NavGroup data, a router-aware renderLink, and the account footer
speedway/app/components/WorkspaceNav.tsx:71-99the RailLink adapter: prefetch on intent, and revalidate instead of navigate when clicking the current page
speedway/app/components/WorkspaceNav.tsx:104-131RailRow: the pending spinner appears only after a 120ms grace period

App-specific: The real renderLink is a router Link with prefetch and a pending spinner, counts come from live queries (no skeleton fallback, deliberately), and collapse state lives in an app context. The frame here bounds the rail for display; apps mount it in the shell.