@titan-design/react-ui 0.5.0 → 0.7.0

package/src/components/icons/icons.stories.tsx

@@ -0,0 +1,122 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { ReactNode } from 'react'
+import { View, Text } from 'react-native'
+import {
+  VoltrasMark,
+  BluetoothIcon,
+  DumbbellIcon,
+  StarIcon,
+  ActivityIcon,
+  HistoryIcon,
+  LayersIcon,
+  PersonStandingIcon,
+  ScaleIcon,
+  AlertTriangleIcon,
+  TrendingDownIcon,
+  CircleSlashIcon,
+  AwardIcon,
+  InfoIcon,
+} from './icons'
+
+const meta: Meta = {
+  title: 'Foundations/Icons',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'The shared icon primitive — 24×24 web-`<svg>` glyphs on a common `SvgIcon` base ' +
+          '(a11y contract: titled → `role="img"`, untitled → `aria-hidden`; `currentColor` inheritance). ' +
+          'Reusable design-system-wide (the shell, Workout badges, etc. compose these).',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj
+
+function Swatch({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <View className="items-center gap-2">
+      {children}
+      <Text className="font-mono text-[10px] text-text-tertiary">{label}</Text>
+    </View>
+  )
+}
+
+export const All: Story = {
+  render: () => (
+    <View className="flex-row gap-8 p-4 items-start">
+      <Swatch label="VoltrasMark">
+        <View className="text-brand-primary">
+          <VoltrasMark size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="BluetoothIcon">
+        <View className="text-status-success">
+          <BluetoothIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="DumbbellIcon">
+        <View className="text-text-primary">
+          <DumbbellIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="StarIcon (fill)">
+        <View className="text-brand-primary">
+          <StarIcon size={28} fill="currentColor" />
+        </View>
+      </Swatch>
+      <Swatch label="ActivityIcon">
+        <View className="text-text-primary">
+          <ActivityIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="HistoryIcon">
+        <View className="text-text-primary">
+          <HistoryIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="LayersIcon">
+        <View className="text-text-primary">
+          <LayersIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="PersonStandingIcon">
+        <View className="text-text-primary">
+          <PersonStandingIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="ScaleIcon">
+        <View className="text-status-error">
+          <ScaleIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="AlertTriangleIcon">
+        <View className="text-status-error">
+          <AlertTriangleIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="TrendingDownIcon">
+        <View className="text-status-warning">
+          <TrendingDownIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="CircleSlashIcon">
+        <View className="text-status-warning">
+          <CircleSlashIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="AwardIcon">
+        <View className="text-status-success">
+          <AwardIcon size={28} />
+        </View>
+      </Swatch>
+      <Swatch label="InfoIcon">
+        <View className="text-status-info">
+          <InfoIcon size={28} />
+        </View>
+      </Swatch>
+    </View>
+  ),
+}

package/src/components/icons/icons.test.tsx

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import {
+  VoltrasMark,
+  BluetoothIcon,
+  DumbbellIcon,
+  StarIcon,
+  ActivityIcon,
+  HistoryIcon,
+  LayersIcon,
+  PersonStandingIcon,
+  ScaleIcon,
+  AlertTriangleIcon,
+  TrendingDownIcon,
+  CircleSlashIcon,
+  AwardIcon,
+  InfoIcon,
+} from './icons'
+import { SvgIcon } from './SvgIcon'
+
+describe('icon primitives', () => {
+  it('every icon renders an svg', () => {
+    ;[
+      VoltrasMark,
+      BluetoothIcon,
+      DumbbellIcon,
+      StarIcon,
+      ActivityIcon,
+      HistoryIcon,
+      LayersIcon,
+      PersonStandingIcon,
+      ScaleIcon,
+      AlertTriangleIcon,
+      TrendingDownIcon,
+      CircleSlashIcon,
+      AwardIcon,
+      InfoIcon,
+    ].forEach((Icon) => {
+      const { container, unmount } = render(<Icon />)
+      expect(container.querySelector('svg')).toBeInTheDocument()
+      unmount()
+    })
+  })
+
+  it('a titled icon is exposed as an accessible image', () => {
+    render(<BluetoothIcon title="Devices" />)
+    expect(screen.getByRole('img', { name: 'Devices' })).toBeInTheDocument()
+  })
+
+  it('an untitled icon is decorative (aria-hidden, no role)', () => {
+    const { container } = render(<VoltrasMark />)
+    const svg = container.querySelector('svg')!
+    expect(svg.getAttribute('aria-hidden')).toBe('true')
+    expect(svg.getAttribute('role')).toBeNull()
+  })
+
+  it('honors size + strokeWidth via the SvgIcon base', () => {
+    const { container } = render(
+      <SvgIcon size={32} strokeWidth={3}>
+        <path d="M0 0" />
+      </SvgIcon>
+    )
+    const svg = container.querySelector('svg')!
+    expect(svg.getAttribute('width')).toBe('32')
+    expect(svg.getAttribute('stroke-width')).toBe('3')
+  })
+
+  it('a decorative icon has no accessibility violations', async () => {
+    const { container } = render(<StarIcon />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/icons/icons.tsx

@@ -0,0 +1,153 @@
+import { SvgIcon, type IconProps } from './SvgIcon'
+
+/**
+ * Voltras brand mark — the ◇ diamond (outline). Pass `fill` for a solid mark.
+ */
+export function VoltrasMark({ size = 14, ...props }: IconProps) {
+  return (
+    <SvgIcon size={size} {...props}>
+      <path d="M12 2 22 12 12 22 2 12Z" />
+    </SvgIcon>
+  )
+}
+
+/**
+ * Bluetooth glyph (stroked) — e.g. device-connection state (color via `currentColor`).
+ */
+export function BluetoothIcon({ size = 18, ...props }: IconProps) {
+  return (
+    <SvgIcon size={size} {...props}>
+      <path d="M7 7 17 17 12 22 12 2 17 7 7 17" />
+    </SvgIcon>
+  )
+}
+
+/** Dumbbell glyph (mirrors lucide-react `Dumbbell`). Outline-only by default. */
+export function DumbbellIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="M14.4 14.4 9.6 9.6" />
+      <path d="M18.657 21.485a2 2 0 1 1-2.829-2.828l-1.767 1.768a2 2 0 1 1-2.829-2.829l6.364-6.364a2 2 0 1 1 2.829 2.829l-1.768 1.767a2 2 0 1 1 2.828 2.829z" />
+      <path d="m21.5 21.5-1.4-1.4" />
+      <path d="M3.9 3.9 2.5 2.5" />
+      <path d="M6.404 12.768a2 2 0 1 1-2.829-2.829l1.768-1.767a2 2 0 1 1-2.828-2.829l2.828-2.828a2 2 0 1 1 2.829 2.828l1.767-1.768a2 2 0 1 1 2.829 2.829z" />
+    </SvgIcon>
+  )
+}
+
+/** Star glyph (mirrors lucide-react `Star`). Pass `fill` for a solid star. */
+export function StarIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z" />
+    </SvgIcon>
+  )
+}
+
+/** Activity / pulse-line glyph (mirrors lucide-react `Activity`). Shell S2 nav → Live. */
+export function ActivityIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="M22 12h-4l-3 9L9 3l-3 9H2" />
+    </SvgIcon>
+  )
+}
+
+/** History / clock-arrow glyph (mirrors lucide-react `History`). Shell S2 nav → Review. */
+export function HistoryIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="M3 12a9 9 0 1 0 3-6.7L3 8" />
+      <path d="M3 3v5h5" />
+      <path d="M12 7v5l4 2" />
+    </SvgIcon>
+  )
+}
+
+/** Layers / stack glyph (mirrors lucide-react `Layers`). Shell S2 nav → Program (mesocycle stack). */
+export function LayersIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="m12.83 2.18a2 2 0 0 0-1.66 0L2.6 6.08a1 1 0 0 0 0 1.83l8.58 3.91a2 2 0 0 0 1.66 0l8.58-3.9a1 1 0 0 0 0-1.83Z" />
+      <path d="m6.08 9.5-3.49 1.59a1 1 0 0 0 0 1.81l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9a1 1 0 0 0 0-1.83l-3.5-1.59" />
+      <path d="m6.08 14.5-3.49 1.59a1 1 0 0 0 0 1.81l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9a1 1 0 0 0 0-1.83l-3.5-1.59" />
+    </SvgIcon>
+  )
+}
+
+/** Standing-figure glyph (mirrors lucide-react `PersonStanding`). Shell S2 nav → Body (muscle map). */
+export function PersonStandingIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <circle cx="12" cy="5" r="1" />
+      <path d="m9 20 3-6 3 6" />
+      <path d="m6 8 6 2 6-2" />
+      <path d="M12 10v4" />
+    </SvgIcon>
+  )
+}
+
+/** Balance-scale glyph (mirrors lucide-react `Scale`). ExerciseIndicator → `imbalance`. */
+export function ScaleIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="m16 16 3-8 3 8c-.87.65-1.92 1-3 1s-2.13-.35-3-1Z" />
+      <path d="m2 16 3-8 3 8c-.87.65-1.92 1-3 1s-2.13-.35-3-1Z" />
+      <path d="M7 21h10" />
+      <path d="M12 3v18" />
+      <path d="M3 7h2c2 0 5-1 7-2 2 1 5 2 7 2h2" />
+    </SvgIcon>
+  )
+}
+
+/** Warning-triangle glyph (mirrors lucide-react `AlertTriangle`). ExerciseIndicator → `overshoot`. */
+export function AlertTriangleIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" />
+      <path d="M12 9v4" />
+      <path d="M12 17h.01" />
+    </SvgIcon>
+  )
+}
+
+/** Down-trend glyph (mirrors lucide-react `TrendingDown`). ExerciseIndicator → `velocity-loss`. */
+export function TrendingDownIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="M16 17h6v-6" />
+      <path d="m22 17-8.5-8.5-5 5L2 7" />
+    </SvgIcon>
+  )
+}
+
+/** Slashed-circle glyph (mirrors lucide-react `CircleSlash`). ExerciseIndicator → `missed-reps`. */
+export function CircleSlashIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <circle cx="12" cy="12" r="10" />
+      <path d="m9 15 6-6" />
+    </SvgIcon>
+  )
+}
+
+/** Medal glyph (mirrors lucide-react `Award`). ExerciseIndicator → `pr`. */
+export function AwardIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <path d="m15.477 12.89 1.515 8.526a.5.5 0 0 1-.81.47l-3.58-2.687a1 1 0 0 0-1.197 0l-3.586 2.686a.5.5 0 0 1-.81-.469l1.514-8.526" />
+      <circle cx="12" cy="8" r="6" />
+    </SvgIcon>
+  )
+}
+
+/** Info-circle glyph (mirrors lucide-react `Info`). ExerciseIndicator → `info`. */
+export function InfoIcon(props: IconProps) {
+  return (
+    <SvgIcon {...props}>
+      <circle cx="12" cy="12" r="10" />
+      <path d="M12 16v-4" />
+      <path d="M12 8h.01" />
+    </SvgIcon>
+  )
+}

package/src/components/icons/index.ts

@@ -0,0 +1,4 @@
+// Icon primitives — the shared, design-system-wide icon set. A base `SvgIcon`
+// wrapper (24×24 web SVG + a11y contract + currentColor) and the icon glyphs.
+export { SvgIcon, type IconProps, type SvgIconProps } from './SvgIcon'
+export * from './icons'

package/src/components/index.ts

@@ -1,5 +1,11 @@
+// Icon primitives (shared, design-system-wide)
+export * from './icons'
+
 // Re-export all UI components
 export * from './ui'
 
 // Re-export custom components
 export * from './custom'
+
+// Re-export shell chrome components
+export * from './shell'

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

@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { BrandLockup } from './BrandLockup'
+
+const meta: Meta<typeof BrandLockup> = {
+  title: 'Shell/BrandLockup',
+  component: BrandLockup,
+  tags: ['autodocs'],
+  args: { subtitle: 'wall dashboard', showSubtitle: true },
+  argTypes: {
+    subtitle: { control: 'text' },
+    showSubtitle: { control: 'boolean' },
+  },
+  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.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof BrandLockup>
+
+export const Default: Story = {}

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

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { BrandLockup } from './BrandLockup'
+
+describe('BrandLockup', () => {
+  it('renders the wordmark', () => {
+    render(<BrandLockup />)
+    expect(screen.getByText('VOLTRAS')).toBeInTheDocument()
+  })
+
+  it('shows the subtitle by default and hides it when showSubtitle is false', () => {
+    const { rerender } = render(<BrandLockup subtitle="wall dashboard" />)
+    expect(screen.getByText('/ wall dashboard')).toBeInTheDocument()
+    rerender(<BrandLockup subtitle="wall dashboard" showSubtitle={false} />)
+    expect(screen.queryByText('/ wall dashboard')).not.toBeInTheDocument()
+  })
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<BrandLockup />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/shell/BrandLockup.tsx

@@ -0,0 +1,47 @@
+import { View, type ViewProps } from 'react-native'
+import { cn } from '../../utils/cn'
+import { Typography } from '../custom/Typography'
+import { VoltrasMark } from '../icons'
+
+export interface BrandLockupProps extends ViewProps {
+  /** The "/ subtitle" that follows the wordmark. Default "wall dashboard". */
+  subtitle?: string
+  /** Show the subtitle. Hidden at tablet width and below (S1-Q4 responsive). */
+  showSubtitle?: boolean
+  className?: string
+}
+
+/**
+ * Product identity lockup for the top bar: ◇ mark + VOLTRAS wordmark + optional
+ * subtitle. Composes the VoltrasMark icon + Typography. S1 · BrandLockup.
+ */
+export function BrandLockup({
+  subtitle = 'wall dashboard',
+  showSubtitle = true,
+  className,
+  ...props
+}: BrandLockupProps) {
+  return (
+    <View className={cn('flex-row items-center gap-[7px]', className)} {...props}>
+      <View className="text-brand-primary">
+        <VoltrasMark size={14} color="currentColor" />
+      </View>
+      <Typography
+        variant="button"
+        color="primary"
+        className="text-[12px] font-extrabold tracking-[1.5px]"
+      >
+        VOLTRAS
+      </Typography>
+      {showSubtitle && subtitle ? (
+        <Typography
+          variant="button"
+          color="tertiary"
+          className="text-[10px] font-semibold tracking-[0.4px]"
+        >
+          / {subtitle}
+        </Typography>
+      ) : null}
+    </View>
+  )
+}

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

@@ -0,0 +1,65 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import { DashboardShell } from './DashboardShell'
+
+/**
+ * `Pages/DashboardShell` — the wall-dashboard chrome as one registered surface.
+ * Composes the shell-nav island (SideNav + TopBar and everything they pull in) over a
+ * `children` content slot, so the dashboard app mounts a single component.
+ */
+const meta: Meta<typeof DashboardShell> = {
+  title: 'Pages/DashboardShell',
+  component: DashboardShell,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          '**Page shell.** The wall-dashboard chrome. Composes ' +
+          '[SideNav](?path=/docs/shell-sidenav--docs) + ' +
+          '[TopBar](?path=/docs/shell-topbar--docs) — which pulls in DeviceMenu, DeviceRow, ' +
+          'DeviceIndicator, SessionStatePill, BrandLockup, DateTime and Divider — over a ' +
+          '`children` content slot. Mount this instead of re-assembling the chrome per view.',
+      },
+    },
+  },
+  argTypes: {
+    state: { control: 'select', options: ['live', 'rest', 'idle'] },
+    activeKey: { control: 'select', options: ['live', 'review', 'program', 'body'] },
+    liveKey: { control: 'select', options: [null, 'live', 'review', 'program', 'body'] },
+    onNavigate: { control: false },
+    onSelectDevice: { control: false },
+  },
+  decorators: [
+    (Story) => (
+      <View style={{ height: '100vh' as unknown as number, backgroundColor: '#0E0E0E' }}>
+        <Story />
+      </View>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof DashboardShell>
+
+export const Default: Story = {
+  args: { activeKey: 'live', state: 'live' },
+}
+
+export const WithContent: Story = {
+  args: { activeKey: 'review', state: 'rest', liveKey: 'live' },
+  render: (args) => (
+    <DashboardShell {...args}>
+      <View style={{ flex: 1, padding: 28 }}>
+        <Text style={{ color: '#E5E5E5', fontSize: 22, fontWeight: '700' }}>Review</Text>
+        <Text style={{ color: '#8A8A8A', fontSize: 13, marginTop: 6 }}>
+          A page mounts its content here; the shell keeps the nav + top-bar chrome persistent.
+        </Text>
+      </View>
+    </DashboardShell>
+  ),
+  parameters: {
+    docs: { description: { story: 'The shell with a page mounted in its content slot.' } },
+  },
+}

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

@@ -0,0 +1,42 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Text } from 'react-native'
+import { axe } from 'jest-axe'
+import { DashboardShell } from './DashboardShell'
+
+describe('DashboardShell', () => {
+  it('composes the SideNav rail and its categories', () => {
+    render(<DashboardShell activeKey="live" />)
+    expect(screen.getByRole('tablist')).toBeInTheDocument()
+    ;['Live', 'Review', 'Plan', 'Body'].forEach((name) => {
+      expect(screen.getByRole('tab', { name })).toBeInTheDocument()
+    })
+  })
+
+  it('renders the content-slot placeholder when no children are given', () => {
+    render(<DashboardShell activeKey="live" />)
+    expect(screen.getByText('main content region')).toBeInTheDocument()
+  })
+
+  it('mounts children in the content slot and drops the placeholder', () => {
+    render(
+      <DashboardShell activeKey="review">
+        <Text>my page body</Text>
+      </DashboardShell>
+    )
+    expect(screen.getByText('my page body')).toBeInTheDocument()
+    expect(screen.queryByText('main content region')).not.toBeInTheDocument()
+  })
+
+  it('forwards nav taps through onNavigate', () => {
+    const onNavigate = vi.fn()
+    render(<DashboardShell activeKey="live" onNavigate={onNavigate} />)
+    fireEvent.click(screen.getByRole('tab', { name: 'Body' }))
+    expect(onNavigate).toHaveBeenCalledWith('body')
+  })
+
+  it('has no a11y violations', async () => {
+    const { container } = render(<DashboardShell activeKey="live" />)
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/shell/DashboardShell.tsx

@@ -0,0 +1,74 @@
+import type { ReactNode } from 'react'
+import { View, Text } from 'react-native'
+import { cn } from '../../utils/cn'
+import { SideNav, type SideNavItem } from './SideNav'
+import { TopBar } from './TopBar'
+import { type Device } from './DeviceRow'
+import { type SessionState } from './SessionStatePill'
+
+/**
+ * `DashboardShell` — the wall-dashboard chrome: a persistent {@link SideNav} rail +
+ * {@link TopBar} over a main content region. A thin frame that wires the shell-nav
+ * organisms together and exposes a `children` content slot, so the dashboard app
+ * mounts one component instead of re-assembling the chrome. Driven entirely by props.
+ */
+export interface DashboardShellProps {
+  /** Active nav category key. */
+  activeKey?: string
+  /** Nav categories, top → bottom. Defaults to SideNav's four dashboard categories. */
+  navItems?: SideNavItem[]
+  /** A category with off-view live activity → a quiet cue on that item. */
+  liveKey?: string | null
+  /** Global session state → the TopBar status pill. */
+  state?: SessionState
+  /** Connected devices → the TopBar connection glyph + dropdown. */
+  devices?: Device[]
+  /** TopBar brand subtitle. */
+  subtitle?: string
+  onNavigate?: (key: string) => void
+  onSelectDevice?: (device: Device) => void
+  /** Main content region. A placeholder renders when omitted. */
+  children?: ReactNode
+  className?: string
+}
+
+const DEMO_DEVICES: Device[] = [
+  { id: 'Voltra-A3F2', nickname: 'Left Cable', slot: 'L', state: 'connected' },
+  { id: 'Voltra-9B1C', nickname: 'Right Cable', slot: 'R', state: 'connected' },
+]
+
+function ContentPlaceholder() {
+  return (
+    <View className="flex-1 items-center justify-center">
+      <Text className="font-heading text-sm text-text-tertiary">main content region</Text>
+    </View>
+  )
+}
+
+export function DashboardShell({
+  activeKey = 'live',
+  navItems,
+  liveKey = null,
+  state = 'live',
+  devices = DEMO_DEVICES,
+  subtitle = 'wall dashboard',
+  onNavigate,
+  onSelectDevice,
+  children,
+  className,
+}: DashboardShellProps) {
+  return (
+    <View className={cn('flex-1 flex-row bg-surface-base', className)}>
+      <SideNav activeKey={activeKey} items={navItems} liveKey={liveKey} onNavigate={onNavigate} />
+      <View className="flex-1">
+        <TopBar
+          state={state}
+          devices={devices}
+          subtitle={subtitle}
+          onSelectDevice={onSelectDevice}
+        />
+        <View className="flex-1">{children ?? <ContentPlaceholder />}</View>
+      </View>
+    </View>
+  )
+}

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

@@ -0,0 +1,28 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { DeviceIndicator } from './DeviceIndicator'
+
+const meta: Meta<typeof DeviceIndicator> = {
+  title: 'Shell/DeviceIndicator',
+  component: DeviceIndicator,
+  tags: ['autodocs'],
+  args: { status: 'connected' },
+  argTypes: {
+    status: { control: 'select', options: ['connected', 'degraded', 'lost'] },
+    label: { control: 'text' },
+    onPress: { control: false },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Molecule.** Composes [BluetoothIcon](?path=/docs/foundations-icons--docs), color-coded by ' +
+          'connection state via a `text-status-*-vivid` token — the glyph color alone carries the fault ' +
+          '(no separate badge). Switch the `status` control to see connected / degraded / lost.',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof DeviceIndicator>
+
+export const Default: Story = {}