@titan-design/react-ui 0.5.0 → 0.7.0

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

@@ -0,0 +1,26 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { DeviceIndicator } from './DeviceIndicator'
+
+describe('DeviceIndicator', () => {
+  it('renders each connection state', () => {
+    const states = ['connected', 'degraded', 'lost'] as const
+    states.forEach((status) => {
+      const { unmount, container } = render(<DeviceIndicator status={status} />)
+      expect(container.firstChild).toBeInTheDocument()
+      unmount()
+    })
+  })
+
+  it('exposes a button role and fires onPress when interactive', () => {
+    const onPress = vi.fn()
+    render(<DeviceIndicator onPress={onPress} />)
+    fireEvent.click(screen.getByRole('button', { name: 'Devices' }))
+    expect(onPress).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders the lost state (red glyph, no separate badge)', () => {
+    const { container } = render(<DeviceIndicator status="lost" />)
+    expect(container.firstChild).toBeInTheDocument()
+  })
+})

package/src/components/shell/DeviceIndicator.tsx

@@ -0,0 +1,52 @@
+import { View, Pressable, type ViewProps } from 'react-native'
+import { cn } from '../../utils/cn'
+import { BluetoothIcon } from '../icons'
+
+export type DeviceConnState = 'connected' | 'degraded' | 'lost'
+
+export interface DeviceIndicatorProps extends ViewProps {
+  /** Aggregate connection state (worst-of the bound devices) → glyph color. */
+  status?: DeviceConnState
+  /** Tap handler. When omitted the glyph is non-interactive (e.g. inside a PopoverTrigger). */
+  onPress?: () => void
+  /** Accessible label (names the glyph / the wrapping trigger button). */
+  label?: string
+  className?: string
+}
+
+// currentColor drives the stroke → color the wrapper's text token by state (vivid, matches LIVE).
+// The glyph color alone carries the fault (red on lost) — no separate alert badge.
+const statusTextClass: Record<DeviceConnState, string> = {
+  connected: 'text-status-success',
+  degraded: 'text-status-warning',
+  lost: 'text-status-error-vivid',
+}
+
+/**
+ * The device/BLE connection glyph — a color-coded bluetooth mark, no label.
+ * Opens the DeviceMenu when tapped. S1 · DeviceIndicator.
+ */
+export function DeviceIndicator({
+  status = 'connected',
+  onPress,
+  label = 'Devices',
+  className,
+  ...props
+}: DeviceIndicatorProps) {
+  const Wrapper = onPress ? Pressable : View
+  return (
+    <Wrapper
+      accessibilityLabel={label}
+      {...(onPress ? { onPress, accessibilityRole: 'button' } : {})}
+      className={cn(
+        'w-[26px] h-[28px] items-center justify-center rounded-[7px]',
+        statusTextClass[status],
+        className
+      )}
+      {...props}
+    >
+      {/* the SVG title names the wrapping trigger button (RNW drops aria-label on non-accessible Views) */}
+      <BluetoothIcon size={18} color="currentColor" title={label} />
+    </Wrapper>
+  )
+}

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

@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { DeviceMenu } from './DeviceMenu'
+import { type Device } from './DeviceRow'
+
+const DEVICES: Device[] = [
+  { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
+  { id: 'Voltra-9B1C', nickname: 'Right Cable', slot: 'R', state: 'connected' },
+  { id: 'Voltra-77E0', nickname: 'Spare', slot: null, state: 'available' },
+]
+
+const meta: Meta<typeof DeviceMenu> = {
+  title: 'Shell/DeviceMenu',
+  component: DeviceMenu,
+  tags: ['autodocs'],
+  args: { devices: DEVICES, isOpen: false },
+  argTypes: {
+    devices: { control: 'object' },
+    isOpen: { control: 'boolean' },
+    onOpenChange: { control: false },
+    onSelectDevice: { control: false },
+  },
+  decorators: [
+    (Story) => (
+      <View className="flex-row p-4 pb-48">
+        <Story />
+      </View>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Organism.** The device glyph + its dropdown. Composes ' +
+          '[Popover](?path=/docs/components-molecules-popover--docs) + ' +
+          '[DeviceIndicator](?path=/docs/shell-deviceindicator--docs) (trigger) + ' +
+          '[DeviceRow](?path=/docs/shell-devicerow--docs) (list) + ' +
+          '[Typography](?path=/docs/foundations-typography--docs) (header). Aggregates the bound devices ' +
+          '(worst-of) for the glyph state. Click the glyph, or toggle the `isOpen` control.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof DeviceMenu>
+
+export const Default: Story = {}

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

@@ -0,0 +1,40 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { DeviceMenu } from './DeviceMenu'
+import { type Device } from './DeviceRow'
+
+const devices: Device[] = [
+  { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
+  { id: 'Voltra-9B1C', nickname: 'Right Cable', slot: 'R', state: 'connected' },
+  { id: 'Voltra-77E0', nickname: 'Spare', slot: null, state: 'available' },
+]
+
+describe('DeviceMenu', () => {
+  it('renders the trigger glyph and opens the device list on click', () => {
+    render(<DeviceMenu devices={devices} />)
+    const trigger = screen.getByRole('button', { name: 'Devices' })
+    expect(screen.queryByText('Left Cable')).not.toBeInTheDocument()
+    fireEvent.click(trigger)
+    expect(screen.getByText('Left Cable')).toBeInTheDocument()
+    expect(screen.getByText(/2 bound · 1 available/)).toBeInTheDocument()
+  })
+
+  it('reports a controlled open state', () => {
+    render(<DeviceMenu devices={devices} isOpen />)
+    expect(screen.getByText('Right Cable')).toBeInTheDocument()
+  })
+
+  it('fires onSelectDevice when a row is tapped', () => {
+    const onSelectDevice = vi.fn()
+    render(<DeviceMenu devices={devices} isOpen onSelectDevice={onSelectDevice} />)
+    fireEvent.click(screen.getByText('Left Cable'))
+    expect(onSelectDevice).toHaveBeenCalledWith(expect.objectContaining({ id: 'Voltra-A3F2' }))
+  })
+
+  it('renders regardless of the aggregate worst-of state (degraded / lost bound device)', () => {
+    const degraded: Device[] = [{ id: 'D', nickname: 'Left', slot: 'L', state: 'degraded' }]
+    const lost: Device[] = [{ id: 'L', nickname: 'Left', slot: 'L', state: 'lost' }]
+    expect(render(<DeviceMenu devices={degraded} />).container.firstChild).toBeInTheDocument()
+    expect(render(<DeviceMenu devices={lost} />).container.firstChild).toBeInTheDocument()
+  })
+})

package/src/components/shell/DeviceMenu.tsx

@@ -0,0 +1,65 @@
+import { View } from 'react-native'
+import { cn } from '../../utils/cn'
+import { Typography } from '../custom/Typography'
+import { Popover, PopoverTrigger, PopoverContent } from '../ui/popover'
+import { DeviceIndicator, type DeviceConnState } from './DeviceIndicator'
+import { DeviceRow, type Device } from './DeviceRow'
+
+export interface DeviceMenuProps {
+  devices: Device[]
+  /** Controlled open state (optional — uncontrolled otherwise). */
+  isOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  onSelectDevice?: (device: Device) => void
+  className?: string
+}
+
+/** Aggregate the bound devices into a single glyph state (worst-of). */
+function aggregateStatus(devices: Device[]): DeviceConnState {
+  const bound = devices.filter((d) => d.slot)
+  if (bound.some((d) => d.state === 'lost')) return 'lost'
+  if (bound.some((d) => d.state === 'degraded')) return 'degraded'
+  return 'connected'
+}
+
+/**
+ * The device glyph + its dropdown of individual devices (availability, slot
+ * binding, id, connection state). Composes Popover + DeviceIndicator +
+ * DeviceRow. S1 · DeviceMenu.
+ */
+export function DeviceMenu({
+  devices,
+  isOpen,
+  onOpenChange,
+  onSelectDevice,
+  className,
+}: DeviceMenuProps) {
+  const status = aggregateStatus(devices)
+  const boundCount = devices.filter((d) => d.slot).length
+  const availCount = devices.filter((d) => !d.slot).length
+
+  return (
+    <Popover placement="bottom" isOpen={isOpen} onOpenChange={onOpenChange} className={className}>
+      <PopoverTrigger>
+        <DeviceIndicator status={status} />
+      </PopoverTrigger>
+      <PopoverContent className="right-0 left-auto mt-[10px] w-[326px] bg-surface-elevated border border-border-strong rounded-[10px] p-[7px]">
+        <Typography
+          variant="monoLabel"
+          color="tertiary"
+          className="text-[9px] tracking-[0.8px] px-2 pt-[6px] pb-2"
+        >
+          Devices — {boundCount} bound · {availCount} available
+        </Typography>
+        {devices.map((device, i) => (
+          <View key={device.id} className={cn(i > 0 && 'border-t border-border')}>
+            <DeviceRow
+              device={device}
+              onPress={onSelectDevice ? () => onSelectDevice(device) : undefined}
+            />
+          </View>
+        ))}
+      </PopoverContent>
+    </Popover>
+  )
+}

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

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { DeviceRow } from './DeviceRow'
+
+const meta: Meta<typeof DeviceRow> = {
+  title: 'Shell/DeviceRow',
+  component: DeviceRow,
+  tags: ['autodocs'],
+  args: {
+    device: { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
+  },
+  argTypes: {
+    device: { control: 'object' },
+    onPress: { control: false },
+  },
+  decorators: [
+    (Story) => (
+      <View className="w-[320px] bg-surface-elevated rounded-lg p-1">
+        <Story />
+      </View>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Molecule.** One device row: status dot · name · Bluetooth id. Composes ' +
+          '[Indicator](?path=/docs/components-atoms-indicator--docs) (status dot) + ' +
+          '[Typography](?path=/docs/foundations-typography--docs) (`body2` name, `mono` id). ' +
+          'Edit the `device` control (set `state` to `lost` / `available`, `slot` to `null`) to explore.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof DeviceRow>
+
+export const Default: Story = {}

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

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { DeviceRow, type Device } from './DeviceRow'
+
+const bound: Device = { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' }
+const unbound: Device = { id: 'Voltra-77E0', nickname: 'Spare', slot: null, state: 'available' }
+
+describe('DeviceRow', () => {
+  it('renders the device name and Bluetooth id', () => {
+    render(<DeviceRow device={bound} />)
+    expect(screen.getByText('Left Cable')).toBeInTheDocument()
+    expect(screen.getByText('Voltra-A3F2')).toBeInTheDocument()
+  })
+
+  it('omits the redundant status text and slot pill (dot + name carry it)', () => {
+    render(<DeviceRow device={bound} />)
+    expect(screen.queryByText('connected')).not.toBeInTheDocument()
+    expect(screen.queryByText('SLOT L')).not.toBeInTheDocument()
+  })
+
+  it('renders an unbound device by name', () => {
+    render(<DeviceRow device={unbound} />)
+    expect(screen.getByText('Spare')).toBeInTheDocument()
+    expect(screen.getByText('Voltra-77E0')).toBeInTheDocument()
+  })
+
+  it('renders every connection state without crashing', () => {
+    const states = ['connected', 'available', 'degraded', 'lost'] as const
+    states.forEach((state) => {
+      const { unmount, container } = render(
+        <DeviceRow device={{ id: 'X', nickname: 'Cable', slot: 'L', state }} />
+      )
+      expect(container.firstChild).toBeInTheDocument()
+      unmount()
+    })
+  })
+})

package/src/components/shell/DeviceRow.tsx

@@ -0,0 +1,58 @@
+import { View, Pressable, type ViewProps } from 'react-native'
+import { cn } from '../../utils/cn'
+import { Indicator, type IndicatorColor } from '../ui/indicator'
+import { Typography } from '../custom/Typography'
+
+export type DeviceRowState = 'connected' | 'available' | 'degraded' | 'lost'
+
+export interface Device {
+  /** Stable device id (e.g. "Voltra-A3F2"). */
+  id: string
+  /** User-assigned slot/device name (e.g. "Left Cable"). */
+  nickname: string
+  /** Bound slot, or null when unbound/available (used for the menu's bound/available tally). */
+  slot?: 'L' | 'R' | null
+  /** Connection/availability state → the status dot color. */
+  state: DeviceRowState
+}
+
+export interface DeviceRowProps extends ViewProps {
+  device: Device
+  onPress?: () => void
+  className?: string
+}
+
+const stateColor: Record<DeviceRowState, IndicatorColor> = {
+  connected: 'success',
+  available: 'info',
+  degraded: 'warning',
+  lost: 'error-vivid',
+}
+
+/**
+ * One device in the DeviceMenu: status dot · name · Bluetooth id. The dot color
+ * carries the connection state (no redundant status text); the name is the one
+ * slot label (no duplicate slot badge). S1 · DeviceRow.
+ */
+export function DeviceRow({ device, onPress, className, ...props }: DeviceRowProps) {
+  const Wrapper = onPress ? Pressable : View
+  return (
+    <Wrapper
+      {...(onPress ? { onPress, accessibilityRole: 'button' } : {})}
+      className={cn('flex-row items-center gap-[10px] px-2 py-[9px] rounded-[7px]', className)}
+      {...props}
+    >
+      <Indicator size="md" color={stateColor[device.state]} />
+      <Typography
+        variant="body2"
+        color={device.slot ? 'primary' : 'secondary'}
+        className="flex-1 font-bold text-[12px]"
+      >
+        {device.nickname}
+      </Typography>
+      <Typography variant="mono" color="tertiary" className="text-[10px]">
+        {device.id}
+      </Typography>
+    </Wrapper>
+  )
+}

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

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { NavItem } from './NavItem'
+import { ActivityIcon } from '../icons'
+
+const meta: Meta<typeof NavItem> = {
+  title: 'Shell/NavItem',
+  component: NavItem,
+  tags: ['autodocs'],
+  args: { label: 'Live', active: false, live: false },
+  argTypes: {
+    label: { control: 'text' },
+    active: { control: 'boolean' },
+    live: { control: 'boolean' },
+    icon: { control: false },
+    onPress: { action: 'press' },
+  },
+  decorators: [
+    (Story) => (
+      <View className="w-[60px] items-center bg-background-base py-2">
+        <Story />
+      </View>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Molecule.** One category button — a glyph over an uppercase micro-label in a 46×46 target, ' +
+          'spanning the full 60px rail so the active accent bar sits flush to the edge. Composes an ' +
+          '[icon](?path=/docs/foundations-icons--docs) + [Typography](?path=/docs/foundations-typography--docs). Toggle ' +
+          '`active` / `live` to see the states.',
+      },
+    },
+  },
+  render: (args) => <NavItem {...args} icon={<ActivityIcon size={20} color="currentColor" />} />,
+}
+export default meta
+type Story = StoryObj<typeof NavItem>
+
+export const Default: Story = {}
+export const Active: Story = { args: { active: true } }
+export const LiveElsewhere: Story = {
+  args: { live: true },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Not the active view, but a set is running for this category → muted-green label.',
+      },
+    },
+  },
+}

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

@@ -0,0 +1,35 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { NavItem } from './NavItem'
+import { ActivityIcon } from '../icons'
+
+const icon = <ActivityIcon size={20} color="currentColor" />
+
+describe('NavItem', () => {
+  it('renders the label and is exposed as a tab', () => {
+    render(<NavItem icon={icon} label="Live" />)
+    expect(screen.getByRole('tab', { name: 'Live' })).toBeInTheDocument()
+  })
+
+  it('shows the accent bar when active', () => {
+    render(<NavItem icon={icon} label="Live" active />)
+    expect(screen.getByTestId('nav-item-accent')).toBeInTheDocument()
+  })
+
+  it('hides the accent bar when inactive', () => {
+    render(<NavItem icon={icon} label="Live" />)
+    expect(screen.queryByTestId('nav-item-accent')).toBeNull()
+  })
+
+  it('fires onPress when tapped', () => {
+    const onPress = vi.fn()
+    render(<NavItem icon={icon} label="Live" onPress={onPress} />)
+    fireEvent.click(screen.getByRole('tab', { name: 'Live' }))
+    expect(onPress).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders the live-elsewhere state', () => {
+    const { container } = render(<NavItem icon={icon} label="Live" live />)
+    expect(container.firstChild).toBeInTheDocument()
+  })
+})

package/src/components/shell/NavItem.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode } from 'react'
+import { Pressable, View } from 'react-native'
+import { cn } from '../../utils/cn'
+import { Typography } from '../custom/Typography'
+
+export interface NavItemProps {
+  /** The nav glyph (an icon from `components/icons`, rendered ~20px via `currentColor`). */
+  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?: 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
+  onPress?: () => void
+  className?: string
+}
+
+/**
+ * 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
+ * label `status-success-dark` (the glyph stays dim); otherwise dim `text-tertiary`.
+ */
+export function NavItem({
+  icon,
+  label,
+  active = false,
+  live = false,
+  onPress,
+  className,
+}: NavItemProps) {
+  const glyphColor = active ? 'text-brand-primary' : 'text-text-tertiary'
+  const labelColor = active
+    ? 'text-brand-primary'
+    : live
+      ? 'text-status-live-muted'
+      : 'text-text-tertiary'
+
+  return (
+    <Pressable
+      accessibilityRole="tab"
+      accessibilityState={{ selected: active }}
+      accessibilityLabel={label}
+      onPress={onPress}
+      className={cn('relative h-[46px] w-[60px] items-center justify-center', className)}
+    >
+      {active ? (
+        <View
+          testID="nav-item-accent"
+          className="absolute left-0 top-[13px] bottom-[13px] w-[3px] rounded-r-[3px] bg-brand-primary"
+        />
+      ) : null}
+      <View
+        className={cn(
+          'h-[46px] w-[46px] items-center justify-center gap-[3px] rounded-[11px]',
+          glyphColor
+        )}
+      >
+        {icon}
+        <Typography
+          variant="button"
+          color="inherit"
+          className={cn('text-[8.5px] font-bold uppercase tracking-[0.4px]', labelColor)}
+        >
+          {label}
+        </Typography>
+      </View>
+    </Pressable>
+  )
+}

package/src/components/shell/README.md

@@ -0,0 +1,116 @@
+# 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.
+
+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.
+
+## 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
+│  └─ Typography ............. titan · button variant (uppercase micro-label)
+└─ (accent bar) .............. bg-brand-primary edge bar on the active item
+```
+
+Decisions locked 2026-07-08 (specimen `coordination/design-explorations/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.
+
+## Specimen: `TopBar` (the first shell unit, S1)
+
+```
+TopBar ....................... organism — the chrome band (Shell/TopBar)
+├─ BrandLockup ............... molecule
+│  ├─ VoltrasMark ............ icons (shared primitive)
+│  └─ 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
+└─ surfaceGradient.chrome .... theme · gradient primitive
+```
+
+## Dependency map
+
+| Component | Tier | Composes ↓ | Used-by ↑ |
+|---|---|---|---|
+| `SideNav` | organism | NavItem ×4, `components/icons` (Activity/History/Layers/PersonStanding) | dashboard app root *(planned)* |
+| `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 |
+| `DeviceIndicator` | molecule | BluetoothIcon | DeviceMenu |
+| `DeviceRow` | molecule | Indicator, Typography | DeviceMenu |
+| `VoltrasMark` / `BluetoothIcon` | **`components/icons`** primitive | `SvgIcon` base | BrandLockup / DeviceIndicator (+ any consumer) |
+
+## Shared substrates introduced here (reusable beyond the shell)
+
+Building S1 grew the design system — these are now available to every component:
+
+- **`components/icons`** — a shared icon primitive: an `SvgIcon` base (24×24, a11y contract, `currentColor`)
+  + `IconProps`. VoltrasMark / BluetoothIcon live here, and the previously-orphaned Workout icons
+  (Dumbbell / Star) were folded in (re-exported from `Workout/icons` for back-compat).
+- **`theme/gradients.ts`** — `linearGradient(from, to, angle)` + named `surfaceGradient.*`, built on
+  `resolveColor` (themeable web CSS vars + native hex fallback).
+- **`Indicator`** (titan atom) — `pulse: 'ping'` (expanding ring) + `success` / `error-vivid` colors.
+- **`DateTime`** (titan) — `hour12`, `seconds`, self-ticking `live`, and Typography routing via `variant`.
+- **`Typography`** — `mono` (technical readouts) + `monoLabel` (all-caps mono) variants.
+- **Tokens** — a full **vivid** green/red palette + **`border-prominent`** divider token.
+
+## Reuse audit (the "are we failing to use existing components?" check)
+
+Every leaf now composes a primitive rather than hand-rolling it:
+
+| Concern | Uses | Not |
+|---|---|---|
+| status dots | `Indicator` | raw CSS/`View` dots |
+| dividers | `Divider` (`border-prominent`) | hairline `View`s |
+| mono / all-caps text | `Typography` `mono`/`monoLabel` | ad-hoc `font-mono` classes |
+| glyphs | icon atoms (`VoltrasMark`, `BluetoothIcon`) | unicode chars / inline `<svg>` |
+| chrome gradient | `surfaceGradient.chrome` | inline `linear-gradient` strings |
+| colors | semantic tokens (vivid palette) | magic hex |
+
+## Testing
+
+- **Unit** — every component + primitive has a `*.test.tsx` (render, behavior, a11y); shell branch coverage ≈96%.
+- **Visual** — `tests/visual/stories.spec.ts` screenshots the `Shell/*` + `Icons` stories via Playwright
+  (`toHaveScreenshot`), clock-frozen + animations-disabled so the live-clock/animated stories are
+  deterministic. Widen `SCOPE` to cover more of the library. **Baselines must be generated in the pinned
+  container** (`mcr.microsoft.com/playwright:v1.58.2-noble`) — the `visual.yml` "Layer 2" step seeds them as
+  an artifact; commit the `*-chromium-linux.png` and flip the step to the `test:visual:stories` gate.
+- **Lint guardrails** — components may not inline `linear-gradient` (use `surfaceGradient`); shell + icons may
+  not use raw hex (use tokens).
+
+**S2 shared substrate:** four nav glyphs added to `components/icons` (`ActivityIcon`, `HistoryIcon`,
+`LayersIcon`, `PersonStandingIcon` — lucide-mirrored, like Dumbbell/Star), available system-wide.
+
+**Watch-list (known gaps to close as we go):**
+- **Dot primitive overlap** — titan has both `StatusDot` (Workout, semantic) and `Indicator` (ui, generic).
+  The shell standardizes on `Indicator`; a future pass could consolidate.
+- **Other hand-rolled gradients** — `MesoCard`, `DeviationBar`, `MesoStatusCard`, `BodyMapDetailPanel` still
+  inline `linear-gradient` strings; they should adopt `surfaceGradient` / `linearGradient`.
+- **`status-live` token family (new, decoupled from success)** — introduced `status-live` (green-300, the
+  vivid LIVE-pill green) + `status-live-muted` (green-500 `#22A444`, the quiet nav cue) so "live" has its own
+  role: changing `status-success` no longer affects live, and vice-versa. Wired the full chain (semantic →
+  config → global.css → tailwind); `Indicator` gained a `live` color; the S1 LIVE pill was repointed
+  `success`→`live` (value-preserving). This realized a slice of TD-05.09 Fork 1b (wiring ramp steps as tokens).
+- **`aria-selected` on `NavItem`** — RNW does not emit `aria-selected` from `accessibilityState={{selected}}`
+  in the jsdom test env, so active-state is asserted via the accent-bar testID. Confirm the on-device/RNW
+  build exposes selection to AT (may need an explicit `aria-selected` for full tab semantics).