@titan-design/react-ui 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@titan-design/react-ui",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Cross-platform design system built on Gluestack UI",
   "author": "Henry Jewkes",
   "license": "MIT",

package/src/components/custom/CircularTimer/CircularTimer.stories.tsx

@@ -0,0 +1,90 @@
+import type { Decorator, Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text, Pressable } from 'react-native'
+import { CircularTimer } from './CircularTimer'
+
+const meta: Meta<typeof CircularTimer> = {
+  title: 'Custom/CircularTimer',
+  component: CircularTimer,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A circular countdown / countup with an mm:ss readout in the center — the graphical ' +
+          'sibling of `TimerReadout`. Batteries-included: owns `useTimer` (pass controlled ' +
+          '`durationMs` + `elapsedMs`) and composes `CircularProgress` for the arc (`down` drains, ' +
+          '`up` fills). On completion a `down` timer with a `doneLabel` fills fully in `doneColor` ' +
+          'and reads the label (e.g. "GO"). Pass `controls` to render buttons below the ring, or ' +
+          "`fill` to make it responsive to its container. `RestTimer`'s `ring` variant wraps this.",
+      },
+    },
+  },
+  argTypes: {
+    mode: { control: 'inline-radio', options: ['down', 'up'] },
+    size: { control: { type: 'number', min: 96, max: 280, step: 4 } },
+    fill: { control: 'boolean' },
+    doneLabel: { control: 'text' },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof CircularTimer>
+
+const dark: Decorator = (Story) => (
+  <View style={{ padding: 32, alignItems: 'center', backgroundColor: '#0E0E0E' }}>
+    <Story />
+  </View>
+)
+
+/** Controls-driven: flip `mode` / `durationMs` / `elapsedMs` / `size` / `doneLabel`. */
+export const Playground: Story = {
+  args: { durationMs: 120000, elapsedMs: 47000, doneLabel: 'GO', size: 180 },
+  decorators: [dark],
+}
+
+/** Countdown, midway — the ring drains from full. */
+export const CountdownMidway: Story = {
+  args: { mode: 'down', durationMs: 120000, elapsedMs: 60000, size: 180 },
+  decorators: [dark],
+}
+
+/** Countup — the ring fills as time elapses. */
+export const CountupMidway: Story = {
+  args: { mode: 'up', durationMs: 120000, elapsedMs: 40000, size: 180 },
+  decorators: [dark],
+}
+
+/** Completed countdown with a done label — full ring, flips to success, reads "GO". */
+export const DoneWithLabel: Story = {
+  args: { mode: 'down', durationMs: 120000, elapsedMs: 120000, doneLabel: 'GO', size: 180 },
+  decorators: [dark],
+}
+
+const DemoButton = ({ label }: { label: string }) => (
+  <Pressable
+    style={{
+      backgroundColor: 'rgba(255,255,255,0.06)',
+      paddingVertical: 8,
+      paddingHorizontal: 20,
+      borderRadius: 8,
+    }}
+  >
+    <Text style={{ color: '#DADADA', fontSize: 11, fontWeight: '600' }}>{label}</Text>
+  </Pressable>
+)
+
+/** With controls rendered below the ring. */
+export const WithControls: Story = {
+  args: {
+    durationMs: 120000,
+    elapsedMs: 47000,
+    size: 180,
+    controls: (
+      <View style={{ flexDirection: 'row', gap: 8 }}>
+        <DemoButton label="+30s" />
+        <DemoButton label="Skip" />
+      </View>
+    ),
+  },
+  decorators: [dark],
+}

package/src/components/custom/CircularTimer/CircularTimer.test.tsx

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { axe } from 'jest-axe'
+import { Text } from 'react-native'
+import { CircularTimer } from './CircularTimer'
+
+describe('CircularTimer', () => {
+  it('renders a timer with a composed progressbar ring', () => {
+    render(<CircularTimer durationMs={120000} elapsedMs={30000} />)
+    expect(screen.getByTestId('circular-timer')).toBeInTheDocument()
+    expect(screen.getByRole('progressbar')).toBeInTheDocument()
+  })
+
+  it('shows the mm:ss remaining in the center while counting down', () => {
+    render(<CircularTimer durationMs={120000} elapsedMs={60000} />)
+    expect(screen.getByTestId('circular-timer-label')).toHaveTextContent('1:00')
+  })
+
+  it('shows the elapsed mm:ss in up mode', () => {
+    render(<CircularTimer mode="up" durationMs={120000} elapsedMs={45000} />)
+    expect(screen.getByTestId('circular-timer-label')).toHaveTextContent('0:45')
+  })
+
+  it('renders the done label (not a time) when a countdown completes', () => {
+    render(<CircularTimer durationMs={120000} elapsedMs={120000} doneLabel="GO" />)
+    expect(screen.getByTestId('circular-timer-label')).toHaveTextContent('GO')
+  })
+
+  it('keeps showing 0:00 at completion when no doneLabel is given', () => {
+    render(<CircularTimer durationMs={120000} elapsedMs={120000} />)
+    expect(screen.getByTestId('circular-timer-label')).toHaveTextContent('0:00')
+  })
+
+  it('renders optional controls below the ring', () => {
+    render(<CircularTimer durationMs={120000} elapsedMs={0} controls={<Text>+30s</Text>} />)
+    expect(screen.getByText('+30s')).toBeInTheDocument()
+  })
+
+  it('defaults its accessibility label to seconds remaining', () => {
+    render(<CircularTimer durationMs={120000} elapsedMs={60000} />)
+    expect(screen.getAllByLabelText('60 seconds remaining').length).toBeGreaterThan(0)
+  })
+
+  it('uses a supplied accessibility label', () => {
+    render(
+      <CircularTimer durationMs={120000} elapsedMs={60000} accessibilityLabel="Rest, 60s left" />
+    )
+    expect(screen.getAllByLabelText('Rest, 60s left').length).toBeGreaterThan(0)
+  })
+
+  it('emits no NaN when durationMs is 0 (guard)', () => {
+    const { container } = render(<CircularTimer durationMs={0} elapsedMs={0} />)
+    expect(container.innerHTML).not.toContain('NaN')
+  })
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <CircularTimer durationMs={120000} elapsedMs={30000} accessibilityLabel="Rest countdown" />
+    )
+    expect(await axe(container)).toHaveNoViolations()
+  })
+})

package/src/components/custom/CircularTimer/CircularTimer.tsx

@@ -0,0 +1,112 @@
+// Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
+import type { ReactNode } from 'react'
+import { View, Text } from 'react-native'
+import { CircularProgress, colorVarMap, type ProgressColor } from '../../ui/progress/Progress'
+import { useTimer, type TimerMode } from '../../../hooks/useTimer'
+
+export interface CircularTimerProps {
+  /** Total duration (ms). `down`: the countdown length; `up`: the target for progress. */
+  durationMs: number
+  /** Controlled elapsed time (ms). */
+  elapsedMs: number
+  /** `down` (default) counts remaining toward 0 (ring drains); `up` counts elapsed up (ring fills). */
+  mode?: TimerMode
+  /** Ring diameter (px) — the geometry/stroke reference. Default 160. */
+  size?: number
+  /** Ring stroke width (px). Default 8. */
+  strokeWidth?: number
+  /** Fill the parent container (responsive) instead of a fixed `size` box. */
+  fill?: boolean
+  /** Ring color while running. Default `primary`. */
+  color?: ProgressColor
+  /**
+   * `down` mode: the text shown in the center — and the color the ring fills to — when
+   * the countdown completes (e.g. `doneLabel="GO"`). Omit to keep showing `0:00`.
+   */
+  doneLabel?: string
+  /** Ring + center color when complete (with {@link doneLabel}). Default `success`. */
+  doneColor?: ProgressColor
+  /** Optional controls rendered below the ring (e.g. +30s / Skip). */
+  controls?: ReactNode
+  /** Accessibility label for the timer. Defaults to a seconds-remaining description. */
+  accessibilityLabel?: string
+  testID?: string
+}
+
+/**
+ * A circular countdown / countup with a time readout in the center — the graphical
+ * sibling of {@link TimerReadout}. Batteries-included: owns {@link useTimer} (pass
+ * controlled `durationMs` + `elapsedMs`) and composes {@link CircularProgress} for the
+ * arc (`down` drains as time runs out, `up` fills), rendering the mm:ss label in its
+ * center slot. On completion (`down` + {@link doneLabel}) the ring fills fully in
+ * {@link doneColor} and the center reads the done label — the "go" moment. An optional
+ * {@link controls} node renders below the ring. Consumers (e.g. `RestTimer`'s `ring`
+ * variant) wrap this and add their own domain chrome.
+ */
+export function CircularTimer({
+  durationMs,
+  elapsedMs,
+  mode = 'down',
+  size = 160,
+  strokeWidth = 8,
+  fill = false,
+  color = 'primary',
+  doneLabel,
+  doneColor = 'success',
+  controls,
+  accessibilityLabel,
+  testID,
+}: CircularTimerProps) {
+  const { remainingMs, progress, label, done } = useTimer({ mode, durationMs, elapsedMs })
+
+  const isDone = done && mode === 'down'
+  const showDone = isDone && doneLabel != null
+  // Down → the remaining fraction (ring drains); up → elapsed progress (ring fills).
+  // A completed countdown with a done label fills fully to signal "go".
+  const remainingFrac = durationMs > 0 ? Math.max(0, Math.min(1, remainingMs / durationMs)) : 0
+  const arc = mode === 'down' ? (showDone ? 1 : remainingFrac) : progress
+  const ringColor: ProgressColor = showDone ? doneColor : color
+
+  const remainingSec = Math.ceil(Math.max(0, remainingMs) / 1000)
+  const a11y =
+    accessibilityLabel ?? (isDone ? 'Timer complete' : `${remainingSec} seconds remaining`)
+
+  return (
+    <View
+      style={{ alignItems: 'center', gap: 16 }}
+      accessibilityRole="timer"
+      accessibilityLabel={a11y}
+      testID={testID ?? 'circular-timer'}
+    >
+      <CircularProgress
+        value={arc}
+        max={1}
+        size={size}
+        strokeWidth={strokeWidth}
+        fill={fill}
+        color={ringColor}
+        // A distinct static name for the ring (the live countdown text lives on the
+        // enclosing timer role) — satisfies the progressbar-name a11y rule without
+        // duplicating the timer label.
+        accessibilityLabel="Timer ring"
+        testID="circular-timer-ring"
+      >
+        <Text
+          className={showDone ? undefined : 'text-text-primary'}
+          style={{
+            fontSize: Math.round(size * (showDone ? 0.28 : 0.24)),
+            fontFamily: '"Space Grotesk", sans-serif',
+            fontWeight: '800',
+            fontVariant: ['tabular-nums'],
+            letterSpacing: showDone ? 1 : -1,
+            ...(showDone ? { color: colorVarMap[doneColor] } : null),
+          }}
+          testID="circular-timer-label"
+        >
+          {showDone ? doneLabel : label}
+        </Text>
+      </CircularProgress>
+      {controls}
+    </View>
+  )
+}

package/src/components/custom/CircularTimer/index.ts

@@ -0,0 +1 @@
+export { CircularTimer, type CircularTimerProps } from './CircularTimer'

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

@@ -12,7 +12,7 @@ import {
   type IconProps,
 } from '../../icons'
 
-// Literal-hex status pins (the TempoBar pattern) — `resolveColor()` yields a
+// Literal-hex status pins (getSemanticColors, not resolveColor) — `resolveColor()` yields a
 // `var(...)` under the RNW vitest alias, which breaks `toHaveStyle` in tests.
 const t = getSemanticColors('dark')
 

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

@@ -42,8 +42,8 @@ export const Vl20: Story = { args: { value: 21 } }
 /** Stop zone — deep into the red. */
 export const StopZone: Story = { args: { value: 34 } }
 
-/** Chunky wall-glanceable density via a taller track. */
-export const WallDensity: Story = { args: { value: 21, trackHeight: 22 } }
+/** 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 = {

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

@@ -71,3 +71,15 @@ describe('FatigueMeter', () => {
     })
   })
 })
+
+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

@@ -1,7 +1,7 @@
 // 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 } from './ZoneTrack'
+import { ZoneTrack, type ZoneTrackZone, type ZoneTrackTick, type ZoneTrackSize } from './ZoneTrack'
 
 const { green, yellow, orange, red } = WORKOUT_TOKENS.scale
 
@@ -24,7 +24,9 @@ export interface FatigueMeterProps extends ViewProps {
   zoneColors?: [string, string, string, string]
   /** Tick labels at [min, ...thresholds, max]. Default ['fresh','VL10','VL20','VL30','stop']. */
   labels?: string[]
-  /** Track height in px. Default 14. */
+  /** 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
@@ -49,7 +51,8 @@ export function FatigueMeter({
   thresholds = DEFAULT_THRESHOLDS,
   zoneColors = DEFAULT_ZONE_COLORS,
   labels = DEFAULT_LABELS,
-  trackHeight = 14,
+  size = 'default',
+  trackHeight,
   needleColor,
   className,
   ...props
@@ -71,6 +74,7 @@ export function FatigueMeter({
       zones={zones}
       min={0}
       max={max}
+      size={size}
       trackHeight={trackHeight}
       ticks={ticks}
       marker={{ type: 'needle', value, color: needleColor }}

package/src/components/custom/Workout/README.md

@@ -8,7 +8,7 @@ component is pure import churn with no file moves.
 ## Tier map
 
 **Atoms** — single-purpose, no cross-component state:
-BaseBadge · WeightBadge · PrBadge · StatusDot · PlaceholderStrip · TempoBar ·
+BaseBadge · WeightBadge · PrBadge · StatusDot · PlaceholderStrip ·
 DeviationBar · IntensityBar · WorkoutPill · MuscleGroupChip · Sparkline ·
 SupersetWrapper · InputBar · MetricCell · SetsRepsLoad · ExerciseIndicator · SetBar
 
@@ -48,6 +48,29 @@ type props without pulling the dependency.
   letter-spacing-1 value/separator cell. `TempoDisplay` (tempo digits) and
   `SetsRepsLoad` (sets × reps @ load) both compose it so the two read as one
   visual language. Exported for composition, not for direct app use.
+- **TempoDisplay is deliberately NOT decomposed further** — it is the single tempo
+  component (the standalone `TempoBar` was retired into it). It renders two modes from
+  one chip: the static phase-coloured **prescription** and, with the `live` prop, the
+  running tempo (per-phase countdown/count-up to 0.1s, a bottom-anchored phase-progress
+  fill, semantic pacing tones, and banked/frozen finals). Its internal parts —
+  `LiveTempoRow`, `LiveTempoCell`, `CellFill` (the fill behind a number), and the
+  `activeNumberTone` pacing helper — are **TempoDisplay-private with no second consumer**,
+  so per the ≥2-consumer rule they stay internal rather than becoming top-level primitives.
+  The only already-shared primitive is `MetricCell`.
+
+  **If reuse emerges, decompose along these seams** (in likely order):
+  1. **`CellFill` → a shared `ProgressCell`/`FillBehind` primitive** — the moment a
+     second component needs "a bottom-anchored progress fill behind centred text" (e.g. a
+     generic timer/meter cell). Cleanest extraction; pure presentation, no tempo semantics.
+  2. **`activeNumberTone` + `ON_TARGET_MS` → a `tempo-pacing` util** — if another surface
+     needs the same yellow/green/red "time-to-target" tone (a coach card, a rep-tempo
+     summary). It is pure logic, trivially portable.
+  3. **`LiveTempoRow` → a `TempoLiveRow` molecule** — only if a consumer wants the running
+     row *without* the chip chrome (label/background/padding). Until then the chrome and the
+     row belong together as one component with a `live` prop, not two.
+
+  Not worth splitting today (speculative extraction the workflow warns against); this note
+  is the trigger list for when it stops being speculative.
 - **S3 session-rail family** — `SessionRail` (organism) composes the standalone
   `ExerciseCardHeading` molecule per exercise, which composes an `ExerciseHeading`
   info block + a `SetStrip`:
@@ -112,14 +135,58 @@ type props without pulling the dependency.
   with a copy-paste `set` config in **`Workout/DataViz/VelocityStrip/Set
   Modalities`** (each card carries a `Collapse` accordion; promoted from the
   now-deleted `S3SetModalities` Lab specimen).
+- **VelocityStrip `hero` variant** — the across-the-room, single-set **wall**
+  treatment (the north-star live page's velocity hero). Tall bars (default 220px
+  plot) with a per-bar velocity value label, a dashed **running-best reference
+  line** (unlabeled — the tallest bar already shows the number, and the container
+  a11y label carries it), and dashed **placeholders for the reps still to come**
+  driven by a new `targetReps` prop. Absorbs the R2 `HeroVelocityBars` candidate
+  into the atom rather than shipping a parallel component. Reuses the shared zone
+  scale (`barColorFor`) and the extracted `useLiveRepPop` entrance (now shared with
+  the framed `expanded` chart). **Layout:** width-fluid (flex bars, capped at 52px,
+  left-packed) with a caller-set fixed height; the eyebrow/section title is
+  organism chrome, not part of the primitive. **Live-update model:** the plan's
+  slots are pre-allocated (`max(done, target)` columns), so a landing rep converts
+  placeholder→bar in the *same* slot with a pop — no reflow within the plan; pair
+  with `scale="fixed"` so heights never rescale either. The one reflow case is
+  set-expansion **beyond** `targetReps` (AMRAP overflow adds a column and flex-
+  narrows the rest — currently snaps; smooth overflow reflow is a deferred
+  follow-up). Documented by the `HeroPlayground` / `Hero*` stories on the wall
+  background.
+- **RestTimer `ring` variant** — the across-the-room **wall** rest treatment (the
+  north-star rest page). Built as a **three-tier decomposition** (not a one-off):
+  `CircularProgress` (atom, gained a **`children`** center slot + a **`fill`**
+  responsive mode) → **`CircularTimer`** (new molecule, `custom/CircularTimer/` — a
+  batteries-included circular countdown/countup; owns `useTimer`, renders the mm:ss
+  readout into the ring center, flips a completed `down` timer to a full `doneColor`
+  ring reading its `doneLabel`, and takes an optional `controls` slot) → **RestTimer
+  `ring`** which composes `CircularTimer` (`doneLabel="GO"`, `doneColor="success"`,
+  `controls={<RestActions/>}`) and adds the rest-specific next-set footer caption.
+  No third copy of the arc math and no `react-native-svg` — it rides
+  `CircularProgress`'s web-`<svg>` + free `stroke-dashoffset` transition. Absorbs
+  the R2 `RestRing` candidate into the atom; the mobile `CircularTimer` countup fork
+  is the natural second consumer of the new molecule (via `mode="up"`). `displayOnly`
+  hides the shared `RestActions` (+30s/Skip, extracted, used by both variants);
+  `size` (default 180) sets the diameter; the eyebrow/section title is organism
+  chrome. Web/RNW-only (like `CircularProgress`) — the wall variant; mobile keeps
+  `bar`. `Ring*` (RestTimer) + `Custom/CircularTimer` stories on the wall background.
+- **`size="wall"` density (FatigueMeter · ZoneTrack)** — the across-the-room
+  dashboard scale, added as the idiomatic titan `size` union (a JS number-map per
+  component; **`default` values are byte-identical** to before, so existing consumers are
+  untouched). **ZoneTrack** (the shared gauge primitive) gained `size` that scales track,
+  needle, tick lines and tick labels together; its *other* consumers (TrainingLoadGauge,
+  RpeCalibration) default to `default` and are unaffected. **FatigueMeter** passes `size`
+  through and lets `trackHeight` flow from it. `Wall*` / `WallDensity` stories on the wall
+  background. (**TempoBar** was retired here — the standalone active-tempo bar is superseded
+  by `TempoDisplay`'s live mode; see the TempoDisplay note.)
 - Badge icons (WeightBadge's dumbbell, PrBadge / PrHistoryModal's star) are inline
   SVGs (`./icons.tsx`), not `lucide-react` — that dependency was dropped in 0.5.0
   to keep the root barrel light. The SVG paths mirror lucide's glyphs so rendering
   is unchanged.
 - **`ExerciseIndicator` taxonomy (LOCKED, TD-03.51)** — one precedence-ranked slot
   per exercise, six distinct kinds over four tier colors (bound to titan status
-  tokens, read as literal hex via `getSemanticColors('dark')` — the TempoBar
-  pattern). Glyph = the specific signal; color = the severity tier. Chips are
+  tokens, read as literal hex via `getSemanticColors('dark')`, not `resolveColor`,
+  so tests can assert them). Glyph = the specific signal; color = the severity tier. Chips are
   outlined (border + glyph, no fill) so they never collide with the *filled*
   velocity strip, and static (no pulse — they are chrome). Precedence, high → low:
 

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

@@ -1,12 +1,31 @@
-import React from 'react'
-import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { Decorator, Meta, StoryObj } from '@storybook/react-vite'
+import { View, Text } from 'react-native'
 import { RestTimer } from './RestTimer'
 
 const meta: Meta<typeof RestTimer> = {
   title: 'Workout/RestTimer',
   component: RestTimer,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Controlled rest countdown (presentational off `useTimer`; pass `totalSeconds` + ' +
+          '`elapsedMs`). Two variants: `bar` (default) — the compact linear card (REST label + ' +
+          'mm:ss + progress bar + controls), the mobile bottom-bar treatment; and `ring` — the ' +
+          'across-the-room wall treatment: a draining countdown ring (composes `CircularProgress`) ' +
+          'with the mm:ss countdown in its center, flipping to a full `success` ring reading "GO" ' +
+          'when rest is up. `displayOnly` hides the +30s/Skip controls in either variant; `size` ' +
+          'sets the ring diameter.',
+      },
+    },
+  },
   argTypes: {
+    variant: {
+      control: 'inline-radio',
+      options: ['bar', 'ring'],
+      description: 'bar (compact linear card) or ring (wall countdown)',
+    },
     totalSeconds: {
       control: 'number',
       description: 'Total rest duration in seconds',
@@ -15,6 +34,10 @@ const meta: Meta<typeof RestTimer> = {
       control: 'number',
       description: 'Elapsed time in milliseconds',
     },
+    size: {
+      control: { type: 'number', min: 96, max: 280, step: 4 },
+      description: 'ring diameter in px (default 180)',
+    },
     visible: {
       control: 'boolean',
       description: 'Whether the timer is visible',
@@ -69,3 +92,110 @@ export const JustStarted: Story = {
     visible: true,
   },
 }
+
+// --- Ring variant ------------------------------------------------------------
+// The across-the-room wall rest treatment. Rendered on the north-star wall
+// background so the draining ring reads the way it will live.
+
+/** Wall-background frame for the ring stories (mirrors the north-star rest page). */
+const ringDecorator: Decorator = (Story) => (
+  <View style={{ width: 420, padding: 32, alignItems: 'center', backgroundColor: '#0E0E0E' }}>
+    <Text
+      style={{
+        color: '#5A5A5A',
+        fontSize: 10,
+        fontWeight: '700',
+        letterSpacing: 1,
+        marginBottom: 20,
+      }}
+    >
+      REST · UNTIL NEXT SET · (organism chrome — not the component)
+    </Text>
+    <Story />
+  </View>
+)
+
+/** Controls-driven ring: flip `totalSeconds` / `elapsedMs` / `size` / `displayOnly`. */
+export const RingPlayground: Story = {
+  args: {
+    variant: 'ring',
+    totalSeconds: 120,
+    elapsedMs: 47000,
+    nextSetInfo: 'Next · Bench Press · set 3 of 4',
+    onSkip: () => {},
+    onAddTime: () => {},
+    visible: true,
+  },
+  decorators: [ringDecorator],
+}
+
+/** Just started: the ring is nearly full and draining. */
+export const RingJustStarted: Story = {
+  args: {
+    variant: 'ring',
+    totalSeconds: 120,
+    elapsedMs: 8000,
+    nextSetInfo: 'Next · Bench Press · set 3 of 4',
+    onSkip: () => {},
+    onAddTime: () => {},
+    visible: true,
+  },
+  decorators: [ringDecorator],
+}
+
+/** Midway: half the rest has drained. */
+export const RingMidway: Story = {
+  args: {
+    variant: 'ring',
+    totalSeconds: 120,
+    elapsedMs: 60000,
+    nextSetInfo: 'Next · Bench Press · set 3 of 4',
+    onSkip: () => {},
+    onAddTime: () => {},
+    visible: true,
+  },
+  decorators: [ringDecorator],
+}
+
+/** Almost done: a sliver of ring left. */
+export const RingAlmostDone: Story = {
+  args: {
+    variant: 'ring',
+    totalSeconds: 120,
+    elapsedMs: 112000,
+    nextSetInfo: 'Next · Bench Press · set 3 of 4',
+    onSkip: () => {},
+    onAddTime: () => {},
+    visible: true,
+  },
+  decorators: [ringDecorator],
+}
+
+/** Rest is up: the ring empties and flips to success (go time). */
+export const RingDone: Story = {
+  args: {
+    variant: 'ring',
+    totalSeconds: 120,
+    elapsedMs: 120000,
+    nextSetInfo: 'Next · Bench Press · set 3 of 4',
+    onSkip: () => {},
+    onAddTime: () => {},
+    visible: true,
+  },
+  decorators: [ringDecorator],
+}
+
+/** Display-only ring (poll mode): the ring + next-set line, no controls. */
+export const RingDisplayOnly: Story = {
+  args: {
+    variant: 'ring',
+    totalSeconds: 120,
+    elapsedMs: 47000,
+    nextSetInfo: 'Next · Bench Press · set 3 of 4',
+    displayOnly: true,
+    onSkip: () => {},
+    onAddTime: () => {},
+    visible: true,
+  },
+  decorators: [ringDecorator],
+}