@titan-design/react-ui 0.6.0 → 0.8.0

package/src/components/custom/Workout/ExerciseIndicator.test.tsx

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import {
+  ExerciseIndicator,
+  resolveIndicator,
+  INDICATOR_PRECEDENCE,
+  type ExerciseIndicatorKind,
+} from './ExerciseIndicator'
+
+// tier color = titan status token, applied as the glyph's SVG stroke (literal hex):
+// danger=status-error, warning=status-warning, success=status-success, info=status-info.
+const kinds: { kind: ExerciseIndicatorKind; label: string; tier: string }[] = [
+  { kind: 'imbalance', label: 'Left/right imbalance', tier: '#D14343' },
+  { kind: 'overshoot', label: 'Load overshoot', tier: '#D14343' },
+  { kind: 'velocity-loss', label: 'Velocity loss', tier: '#F9B415' },
+  { kind: 'missed-reps', label: 'Missed reps', tier: '#F9B415' },
+  { kind: 'pr', label: 'Personal record', tier: '#2ED573' },
+  { kind: 'info', label: 'More info', tier: '#2196F3' },
+]
+
+describe('ExerciseIndicator', () => {
+  it.each(kinds)('renders the $kind chip glyph and accessible label', ({ kind, label }) => {
+    const { container } = render(<ExerciseIndicator kind={kind} />)
+    // glyph is an inline SVG (lucide-mirrored), not a text character
+    expect(container.querySelector('svg')).toBeInTheDocument()
+    expect(screen.getByLabelText(label)).toBeInTheDocument()
+  })
+
+  it.each(kinds)('tints the $kind glyph with its tier color', ({ kind, tier }) => {
+    const { container } = render(<ExerciseIndicator kind={kind} />)
+    expect(container.querySelector('svg')!.getAttribute('stroke')).toBe(tier)
+  })
+
+  it('renders a decorative (aria-hidden) glyph so the chip owns the label', () => {
+    const { container } = render(<ExerciseIndicator kind="pr" />)
+    expect(container.querySelector('svg')!.getAttribute('aria-hidden')).toBe('true')
+  })
+
+  it('is presentational (no button role) without onPress', () => {
+    render(<ExerciseIndicator kind="pr" />)
+    expect(screen.queryByRole('button')).not.toBeInTheDocument()
+  })
+
+  it('becomes a button and fires onPress when interactive', () => {
+    const onPress = vi.fn()
+    render(<ExerciseIndicator kind="pr" onPress={onPress} />)
+    const button = screen.getByRole('button', { name: 'Personal record' })
+    fireEvent.click(button)
+    expect(onPress).toHaveBeenCalledOnce()
+  })
+
+  describe('accessibility', () => {
+    it.each(kinds)('has no accessibility violations for $kind', async ({ kind }) => {
+      const { container } = render(<ExerciseIndicator kind={kind} />)
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+  })
+})
+
+describe('resolveIndicator', () => {
+  it('returns undefined when no signals are active', () => {
+    expect(resolveIndicator([])).toBeUndefined()
+  })
+
+  it('returns the sole candidate unchanged', () => {
+    expect(resolveIndicator(['velocity-loss'])).toBe('velocity-loss')
+  })
+
+  it('picks the highest-precedence kind regardless of input order', () => {
+    expect(resolveIndicator(['info', 'pr', 'overshoot'])).toBe('overshoot')
+    expect(resolveIndicator(['overshoot', 'pr', 'info'])).toBe('overshoot')
+  })
+
+  it('lets imbalance (rank 1) win over every other signal', () => {
+    expect(resolveIndicator([...INDICATOR_PRECEDENCE])).toBe('imbalance')
+  })
+
+  it('ranks the soft alerts above pr (alert > pr)', () => {
+    expect(resolveIndicator(['pr', 'missed-reps'])).toBe('missed-reps')
+    expect(resolveIndicator(['pr', 'velocity-loss'])).toBe('velocity-loss')
+  })
+
+  it('falls to info only when it is the lowest active signal', () => {
+    expect(resolveIndicator(['info', 'pr'])).toBe('pr')
+    expect(resolveIndicator(['info'])).toBe('info')
+  })
+
+  it('ignores duplicate candidates', () => {
+    expect(resolveIndicator(['pr', 'pr', 'info'])).toBe('pr')
+  })
+})

package/src/components/custom/Workout/ExerciseIndicator.tsx

@@ -0,0 +1,120 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import type { ComponentType } from 'react'
+import { View, Pressable, type ViewProps } from 'react-native'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import {
+  ScaleIcon,
+  AlertTriangleIcon,
+  TrendingDownIcon,
+  CircleSlashIcon,
+  AwardIcon,
+  InfoIcon,
+  type IconProps,
+} from '../../icons'
+
+// Literal-hex status pins (the TempoBar pattern) — `resolveColor()` yields a
+// `var(...)` under the RNW vitest alias, which breaks `toHaveStyle` in tests.
+const t = getSemanticColors('dark')
+
+/**
+ * The LOCKED 6-kind indicator taxonomy (TD-03.51). One precedence-ranked slot is
+ * ever shown per exercise, resolved by {@link resolveIndicator}. Glyph = the
+ * specific signal; color = the severity tier (danger/warning/success/info, bound
+ * to titan status tokens). Outlined (border + glyph, no fill) so a chip never
+ * collides with the filled velocity strip beside it.
+ */
+export type ExerciseIndicatorKind =
+  | 'imbalance'
+  | 'overshoot'
+  | 'velocity-loss'
+  | 'missed-reps'
+  | 'pr'
+  | 'info'
+
+interface IndicatorConfig {
+  Icon: ComponentType<IconProps>
+  /** Tier color — a titan status semantic token (literal hex on `t`). */
+  color: string
+  /** Accessible description (also the intended tooltip subject). */
+  label: string
+}
+
+const INDICATOR_CONFIG: Record<ExerciseIndicatorKind, IndicatorConfig> = {
+  imbalance: { Icon: ScaleIcon, color: t['status-error'], label: 'Left/right imbalance' },
+  overshoot: { Icon: AlertTriangleIcon, color: t['status-error'], label: 'Load overshoot' },
+  'velocity-loss': { Icon: TrendingDownIcon, color: t['status-warning'], label: 'Velocity loss' },
+  'missed-reps': { Icon: CircleSlashIcon, color: t['status-warning'], label: 'Missed reps' },
+  pr: { Icon: AwardIcon, color: t['status-success'], label: 'Personal record' },
+  info: { Icon: InfoIcon, color: t['status-info'], label: 'More info' },
+}
+
+/**
+ * Precedence order (1=highest → last=lowest). A single chip is shown, so when
+ * several signals are true the highest-ranked wins. Alerts outrank `pr`; `info`
+ * is the floor. This ordering is LOCKED — do not reshuffle.
+ */
+export const INDICATOR_PRECEDENCE: readonly ExerciseIndicatorKind[] = [
+  'imbalance',
+  'overshoot',
+  'velocity-loss',
+  'missed-reps',
+  'pr',
+  'info',
+]
+
+/**
+ * Given the signals currently true for an exercise, pick the single
+ * highest-precedence kind to surface (or `undefined` when none apply). Order and
+ * duplicates in `candidates` don't matter — {@link INDICATOR_PRECEDENCE} decides.
+ */
+export function resolveIndicator(
+  candidates: ExerciseIndicatorKind[],
+): ExerciseIndicatorKind | undefined {
+  return INDICATOR_PRECEDENCE.find((kind) => candidates.includes(kind))
+}
+
+export interface ExerciseIndicatorProps extends Omit<ViewProps, 'children'> {
+  kind: ExerciseIndicatorKind
+  /** Optional tap handler (surfaces detail — PR history / alert / info). */
+  onPress?: () => void
+  className?: string
+}
+
+/**
+ * A small circular outlined chip for an exercise heading. Presentational and
+ * static (chips are chrome — no pulse); the tap detail (tooltip/sheet) is wired
+ * by the consumer.
+ */
+export function ExerciseIndicator({ kind, onPress, className, ...props }: ExerciseIndicatorProps) {
+  const { Icon, color, label } = INDICATOR_CONFIG[kind]
+
+  const chip = (
+    <View
+      className={className}
+      style={{
+        width: 16,
+        height: 16,
+        borderRadius: 8,
+        borderWidth: 1,
+        borderColor: color,
+        alignItems: 'center',
+        justifyContent: 'center',
+      }}
+      accessibilityRole="image"
+      accessibilityLabel={label}
+      testID="exercise-indicator"
+      {...props}
+    >
+      <Icon size={11} color={color} />
+    </View>
+  )
+
+  if (onPress) {
+    return (
+      <Pressable onPress={onPress} accessibilityRole="button" accessibilityLabel={label}>
+        {chip}
+      </Pressable>
+    )
+  }
+  return chip
+}

package/src/components/custom/Workout/FatigueMeter.stories.tsx

@@ -0,0 +1,51 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View } from 'react-native'
+import { FatigueMeter } from './FatigueMeter'
+
+const meta: Meta<typeof FatigueMeter> = {
+  title: 'Workout/DataViz/FatigueMeter',
+  component: FatigueMeter,
+  tags: ['autodocs'],
+  argTypes: {
+    value: { control: { type: 'range', min: 0, max: 40, step: 1 } },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '**Component.** The winning fatigue-visual lineage: a sliding needle over a fixed ' +
+          'green→gold→orange→red velocity-loss gradient with VL10/VL20/VL30/stop markers. ' +
+          'Composes the [ZoneTrack](?path=/docs/workout-dataviz-zonetrack--docs) primitive. ' +
+          'Prop-driven: `value` plus overridable `thresholds` / `max` / `zoneColors` / `labels`.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <View style={{ width: 360, padding: 20, backgroundColor: '#131313' }}>
+        <Story />
+      </View>
+    ),
+  ],
+}
+export default meta
+
+type Story = StoryObj<typeof FatigueMeter>
+
+/** Fresh — needle sits in the green zone. */
+export const Fresh: Story = { args: { value: 5 } }
+
+/** VL20 — needle crossing into the orange zone. */
+export const Vl20: Story = { args: { value: 21 } }
+
+/** Stop zone — deep into the red. */
+export const StopZone: Story = { args: { value: 34 } }
+
+/** The across-the-room wall scale — `size="wall"` grows the track, needle and tick labels together. */
+export const WallDensity: Story = { args: { value: 21, size: 'wall' } }
+
+/** Custom scale — a tighter 0..30 domain with earlier thresholds. */
+export const CustomScale: Story = {
+  args: { value: 12, max: 30, thresholds: [8, 16, 24], labels: ['ok', 'w1', 'w2', 'w3', 'max'] },
+}

package/src/components/custom/Workout/FatigueMeter.test.tsx

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { FatigueMeter } from './FatigueMeter'
+import { WORKOUT_TOKENS } from '../../../theme/workout-tokens'
+
+const { green, red } = WORKOUT_TOKENS.scale
+
+describe('FatigueMeter', () => {
+  it('renders the four fatigue zone bands', () => {
+    render(<FatigueMeter value={0} />)
+    expect(screen.getAllByTestId('zone-track-band')).toHaveLength(4)
+  })
+
+  it('colours the bands from the canonical effort scale', () => {
+    render(<FatigueMeter value={0} />)
+    const bands = screen.getAllByTestId('zone-track-band')
+    expect(bands[0]).toHaveStyle({ backgroundColor: green })
+    expect(bands[3]).toHaveStyle({ backgroundColor: red })
+  })
+
+  it('renders the default VL scale labels', () => {
+    render(<FatigueMeter value={0} />)
+    for (const label of ['fresh', 'VL10', 'VL20', 'VL30', 'stop']) {
+      expect(screen.getByText(label)).toBeInTheDocument()
+    }
+  })
+
+  it('positions the needle at the value on the 0..40 loss scale', () => {
+    render(<FatigueMeter value={20} />)
+    expect(screen.getByTestId('zone-track-needle')).toHaveStyle({ left: '50%' })
+  })
+
+  it('clamps a value beyond the stop end to the track end', () => {
+    render(<FatigueMeter value={60} />)
+    expect(screen.getByTestId('zone-track-needle')).toHaveStyle({ left: '100%' })
+  })
+
+  it('reshapes the zones from custom thresholds + max', () => {
+    render(<FatigueMeter value={5} max={20} thresholds={[5, 10, 15]} />)
+    const bands = screen.getAllByTestId('zone-track-band')
+    expect(bands[0]).toHaveStyle({ flexGrow: 5 })
+    expect(bands[3]).toHaveStyle({ flexGrow: 5 })
+  })
+
+  it('honours custom labels', () => {
+    render(<FatigueMeter value={5} labels={['A', 'B', 'C', 'D', 'E']} />)
+    expect(screen.getByText('A')).toBeInTheDocument()
+    expect(screen.getByText('E')).toBeInTheDocument()
+  })
+
+  it('honours a needle colour override', () => {
+    render(<FatigueMeter value={10} needleColor="#FF00FF" />)
+    expect(screen.getByTestId('zone-track-needle')).toHaveStyle({ backgroundColor: '#FF00FF' })
+  })
+
+  // RNW does not map accessibilityValue → aria-valuenow under jsdom (gotcha #11), so the
+  // loss value is verified via the needle position + the accessible name.
+  it('exposes the progressbar role with the loss value in its accessible name', () => {
+    render(<FatigueMeter value={17} />)
+    expect(
+      screen.getByRole('progressbar', { name: 'Fatigue: 17% velocity loss' })
+    ).toBeInTheDocument()
+  })
+
+  describe('accessibility', () => {
+    it('has no accessibility violations', async () => {
+      const { container } = render(<FatigueMeter value={21} />)
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+  })
+})
+
+describe('FatigueMeter size="wall"', () => {
+  it('passes wall density through to the composed ZoneTrack (thicker needle)', () => {
+    render(<FatigueMeter value={20} size="wall" />)
+    expect(screen.getByTestId('zone-track-needle')).toHaveStyle({ width: '7px' })
+  })
+
+  it('keeps the compact needle by default', () => {
+    render(<FatigueMeter value={20} />)
+    expect(screen.getByTestId('zone-track-needle')).toHaveStyle({ width: '4px' })
+  })
+})

package/src/components/custom/Workout/FatigueMeter.tsx

@@ -0,0 +1,86 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import type { ViewProps } from 'react-native'
+import { WORKOUT_TOKENS } from '../../../theme/workout-tokens'
+import { ZoneTrack, type ZoneTrackZone, type ZoneTrackTick, type ZoneTrackSize } from './ZoneTrack'
+
+const { green, yellow, orange, red } = WORKOUT_TOKENS.scale
+
+/** Canonical fatigue band colours (fresh → stop) — the even effort-scale hue walk. */
+const DEFAULT_ZONE_COLORS: [string, string, string, string] = [green, yellow, orange, red]
+/** Zone boundaries in velocity-loss %, matching the VL10/VL20/VL30 coaching cues. */
+const DEFAULT_THRESHOLDS: [number, number, number] = [10, 20, 30]
+/** Scale labels at [min, ...thresholds, max]. */
+const DEFAULT_LABELS = ['fresh', 'VL10', 'VL20', 'VL30', 'stop']
+const DEFAULT_MAX = 40
+
+export interface FatigueMeterProps extends ViewProps {
+  /** Current velocity-loss percentage (0 = fresh). Drives the needle position. */
+  value: number
+  /** Upper bound of the fatigue scale — the "stop" end, in loss %. Default 40. */
+  max?: number
+  /** Zone boundary thresholds (loss %): green→gold, gold→orange, orange→red. Default [10,20,30]. */
+  thresholds?: [number, number, number]
+  /** Zone band colours low→high (fresh→stop). Default the canonical effort scale. */
+  zoneColors?: [string, string, string, string]
+  /** Tick labels at [min, ...thresholds, max]. Default ['fresh','VL10','VL20','VL30','stop']. */
+  labels?: string[]
+  /** Density: `default` (compact) or `wall` (the across-the-room dashboard scale — bigger track, needle and tick labels). */
+  size?: ZoneTrackSize
+  /** Track height in px. Overrides the `size` default (14 default / 24 wall). */
+  trackHeight?: number
+  /** Needle colour. Default white. */
+  needleColor?: string
+  className?: string
+}
+
+/**
+ * A fatigue meter: a sliding needle over a fixed green→gold→orange→red velocity-loss
+ * gradient with VL10/VL20/VL30/stop scale markers. This is the winning fatigue-visual
+ * lineage (needle-over-zoned-gradient, three independent sources agreed) — it composes
+ * the shared {@link ZoneTrack} primitive, supplying the fatigue domain, zone bands from
+ * the effort-scale tokens, and the coaching-cue tick labels. Prop-driven: `value` plus
+ * overridable `thresholds` / `max` / `zoneColors` / `labels`.
+ *
+ * @example
+ * <FatigueMeter value={21} />           // needle in the VL20 (orange) zone
+ * <FatigueMeter value={8} max={40} thresholds={[10, 20, 30]} />
+ */
+export function FatigueMeter({
+  value,
+  max = DEFAULT_MAX,
+  thresholds = DEFAULT_THRESHOLDS,
+  zoneColors = DEFAULT_ZONE_COLORS,
+  labels = DEFAULT_LABELS,
+  size = 'default',
+  trackHeight,
+  needleColor,
+  className,
+  ...props
+}: FatigueMeterProps) {
+  const [t1, t2, t3] = thresholds
+  const zones: ZoneTrackZone[] = [
+    { upTo: t1, color: zoneColors[0] },
+    { upTo: t2, color: zoneColors[1] },
+    { upTo: t3, color: zoneColors[2] },
+    { upTo: max, color: zoneColors[3] },
+  ]
+
+  const tickValues = [0, t1, t2, t3, max]
+  const ticks: ZoneTrackTick[] = tickValues.map((v, i) => ({ value: v, label: labels[i] }))
+
+  return (
+    <ZoneTrack
+      className={className}
+      zones={zones}
+      min={0}
+      max={max}
+      size={size}
+      trackHeight={trackHeight}
+      ticks={ticks}
+      marker={{ type: 'needle', value, color: needleColor }}
+      accessibilityLabel={`Fatigue: ${value}% velocity loss`}
+      testID="fatigue-meter"
+      {...props}
+    />
+  )
+}

package/src/components/custom/Workout/InputBar.stories.tsx

@@ -4,7 +4,7 @@ import { View } from 'react-native'
 import { InputBar } from './InputBar'
 
 const meta: Meta<typeof InputBar> = {
-  title: 'Custom/Workout/InputBar',
+  title: 'Workout/InputBar',
   component: InputBar,
   tags: ['autodocs'],
   argTypes: {

package/src/components/custom/Workout/IntensityBar.stories.tsx

@@ -3,7 +3,7 @@ import { View } from 'react-native'
 import { IntensityBar } from './IntensityBar'
 
 const meta: Meta<typeof IntensityBar> = {
-  title: 'Custom/Workout/IntensityBar',
+  title: 'Workout/DataViz/IntensityBar',
   component: IntensityBar,
   tags: ['autodocs'],
   argTypes: {

package/src/components/custom/Workout/LiveAuraFrame.stories.tsx

@@ -0,0 +1,153 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
+import { LiveAuraFrame } from './LiveAuraFrame'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+const t = getSemanticColors('dark')
+
+/** A representative live-workout hero so the full-surface flood reads against real content. */
+function LiveHero({ caption }: { caption: string }) {
+  return (
+    <View style={{ flex: 1, padding: 24, justifyContent: 'space-between' }}>
+      <View>
+        <Text
+          style={{
+            fontSize: 11,
+            fontWeight: '800',
+            letterSpacing: 1.2,
+            textTransform: 'uppercase',
+            color: t['text-tertiary'],
+          }}
+        >
+          Cable Row · Set 4 / 5
+        </Text>
+      </View>
+
+      <View style={{ alignItems: 'center' }}>
+        <Text
+          style={{ fontSize: 96, fontWeight: '800', lineHeight: 100, color: t['text-primary'] }}
+        >
+          8
+        </Text>
+        <Text
+          style={{
+            fontSize: 12,
+            letterSpacing: 2,
+            textTransform: 'uppercase',
+            color: t['text-tertiary'],
+          }}
+        >
+          reps
+        </Text>
+      </View>
+
+      <View>
+        <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginBottom: 12 }}>
+          {[
+            ['0.42', 'm/s'],
+            ['8.5', 'RPE'],
+            ['−18%', 'vel loss'],
+          ].map(([v, l]) => (
+            <View key={l} style={{ alignItems: 'center' }}>
+              <Text style={{ fontSize: 20, fontWeight: '700', color: t['text-primary'] }}>{v}</Text>
+              <Text
+                style={{
+                  fontSize: 9,
+                  letterSpacing: 1,
+                  textTransform: 'uppercase',
+                  color: t['text-tertiary'],
+                }}
+              >
+                {l}
+              </Text>
+            </View>
+          ))}
+        </View>
+        <Text style={{ fontSize: 12, color: t['text-secondary'], textAlign: 'center' }}>
+          {caption}
+        </Text>
+      </View>
+    </View>
+  )
+}
+
+const PANEL = { width: 360, height: 620, borderRadius: 24, overflow: 'hidden' as const }
+
+const meta: Meta<typeof LiveAuraFrame> = {
+  title: 'Workout/LiveAuraFrame',
+  component: LiveAuraFrame,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Full-surface color-flood frame tied to a coaching category. Wraps content on a charcoal ' +
+          'base and layers a radial wash — amber at threshold (VL20), red at stop (VL28+, pulsing) — ' +
+          'derived from the semantic warning / error tokens via `alpha()`. Children pass through. ' +
+          'Rendered here at live-screen size so the flood reads (it is meant to tint a whole panel, ' +
+          'not a card).',
+      },
+    },
+  },
+  argTypes: {
+    category: {
+      control: 'select',
+      options: ['productive', 'threshold', 'stop'],
+      description: 'Coaching-category flood level',
+    },
+    pulse: { control: 'boolean', description: 'Pulse the flood on stop' },
+  },
+  decorators: [
+    (Story) => (
+      <View
+        style={{
+          minHeight: 700,
+          backgroundColor: '#070707',
+          alignItems: 'center',
+          justifyContent: 'center',
+          padding: 32,
+        }}
+      >
+        <Story />
+      </View>
+    ),
+  ],
+  render: (args) => (
+    <LiveAuraFrame {...args} style={PANEL}>
+      <LiveHero
+        caption={
+          args.category === 'stop'
+            ? 'red flood — VL28+, stop the set'
+            : args.category === 'threshold'
+              ? 'amber flood — VL20 threshold reached'
+              : 'no flood — productive, quiet background'
+        }
+      />
+    </LiveAuraFrame>
+  ),
+}
+
+export default meta
+type Story = StoryObj<typeof LiveAuraFrame>
+
+export const Productive: Story = { args: { category: 'productive' } }
+export const Threshold: Story = { args: { category: 'threshold' } }
+export const Stop: Story = { args: { category: 'stop' } }
+
+/** All three flood levels side by side at live-screen size. */
+export const AllStates: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 20, flexWrap: 'wrap', justifyContent: 'center' }}>
+      <LiveAuraFrame category="productive" style={PANEL}>
+        <LiveHero caption="no flood — productive" />
+      </LiveAuraFrame>
+      <LiveAuraFrame category="threshold" style={PANEL}>
+        <LiveHero caption="amber flood — VL20 threshold" />
+      </LiveAuraFrame>
+      <LiveAuraFrame category="stop" pulse={false} style={PANEL}>
+        <LiveHero caption="red flood — VL28+, stop" />
+      </LiveAuraFrame>
+    </View>
+  ),
+}

package/src/components/custom/Workout/LiveAuraFrame.test.tsx

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { Text } from 'react-native'
+import { LiveAuraFrame, liveAuraColor, type LiveAuraCategory } from './LiveAuraFrame'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { alpha } from '../../../utils/colors'
+
+const t = getSemanticColors('dark')
+
+describe('LiveAuraFrame', () => {
+  it('renders the frame and passes children through', () => {
+    render(
+      <LiveAuraFrame category="productive">
+        <Text>Cable Row</Text>
+      </LiveAuraFrame>
+    )
+    expect(screen.getByTestId('live-aura-frame')).toBeInTheDocument()
+    expect(screen.getByText('Cable Row')).toBeInTheDocument()
+  })
+
+  it('sits on the charcoal base surface', () => {
+    render(<LiveAuraFrame category="productive" />)
+    expect(screen.getByTestId('live-aura-frame')).toHaveStyle({
+      backgroundColor: t['background-base'],
+    })
+  })
+
+  it('renders no flood overlay for the productive (quiet) category', () => {
+    render(<LiveAuraFrame category="productive" />)
+    expect(screen.queryByTestId('live-aura-flood')).not.toBeInTheDocument()
+  })
+
+  const floods: Array<{
+    category: LiveAuraCategory
+    token: 'status-warning' | 'status-error'
+    opacity: number
+  }> = [
+    { category: 'threshold', token: 'status-warning', opacity: 0.12 },
+    { category: 'stop', token: 'status-error', opacity: 0.18 },
+  ]
+
+  floods.forEach(({ category, token, opacity }) => {
+    it(`floods ${category} with a ${token}-tinted radial wash that fades to transparent`, () => {
+      render(<LiveAuraFrame category={category} />)
+      // Web (the target): a top-down radial gradient tinted with the token color,
+      // fading to transparent — matches R2's .aura-* CSS, NOT a flat surface fill.
+      const flood = screen.getByTestId('live-aura-flood') as HTMLElement
+      expect(flood.style.backgroundImage).toContain(alpha(t[token], opacity))
+      expect(flood.style.backgroundImage).toContain('transparent')
+      expect(flood.style.backgroundColor).toBe('')
+    })
+  })
+
+  it('exposes the resolved flood color via liveAuraColor', () => {
+    expect(liveAuraColor('productive')).toBeNull()
+    expect(liveAuraColor('threshold')).toBe(t['status-warning'])
+    expect(liveAuraColor('stop')).toBe(t['status-error'])
+  })
+
+  it('renders the flood for stop when pulse is disabled', () => {
+    render(<LiveAuraFrame category="stop" pulse={false} />)
+    expect(screen.getByTestId('live-aura-flood')).toBeInTheDocument()
+  })
+
+  it('has no a11y violations', async () => {
+    const { container } = render(
+      <LiveAuraFrame category="stop">
+        <Text>Set 4/5</Text>
+      </LiveAuraFrame>
+    )
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})