@titan-design/react-ui 0.12.0 → 0.13.0

package/src/components/shell/BrandLockup.stories.tsx

@@ -1,22 +1,37 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { Surface } from '../ui/surface'
+import { Typography } from '../custom/Typography'
+import { StarIcon } from '../icons'
 import { BrandLockup } from './BrandLockup'
+import { brandKeys } from './brands'
 
 const meta: Meta<typeof BrandLockup> = {
   title: 'Shell/BrandLockup',
   component: BrandLockup,
-  tags: ['autodocs'],
-  args: { subtitle: 'wall dashboard', showSubtitle: true },
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  args: { brand: 'voltras', showSubtitle: true },
   argTypes: {
+    brand: { control: 'select', options: brandKeys },
     subtitle: { control: 'text' },
+    wordmark: { control: 'text' },
+    accentClassName: { control: 'text' },
     showSubtitle: { control: 'boolean' },
+    mark: { control: false },
   },
   parameters: {
     docs: {
       description: {
         component:
-          '**Molecule.** Composes [VoltrasMark](?path=/docs/foundations-icons--docs) (icon) + ' +
-          '[Typography](?path=/docs/foundations-typography--docs) (wordmark + subtitle). ' +
-          'Toggle `showSubtitle` to see the responsive collapse.',
+          '**Molecule.** Composes an [icon](?path=/docs/foundations-icons--docs) mark + ' +
+          '[Typography](?path=/docs/foundations-typography--docs) (wordmark + subtitle).\n\n' +
+          '**Generic over the app (AW-132).** Pick a `brand` preset, or override `mark` / ' +
+          '`wordmark` / `accentClassName` / `subtitle` for an app that has no preset yet. ' +
+          "Accents come from `data-*` rather than `status-*`: `data-*` is the library's set of " +
+          'distinct, CVD-checked hues with no semantic load, which is what a per-app identity ' +
+          'accent needs. Voltras keeps the real `brand-primary` token.\n\n' +
+          '**Try it:** switch `brand` in the **Controls**, or toggle `showSubtitle` to see the ' +
+          'responsive collapse.',
       },
     },
   },
@@ -25,3 +40,49 @@ export default meta
 type Story = StoryObj<typeof BrandLockup>
 
 export const Default: Story = {}
+
+/** Every app likely to mount this shell, in the chrome band's own surface. */
+export const BrandVariants: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The five branding presets. Each is a mark, a wordmark, a semantic accent token and a ' +
+          'default subtitle — nothing else in the shell changes between them.',
+      },
+    },
+  },
+  render: () => (
+    <Surface level="elevated" className="gap-4 p-5">
+      {brandKeys.map((brand) => (
+        <View key={brand} className="gap-1">
+          <Typography variant="microLabel" color="tertiary">
+            {brand}
+          </Typography>
+          <BrandLockup brand={brand} />
+        </View>
+      ))}
+    </Surface>
+  ),
+}
+
+/** Collapsed subtitle — what every brand looks like below ~1024px. */
+export const BrandVariantsCollapsed: Story = {
+  render: () => (
+    <Surface level="elevated" className="gap-4 p-5">
+      {brandKeys.map((brand) => (
+        <BrandLockup key={brand} brand={brand} showSubtitle={false} />
+      ))}
+    </Surface>
+  ),
+}
+
+/** An app with no preset: supply mark, wordmark, accent and subtitle directly. */
+export const CustomBrand: Story = {
+  args: {
+    mark: <StarIcon size={14} color="currentColor" />,
+    wordmark: 'HYPERFRAMES',
+    subtitle: 'renders',
+    accentClassName: 'text-data-6',
+  },
+}

package/src/components/shell/BrandLockup.test.tsx

@@ -2,9 +2,10 @@ import { describe, it, expect } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import { axe } from 'jest-axe'
 import { BrandLockup } from './BrandLockup'
+import { brandKeys, brandPresets } from './brands'
 
 describe('BrandLockup', () => {
-  it('renders the wordmark', () => {
+  it('renders the voltras wordmark by default', () => {
     render(<BrandLockup />)
     expect(screen.getByText('VOLTRAS')).toBeInTheDocument()
   })
@@ -16,6 +17,38 @@ describe('BrandLockup', () => {
     expect(screen.queryByText('/ wall dashboard')).not.toBeInTheDocument()
   })
 
+  it.each(brandKeys)('renders the %s preset wordmark and subtitle', (brand) => {
+    render(<BrandLockup brand={brand} />)
+    expect(screen.getByText(brandPresets[brand].wordmark)).toBeInTheDocument()
+    expect(screen.getByText(`/ ${brandPresets[brand].subtitle}`)).toBeInTheDocument()
+  })
+
+  it('lets an app override the preset parts', () => {
+    render(<BrandLockup brand="brain" wordmark="HYPERFRAMES" subtitle="renders" />)
+    expect(screen.getByText('HYPERFRAMES')).toBeInTheDocument()
+    expect(screen.getByText('/ renders')).toBeInTheDocument()
+    expect(screen.queryByText('BRAIN')).not.toBeInTheDocument()
+  })
+
+  // nativewind compiles className to style, so the rendered accent colour is not
+  // assertable in jsdom. Assert the token CHOICE instead: every preset picks a
+  // semantic `text-*` token, and no two apps share one.
+  it('gives every brand a distinct semantic accent token', () => {
+    const accents = brandKeys.map((brand) => brandPresets[brand].accentClassName)
+    accents.forEach((accent) => expect(accent).toMatch(/^text-(brand|data)-/))
+    expect(new Set(accents).size).toBe(accents.length)
+  })
+
+  // The nav's active bar needs the accent as a background, and a mismatched pair
+  // would render a lockup and an active nav item in two different hues.
+  it('pairs every accent with the same token as a background', () => {
+    brandKeys.forEach((brand) => {
+      const { accentClassName, accentBarClassName } = brandPresets[brand]
+      expect(accentBarClassName).toMatch(/^bg-(brand|data)-/)
+      expect(accentBarClassName).toBe(accentClassName.replace(/^text-/, 'bg-'))
+    })
+  })
+
   it('has no accessibility violations', async () => {
     const { container } = render(<BrandLockup />)
     expect(await axe(container)).toHaveNoViolations()

package/src/components/shell/BrandLockup.tsx

@@ -1,10 +1,19 @@
+import type { ReactNode } from 'react'
 import { View, type ViewProps } from 'react-native'
 import { cn } from '../../utils/cn'
 import { Typography } from '../custom/Typography'
-import { VoltrasMark } from '../icons'
+import { brandPresets, type BrandKey } from './brands'
 
 export interface BrandLockupProps extends ViewProps {
-  /** The "/ subtitle" that follows the wordmark. Default "wall dashboard". */
+  /** Which app's identity to render. Defaults to `voltras`. */
+  brand?: BrandKey
+  /** Replace the preset's mark glyph. */
+  mark?: ReactNode
+  /** Replace the preset's wordmark. */
+  wordmark?: string
+  /** Replace the preset's accent — a semantic `text-*` token class for the mark. */
+  accentClassName?: string
+  /** The "/ subtitle" that follows the wordmark. Defaults to the brand's own. */
   subtitle?: string
   /** Show the subtitle. Hidden at tablet width and below (S1-Q4 responsive). */
   showSubtitle?: boolean
@@ -12,34 +21,41 @@ export interface BrandLockupProps extends ViewProps {
 }
 
 /**
- * Product identity lockup for the top bar: ◇ mark + VOLTRAS wordmark + optional
- * subtitle. Composes the VoltrasMark icon + Typography. S1 · BrandLockup.
+ * Product identity lockup for the top bar: mark + wordmark + optional subtitle.
+ * Generic over the app: pick a `brand` preset, or override `mark` / `wordmark` /
+ * `accentClassName` / `subtitle` piecemeal for an app that has no preset yet.
+ * Composes an icon primitive + Typography. S1 · BrandLockup.
  */
 export function BrandLockup({
-  subtitle = 'wall dashboard',
+  brand = 'voltras',
+  mark,
+  wordmark,
+  accentClassName,
+  subtitle,
   showSubtitle = true,
   className,
   ...props
 }: BrandLockupProps) {
+  const preset = brandPresets[brand]
+  const resolvedSubtitle = subtitle ?? preset.subtitle
+
   return (
     <View className={cn('flex-row items-center gap-[7px]', className)} {...props}>
-      <View className="text-brand-primary">
-        <VoltrasMark size={14} color="currentColor" />
-      </View>
+      <View className={accentClassName ?? preset.accentClassName}>{mark ?? preset.mark}</View>
       <Typography
         variant="button"
         color="primary"
         className="text-[12px] font-extrabold tracking-[1.5px]"
       >
-        VOLTRAS
+        {wordmark ?? preset.wordmark}
       </Typography>
-      {showSubtitle && subtitle ? (
+      {showSubtitle && resolvedSubtitle ? (
         <Typography
           variant="button"
           color="tertiary"
           className="text-[10px] font-semibold tracking-[0.4px]"
         >
-          / {subtitle}
+          / {resolvedSubtitle}
         </Typography>
       ) : null}
     </View>

package/src/components/shell/NavItem.stories.tsx

@@ -1,12 +1,12 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
-import { View } from 'react-native'
 import { NavItem } from './NavItem'
 import { ActivityIcon } from '../icons'
+import { Surface } from '../ui/surface'
 
 const meta: Meta<typeof NavItem> = {
   title: 'Shell/NavItem',
   component: NavItem,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:candidate', '!status:review'],
   args: { label: 'Live', active: false, live: false },
   argTypes: {
     label: { control: 'text' },
@@ -17,9 +17,9 @@ const meta: Meta<typeof NavItem> = {
   },
   decorators: [
     (Story) => (
-      <View className="w-[60px] items-center bg-background-base py-2">
+      <Surface level="background" className="w-[60px] items-center py-2">
         <Story />
-      </View>
+      </Surface>
     ),
   ],
   parameters: {

package/src/components/shell/NavItem.test.tsx

@@ -32,4 +32,21 @@ describe('NavItem', () => {
     const { container } = render(<NavItem icon={icon} label="Live" live />)
     expect(container.firstChild).toBeInTheDocument()
   })
+
+  // nativewind compiles className to style, so jsdom cannot see the accent colour.
+  // Assert an app-supplied accent leaves the rest of the active state intact; the
+  // colour itself is guarded by the paired-token test in BrandLockup.test.
+  it('keeps the active state when an app supplies its own accent', () => {
+    render(
+      <NavItem
+        icon={icon}
+        label="Graph"
+        active
+        accentClassName="text-data-3"
+        accentBarClassName="bg-data-3"
+      />
+    )
+    expect(screen.getByTestId('nav-item-accent')).toBeInTheDocument()
+    expect(screen.getByRole('tab', { name: 'Graph' })).toBeInTheDocument()
+  })
 })

package/src/components/shell/NavItem.tsx

@@ -8,13 +8,17 @@ export interface NavItemProps {
   icon: ReactNode
   /** Short label shown under the glyph (uppercased for display; used as the accessible name). */
   label: string
-  /** Active category → left accent bar + brand-colored glyph & label. */
+  /** Active category → left accent bar + accent-colored glyph & label. */
   active?: boolean
   /**
    * A set is running for this category while it is NOT the active view
    * (live-elsewhere) → a quiet muted-green label tint. Ignored when `active`.
    */
   live?: boolean
+  /** Semantic `text-*` token for the active glyph and label. Defaults to the Voltras brand. */
+  accentClassName?: string
+  /** Semantic `bg-*` token for the active bar. Pair it with `accentClassName`. */
+  accentBarClassName?: string
   onPress?: () => void
   className?: string
 }
@@ -23,20 +27,25 @@ export interface NavItemProps {
  * Shell S2 · NavItem — one category button in the {@link SideNav}: a 20px glyph
  * over an uppercase micro-label in a 46×46 target. The button spans the full 60px
  * rail so the active **left accent bar** sits flush to the rail's edge. States:
- * active = accent bar + `brand-primary`; `live` (while not active) tints only the
+ * active = accent bar + the accent token; `live` (while not active) tints only the
  * label `status-success-dark` (the glyph stays dim); otherwise dim `text-tertiary`.
+ *
+ * The accent follows the mounting app's brand, so a Brain shell reads yellow
+ * throughout rather than showing a Voltras-orange active item under its own lockup.
  */
 export function NavItem({
   icon,
   label,
   active = false,
   live = false,
+  accentClassName = 'text-brand-primary',
+  accentBarClassName = 'bg-brand-primary',
   onPress,
   className,
 }: NavItemProps) {
-  const glyphColor = active ? 'text-brand-primary' : 'text-text-tertiary'
+  const glyphColor = active ? accentClassName : 'text-text-tertiary'
   const labelColor = active
-    ? 'text-brand-primary'
+    ? accentClassName
     : live
       ? 'text-status-live-muted'
       : 'text-text-tertiary'
@@ -52,7 +61,10 @@ export function NavItem({
       {active ? (
         <View
           testID="nav-item-accent"
-          className="absolute left-0 top-[13px] bottom-[13px] w-[3px] rounded-r-[3px] bg-brand-primary"
+          className={cn(
+            'absolute left-0 top-[13px] bottom-[13px] w-[3px] rounded-r-[3px]',
+            accentBarClassName
+          )}
         />
       ) : null}
       <View

package/src/components/shell/README.md

@@ -1,64 +1,113 @@
 # Shell chrome — component family
 
-The persistent dashboard frame (top bar, and — as the decomposition proceeds — side nav, session
-rail, drawers, pinned strip). Components live flat on disk; the tiering below is a documentation
-contract, not a directory layout, so promoting/composing is pure import churn.
+The persistent dashboard frame (top bar, side nav, and — as the decomposition proceeds — session
+rail, drawers, pinned strip). The tiering below is a documentation contract, not a directory
+layout, so promoting/composing is pure import churn.
 
 This README is the **index**: it maps each component's dependencies (**composes ↓**) and its consumers
 (**used-by ↑**) so you can navigate the tree in both directions and spot where a hand-rolled element
 should be reaching for an existing primitive instead. Storybook mirrors this tree under `Shell/TopBar/…`,
 and every component's autodocs page repeats its "Composes" links.
 
+## The generic/app split (AW-132)
+
+`shell/` is **generic**. It knows about a band, a rail, a brand lockup and a content region, and
+nothing about any one product. `shell/workout/` is the **workout app's** chrome, and it composes
+the generic family. The dependency arrow points one way only: nothing in `shell/` may import from
+`shell/workout/`, and a second app (audiobook, active-work, agent dashboards, brain) gets its own
+sibling directory rather than a new prop on `AppShell`.
+
+**The composition mechanism is the library's existing slot idiom** — named `ReactNode` props with a
+built-in default, the same shape as `Pill`'s `leading`/`trailing` and `SectionHeader`'s `trailing`.
+No second mechanism was introduced.
+
+| Slot                     | On          | Default                          | An app uses it to…                       |
+| ------------------------ | ----------- | -------------------------------- | ---------------------------------------- |
+| `TopBar.trailing`        | `TopBar`    | just the clock                   | put its own chrome in the right cluster  |
+| `TopBar.leading`         | `TopBar`    | `<BrandLockup brand=…>`          | replace the brand region outright        |
+| `AppShell.topBarTrailing` | `AppShell`  | —                                | pass chrome through to the default bar   |
+| `AppShell.topBar`        | `AppShell`  | `<TopBar brand=…>`               | swap the whole band                      |
+| `AppShell.nav`           | `AppShell`  | `<SideNav items=…>`              | swap the whole rail                      |
+| `AppShell.children`      | `AppShell`  | a placeholder                    | mount its page                           |
+
+`TopBar.trailing` takes an array as well as a node. **The bar interleaves its own vertical dividers
+between the items**, so an app supplies the controls and the shell keeps the divider rhythm from the
+S1 lock — the app never hand-places a `Divider`, and can't drift from it.
+
+Two things stopped being generic defaults and became the workout app's data:
+
+- `SideNav.items` is **required**. The four Live · Review · Plan · Body categories are
+  `workoutNavItems` in `shell/workout/`.
+- `BrandLockup` is generic over `brand` (five presets in `brands.tsx`), rather than hard-coding
+  the Voltras mark and wordmark.
+
 ## Specimen: `SideNav` (the second shell unit, S2)
 
 ```
 SideNav ...................... organism — the 60px left rail (Shell/SideNav)
-├─ NavItem ................... molecule × 4 (Live · Review · Plan · Body)
-│  ├─ icon ................... icons (shared primitive) — Activity/History/Layers/PersonStanding
+├─ NavItem ................... molecule × `items` (the app's own categories)
+│  ├─ icon ................... icons (shared primitive) — supplied per item
 │  └─ Typography ............. titan · button variant (uppercase micro-label)
-└─ (accent bar) .............. bg-brand-primary edge bar on the active item
+└─ (accent bar) .............. edge bar on the active item, in the app's brand accent
 ```
 
-Decisions locked 2026-07-08 (specimen `coordination/design-explorations/shell/S2-sidenav/`): lucide glyphs
+Decisions locked 2026-07-08 (specimen `sources/design/shell/S2-sidenav/`): lucide glyphs
 (activity · history · layers · figure) · **Plan** label (narrower than "Program") · active = **left accent
 bar** (short, centered on the icon+label) · **60px** icon+micro-label · live cue = **muted-green label**
 (`status-live-muted`) on the Live item while a set runs off-Live · four items, no footer, no top-nav. Fixed
 60px at every width (labels sit under the glyph). `SideNav` is presentational — `activeKey` / `onNavigate` /
-`liveKey`; the app owns routing + which key is live.
+`liveKey`; the app owns routing + which key is live. Those four categories are now
+`workoutNavItems` in `shell/workout/` (AW-132); the rail itself has no built-in set.
 
 ## Specimen: `TopBar` (the first shell unit, S1)
 
 ```
 TopBar ....................... organism — the chrome band (Shell/TopBar)
-├─ BrandLockup ............... molecule
-│  ├─ VoltrasMark ............ icons (shared primitive)
+├─ BrandLockup ............... molecule — default `leading`
+│  ├─ brand mark ............. icons (shared primitive) — per `brands.tsx` preset
 │  └─ Typography ............. titan · button variant
-├─ SessionStatePill .......... molecule  (= the reusable StatusPill)
-│  ├─ Indicator .............. titan · ping pulse + vivid color
-│  └─ Typography ............. titan · monoLabel
-├─ Divider ................... titan · bg-border-prominent
-├─ DeviceMenu ................ organism
-│  ├─ Popover ................ titan
-│  ├─ DeviceIndicator ........ molecule → BluetoothIcon (icons primitive)
-│  ├─ DeviceRow .............. molecule → Indicator + Typography (body2 / mono)
-│  └─ Typography ............. titan · monoLabel (header)
-├─ DateTime .................. titan · mono variant, live 24h clock
+├─ trailing[] ................ SLOT — app chrome, divider-interleaved by the bar
+├─ Divider ................... titan · bg-border-prominent (one per slot gap)
+├─ DateTime .................. titan · mono variant, live 24h clock (edge-pinned)
 └─ surfaceGradient.chrome .... theme · gradient primitive
 ```
 
-## Dependency map
+## Specimen: `WorkoutTopBar` (the same band, filled by the workout app)
+
+```
+WorkoutTopBar ................ organism — Shell/Workout/WorkoutTopBar
+└─ TopBar .................... generic band, brand="voltras"
+   └─ trailing[] ............. supplied by the workout app:
+      ├─ SessionStatePill .... molecule → Indicator + Typography (monoLabel)
+      └─ DeviceMenu .......... organism
+         ├─ Popover .......... titan
+         ├─ DeviceIndicator .. molecule → BluetoothIcon (icons primitive)
+         ├─ DeviceRow ........ molecule → Indicator + Typography (body2 / mono)
+         └─ Typography ....... titan · monoLabel (header)
+```
+
+## Dependency map — generic (`shell/`)
 
 | Component | Tier | Composes ↓ | Used-by ↑ |
 |---|---|---|---|
-| `SideNav` | organism | NavItem ×4, `components/icons` (Activity/History/Layers/PersonStanding) | dashboard app root *(planned)* |
+| `AppShell` | page shell | TopBar, SideNav, Surface | WorkoutShell, any app root |
+| `SideNav` | organism | NavItem × `items` | AppShell |
 | `NavItem` | molecule | icon, Typography | SideNav |
-| `TopBar` | organism | BrandLockup, SessionStatePill, Divider, DeviceMenu, DateTime, `surfaceGradient.chrome` | dashboard app root *(planned)* |
-| `BrandLockup` | molecule | VoltrasMark, Typography | TopBar |
-| `SessionStatePill` | molecule | Indicator, Typography | TopBar, **Live-view header** *(planned reuse)* |
-| `DeviceMenu` | organism | Popover, DeviceIndicator, DeviceRow, Typography | TopBar |
+| `TopBar` | organism | BrandLockup, Divider, DateTime, `surfaceGradient.chrome` | AppShell, WorkoutTopBar |
+| `BrandLockup` | molecule | a brand mark icon, Typography | TopBar |
+| `brands.tsx` | data | VoltrasMark / Headphones / Kanban / Bot / Brain icons | BrandLockup, TopBar, AppShell |
+
+## Dependency map — workout app (`shell/workout/`)
+
+| Component | Tier | Composes ↓ | Used-by ↑ |
+|---|---|---|---|
+| `WorkoutShell` | page shell | AppShell, WorkoutTopBar, workoutNavItems | dashboard app root |
+| `WorkoutTopBar` | organism | TopBar, SessionStatePill, DeviceMenu | WorkoutShell |
+| `SessionStatePill` | molecule | Indicator, Typography | WorkoutTopBar, **Live-view header** *(planned reuse)* |
+| `DeviceMenu` | organism | Popover, DeviceIndicator, DeviceRow, Typography | WorkoutTopBar |
 | `DeviceIndicator` | molecule | BluetoothIcon | DeviceMenu |
 | `DeviceRow` | molecule | Indicator, Typography | DeviceMenu |
-| `VoltrasMark` / `BluetoothIcon` | **`components/icons`** primitive | `SvgIcon` base | BrandLockup / DeviceIndicator (+ any consumer) |
+| `workoutNavItems` | data | Activity/History/Layers/PersonStanding icons | WorkoutShell |
 
 ## Shared substrates introduced here (reusable beyond the shell)
 
@@ -98,6 +147,20 @@ Every leaf now composes a primitive rather than hand-rolling it:
 - **Lint guardrails** — components may not inline `linear-gradient` (use `surfaceGradient`); shell + icons may
   not use raw hex (use tokens).
 
+**AW-132 shared substrate:** four brand marks added to `components/icons` (`HeadphonesIcon`,
+`KanbanIcon`, `BotIcon`, `BrainIcon`), so `brands.tsx` can carry a preset for every app expected to
+mount this shell. Brand accents come from `data-*` rather than `status-*`: `data-*` is the library's
+set of distinct, CVD-checked hues with no semantic load, which is what a per-app identity accent
+needs. Voltras keeps the real `brand-primary` token.
+
+**The nav accent is brand-level, not shell-level** (operator, Gate 2 2026-09-11). `SideNav`'s active
+item and its edge bar take the mounting app's accent, so a Brain shell reads yellow throughout
+rather than showing a Voltras-orange active item under a yellow lockup. `AppShell` threads it down
+from `brand`; a bare `SideNav` takes `accentClassName` / `accentBarClassName`. Each preset declares
+both as literals (`text-data-3` + `bg-data-3`) because Tailwind only emits classes it can see in the
+source — a name built at runtime is never generated — and a test asserts the pair always matches.
+Workout is unaffected: its accent *is* `brand-primary`.
+
 **S2 shared substrate:** four nav glyphs added to `components/icons` (`ActivityIcon`, `HistoryIcon`,
 `LayersIcon`, `PersonStandingIcon` — lucide-mirrored, like Dumbbell/Star), available system-wide.
 

package/src/components/shell/SideNav.stories.tsx

@@ -3,15 +3,20 @@ import { useArgs } from 'storybook/preview-api'
 import { View } from 'react-native'
 import { SideNav } from './SideNav'
 import { Typography } from '../custom/Typography'
+import { Surface } from '../ui/surface'
+import { BotIcon, BrainIcon, LayersIcon } from '../icons'
+import { workoutNavItems } from './workout'
+import { brandPresets } from './brands'
 
 const meta: Meta<typeof SideNav> = {
   title: 'Shell/SideNav',
   component: SideNav,
-  tags: ['autodocs'],
-  args: { activeKey: 'live', liveKey: null },
+  tags: ['autodocs', 'status:candidate', '!status:review'],
+  args: { items: workoutNavItems, activeKey: 'live', liveKey: null },
   argTypes: {
     activeKey: { control: 'select', options: ['live', 'review', 'program', 'body'] },
     liveKey: { control: 'select', options: [null, 'live', 'review', 'program', 'body'] },
+    items: { control: false },
     onNavigate: { action: 'navigate' },
   },
   // Interactive AND Controls-synced: clicking a category writes `activeKey` back to the
@@ -35,14 +40,14 @@ const meta: Meta<typeof SideNav> = {
   // stretches with the viewport (resize the canvas height to see it hold).
   decorators: [
     (Story) => (
-      <View className="min-h-screen flex-row bg-background-default">
+      <Surface level="base" className="min-h-screen flex-row">
         <Story />
         <View className="flex-1 items-center justify-center">
           <Typography variant="body2" color="tertiary">
             main viewport
           </Typography>
         </View>
-      </View>
+      </Surface>
     ),
   ],
   parameters: {
@@ -50,9 +55,11 @@ const meta: Meta<typeof SideNav> = {
     docs: {
       description: {
         component:
-          '**Organism** (shell region). The persistent 60px left rail switching Live · Review · Plan · ' +
-          'Body. Composes [NavItem](?path=/docs/shell-navitem--docs) × the four categories + the ' +
-          'shared [icon set](?path=/docs/foundations-icons--docs). Presentational — drive it with `activeKey` / ' +
+          '**Organism** (shell region). The persistent 60px left rail that switches the main viewport ' +
+          "between an app's categories. Composes [NavItem](?path=/docs/shell-navitem--docs) × `items` + the " +
+          'shared [icon set](?path=/docs/foundations-icons--docs). It has no built-in categories: `items` is ' +
+          'required, and each app supplies its own (the workout set is `workoutNavItems`). ' +
+          'Presentational — drive it with `activeKey` / ' +
           '`onNavigate` / `liveKey`. Active = left accent bar; `liveKey` (when not active) tints that ' +
           'label a muted green.\n\n' +
           '**Try it:** stories render in a full-height shell frame — the rail pins to the left edge and ' +
@@ -79,3 +86,27 @@ export const LiveElsewhere: Story = {
     },
   },
 }
+
+/** A different app's categories and accent in the same rail (AW-132). */
+export const AnotherApp: Story = {
+  args: {
+    items: [
+      { key: 'notes', label: 'Notes', icon: <LayersIcon size={20} color="currentColor" /> },
+      { key: 'graph', label: 'Graph', icon: <BrainIcon size={20} color="currentColor" /> },
+      { key: 'agents', label: 'Agents', icon: <BotIcon size={20} color="currentColor" /> },
+    ],
+    activeKey: 'graph',
+    accentClassName: brandPresets.brain.accentClassName,
+    accentBarClassName: brandPresets.brain.accentBarClassName,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The brain app's three categories in its own accent. Same rail, same states, different " +
+          '`items` and accent. `AppShell` passes the accent down from its `brand`; drive the bare ' +
+          'rail with `accentClassName` / `accentBarClassName`.',
+      },
+    },
+  },
+}

package/src/components/shell/SideNav.test.tsx

@@ -1,11 +1,19 @@
 import { describe, it, expect, vi } from 'vitest'
 import { render, screen, fireEvent, within } from '@testing-library/react'
 import { axe } from 'jest-axe'
-import { SideNav } from './SideNav'
+import { SideNav, type SideNavItem } from './SideNav'
+
+// A generic four-category set — the rail has no built-in categories any more.
+const items: SideNavItem[] = [
+  { key: 'live', label: 'Live', icon: null },
+  { key: 'review', label: 'Review', icon: null },
+  { key: 'program', label: 'Plan', icon: null },
+  { key: 'body', label: 'Body', icon: null },
+]
 
 describe('SideNav', () => {
-  it('renders the four default categories as tabs in a tablist', () => {
-    render(<SideNav activeKey="live" />)
+  it('renders the supplied categories as tabs in a tablist', () => {
+    render(<SideNav items={items} activeKey="live" />)
     expect(screen.getByRole('tablist')).toBeInTheDocument()
     ;['Live', 'Review', 'Plan', 'Body'].forEach((name) => {
       expect(screen.getByRole('tab', { name })).toBeInTheDocument()
@@ -13,7 +21,7 @@ describe('SideNav', () => {
   })
 
   it('shows the accent bar only on the active category', () => {
-    render(<SideNav activeKey="program" />)
+    render(<SideNav items={items} activeKey="program" />)
     expect(screen.getAllByTestId('nav-item-accent')).toHaveLength(1)
     expect(
       within(screen.getByRole('tab', { name: 'Plan' })).getByTestId('nav-item-accent')
@@ -25,13 +33,13 @@ describe('SideNav', () => {
 
   it('reports the tapped key via onNavigate', () => {
     const onNavigate = vi.fn()
-    render(<SideNav activeKey="live" onNavigate={onNavigate} />)
+    render(<SideNav items={items} activeKey="live" onNavigate={onNavigate} />)
     fireEvent.click(screen.getByRole('tab', { name: 'Body' }))
     expect(onNavigate).toHaveBeenCalledWith('body')
   })
 
   it('keeps the active item as active even when it is also the liveKey (no double-state)', () => {
-    render(<SideNav activeKey="live" liveKey="live" />)
+    render(<SideNav items={items} activeKey="live" liveKey="live" />)
     // active wins: exactly one accent bar, on Live (the live cue never applies to the active view)
     expect(screen.getAllByTestId('nav-item-accent')).toHaveLength(1)
     expect(
@@ -39,13 +47,13 @@ describe('SideNav', () => {
     ).toBeInTheDocument()
   })
 
-  it('accepts custom items', () => {
+  it('accepts an app-specific item set', () => {
     render(<SideNav activeKey="a" items={[{ key: 'a', label: 'Alpha', icon: null }]} />)
     expect(screen.getByRole('tab', { name: 'Alpha' })).toBeInTheDocument()
   })
 
   it('has no accessibility violations', async () => {
-    const { container } = render(<SideNav activeKey="live" />)
+    const { container } = render(<SideNav items={items} activeKey="live" />)
     expect(await axe(container)).toHaveNoViolations()
   })
 })