@titan-design/react-ui 0.13.0 → 0.14.0

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

@@ -1,5 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { Treemap, type TreemapDatum } from './Treemap'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+const t = getSemanticColors('dark')
 
 const meta: Meta<typeof Treemap> = {
   title: 'Custom/Charts/Treemap',
@@ -16,14 +19,14 @@ export default meta
 type Story = StoryObj<typeof Treemap>
 
 const sample: TreemapDatum[] = [
-  { id: 'router', value: 5035, color: '#F83030', label: 'router.ts' },
-  { id: 'engine', value: 4378, color: '#F83030', label: 'engine.ts' },
-  { id: 'linker', value: 1695, color: '#F4A736', label: 'linker.ts' },
-  { id: 'validate', value: 1288, color: '#F4A736', label: 'validate.ts' },
-  { id: 'hook', value: 1050, color: '#F4A736', label: 'hook.ts' },
-  { id: 'update', value: 890, color: '#5B9BD5', label: 'update.ts' },
-  { id: 'pool', value: 504, color: '#5B9BD5', label: 'pool.ts' },
-  { id: 'log', value: 342, color: '#5B9BD5', label: 'log.ts' },
+  { id: 'router', value: 5035, color: t['data-4'], label: 'router.ts' },
+  { id: 'engine', value: 4378, color: t['data-4'], label: 'engine.ts' },
+  { id: 'linker', value: 1695, color: t['data-6'], label: 'linker.ts' },
+  { id: 'validate', value: 1288, color: t['data-6'], label: 'validate.ts' },
+  { id: 'hook', value: 1050, color: t['data-6'], label: 'hook.ts' },
+  { id: 'update', value: 890, color: t['data-7'], label: 'update.ts' },
+  { id: 'pool', value: 504, color: t['data-7'], label: 'pool.ts' },
+  { id: 'log', value: 342, color: t['data-7'], label: 'log.ts' },
 ]
 
 export const Default: Story = {
@@ -33,7 +36,7 @@ export const Default: Story = {
 /** A single outlier under a linear scale swallows the canvas... */
 export const OutlierLinear: Story = {
   args: {
-    data: [{ id: 'mega', value: 205422, color: '#F83030', label: 'mega.ts' }, ...sample],
+    data: [{ id: 'mega', value: 205422, color: t['data-4'], label: 'mega.ts' }, ...sample],
     width: 560,
     height: 300,
     scale: 'linear',
@@ -43,7 +46,7 @@ export const OutlierLinear: Story = {
 /** ...the same data with a sqrt scale keeps every tile legible. */
 export const OutlierSqrt: Story = {
   args: {
-    data: [{ id: 'mega', value: 205422, color: '#F83030', label: 'mega.ts' }, ...sample],
+    data: [{ id: 'mega', value: 205422, color: t['data-4'], label: 'mega.ts' }, ...sample],
     width: 560,
     height: 300,
     scale: 'sqrt',

package/src/components/custom/Treemap/Treemap.tsx

@@ -2,6 +2,7 @@ import React from 'react'
 import { View, Text, Pressable, type ViewProps } from 'react-native'
 import { cn } from '../../../utils/cn'
 import { DATAVIZ_CATEGORICAL_PALETTE } from '../../../theme/extracted-colors-dataviz'
+import { primitiveColors } from '../../../theme/tokens/primitives'
 
 export interface TreemapDatum {
   /** Stable identity — returned by onPress and used as the React key. */
@@ -146,6 +147,7 @@ export function Treemap({
       {
         id: '__more__',
         value: restValue,
+        // VW-82: no token at this value (nearest surface-overlay #373635); proposed, not swapped.
         color: '#3a3a3a',
         label: `+${clean.length - (maxTiles - 1)} more`,
       },
@@ -177,12 +179,13 @@ export function Treemap({
               borderRadius: 3,
               opacity: selected ? 1 : 0.9,
               borderWidth: selected ? 2 : 0,
-              borderColor: '#ffffff',
+              borderColor: primitiveColors.white,
               padding: 4,
               overflow: 'hidden',
             }}
           >
             {labelFits && (
+              // VW-82: label on a data-coloured tile; no on-data token exists yet.
               <Text numberOfLines={2} className="text-[10px] font-semibold text-[#0b0b0b]">
                 {r.datum.label ?? r.datum.id}
               </Text>

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

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { ActiveWorkoutPage, type ActiveWorkoutExercise } from './ActiveWorkoutPage'
 import type { SetRowProps } from './SetRow'
+import { primitiveRamps } from '../../../theme/tokens/primitives'
 
 const velocities = (base: number): number[] =>
   Array.from({ length: 8 }, (_, i) => Number((base - i * 0.03).toFixed(2)))
@@ -109,7 +110,7 @@ const meta: Meta<typeof ActiveWorkoutPage> = {
     title: 'Push Day A',
     subtitle: 'Hypertrophy · Week 6 of 8',
     exercises,
-    supersets: [{ id: 'ss1', label: 'SS1', color: '#22D3EE' }],
+    supersets: [{ id: 'ss1', label: 'SS1', color: primitiveRamps.cyan[300] }],
     input: { reps: '8', weight: '195' },
     rest: { totalSeconds: 120, elapsedMs: 42_000, nextSetInfo: 'Set 3 · 8 × 195 lbs' },
   },

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

@@ -2,6 +2,10 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
 import { View, Text } from 'react-native'
 import { DumbbellIcon } from './icons'
 import { BaseBadge } from './BaseBadge'
+import { greyRamp } from '../../../theme/tokens/primitives'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+const t = getSemanticColors('dark')
 
 const meta: Meta<typeof BaseBadge> = {
   title: 'Custom/Workout/BaseBadge',
@@ -17,7 +21,7 @@ const meta: Meta<typeof BaseBadge> = {
 export default meta
 type Story = StoryObj<typeof BaseBadge>
 
-const Label = ({ children, color = '#9CA3AF' }: { children: string; color?: string }) => (
+const Label = ({ children, color = greyRamp[400] }: { children: string; color?: string }) => (
   <Text
     style={{
       fontFamily: '"Space Grotesk", sans-serif',
@@ -40,14 +44,14 @@ export const Plain: Story = {
 export const Pr: Story = {
   args: {
     variant: 'pr',
-    children: <Label color="#FF7900">PR</Label>,
+    children: <Label color={t['brand-primary']}>PR</Label>,
   },
 }
 
 export const WithIcon: Story = {
   args: {
     variant: 'plain',
-    icon: <DumbbellIcon size={12} color="#9CA3AF" strokeWidth={2} />,
+    icon: <DumbbellIcon size={12} color={greyRamp[400]} strokeWidth={2} />,
     children: <Label>225 lbs</Label>,
   },
 }
@@ -68,17 +72,17 @@ export const AllVariants: Story = {
       </View>
       <View style={{ flexDirection: 'row', gap: 12, alignItems: 'center' }}>
         <BaseBadge variant="pr" size="sm">
-          <Label color="#FF7900">PR</Label>
+          <Label color={t['brand-primary']}>PR</Label>
         </BaseBadge>
         <BaseBadge variant="pr" size="md">
-          <Label color="#FF7900">PR</Label>
+          <Label color={t['brand-primary']}>PR</Label>
         </BaseBadge>
         <BaseBadge variant="pr" size="lg">
-          <Label color="#FF7900">PR</Label>
+          <Label color={t['brand-primary']}>PR</Label>
         </BaseBadge>
       </View>
       <View style={{ flexDirection: 'row', gap: 12, alignItems: 'center' }}>
-        <BaseBadge icon={<DumbbellIcon size={12} color="#9CA3AF" strokeWidth={2} />}>
+        <BaseBadge icon={<DumbbellIcon size={12} color={greyRamp[400]} strokeWidth={2} />}>
           <Label>225 lbs</Label>
         </BaseBadge>
       </View>

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

@@ -2,6 +2,7 @@
 import { useState, type ReactNode } from 'react'
 import { View, Pressable, Animated, type ViewProps } from 'react-native'
 import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { alpha } from '../../../utils/colors'
 
 const t = getSemanticColors('dark')
 
@@ -32,8 +33,8 @@ export const baseBadgeSizeConfig: Record<
 const variantColors: Record<BaseBadgeVariant, { backgroundColor: string; borderColor: string }> = {
   plain: { backgroundColor: t['surface-raised'], borderColor: t['hairline-default'] },
   pr: {
-    backgroundColor: 'rgba(255, 121, 0, 0.12)',
-    borderColor: 'rgba(255, 121, 0, 0.3)',
+    backgroundColor: alpha(t['brand-primary'], 0.12),
+    borderColor: alpha(t['brand-primary'], 0.3),
   },
 }
 

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

@@ -5,6 +5,8 @@ import BodyHighlighter, { type ExtendedBodyPart, type Slug } from 'react-native-
 import { cn } from '../../../utils/cn'
 import { resolveColor } from '../../../theme/resolve-color'
 import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { primitiveColors } from '../../../theme/tokens/primitives'
+import { alpha } from '../../../utils/colors'
 import { getGlowShadow } from '../../../theme/elevation'
 import {
   MuscleGroup,
@@ -29,8 +31,8 @@ const Body = ((BodyHighlighter as unknown as { default?: typeof BodyHighlighter
 
 const BRAND_PRIMARY = getSemanticColors('dark')['brand-primary']
 
-const OUTLINE_FILL = 'rgba(255,255,255,0.08)'
-const OUTLINE_BORDER = 'rgba(255,255,255,0.12)'
+const OUTLINE_FILL = alpha(primitiveColors.white, 0.08)
+const OUTLINE_BORDER = alpha(primitiveColors.white, 0.12)
 const BODY_SCALE = 0.8 // 200x400 intrinsic -> ~160x320 px
 
 export interface BodyMapData {
@@ -278,7 +280,7 @@ function ViewToggle({ view, onViewChange }: ViewToggleProps) {
               paddingHorizontal: 12,
               paddingVertical: 4,
               borderRadius: 9999,
-              backgroundColor: active ? 'rgba(255,121,0,0.16)' : 'transparent',
+              backgroundColor: active ? alpha(BRAND_PRIMARY, 0.16) : 'transparent',
               borderWidth: 1,
               borderColor: active ? BRAND_PRIMARY : resolveColor('hairline-strong'),
             }}

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

@@ -8,6 +8,10 @@ import {
 } from './BodyMapDetailPanel'
 import { MuscleGroup } from './muscleTaxonomy'
 import { Surface } from '../../ui/surface'
+import { primitiveColors } from '../../../theme/tokens/primitives'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+const t = getSemanticColors('dark')
 
 const contributing: ContributingExercise[] = [
   { name: 'Barbell Bench Press', sets: 4, contributionWeight: 1 },
@@ -141,7 +145,7 @@ function InteractiveBodyMapDetailPanel() {
         position: 'relative',
         height: 640,
         width: 380,
-        backgroundColor: '#0E0E0E',
+        backgroundColor: t['background-frame'],
         padding: 16,
       }}
     >
@@ -150,13 +154,19 @@ function InteractiveBodyMapDetailPanel() {
         accessibilityRole="button"
         style={{
           alignSelf: 'flex-start',
-          backgroundColor: '#FF7900',
+          backgroundColor: t['brand-primary'],
           paddingVertical: 10,
           paddingHorizontal: 20,
           borderRadius: 8,
         }}
       >
-        <Text style={{ color: '#FFFFFF', fontWeight: '700', fontFamily: 'Inter, sans-serif' }}>
+        <Text
+          style={{
+            color: primitiveColors.white,
+            fontWeight: '700',
+            fontFamily: 'Inter, sans-serif',
+          }}
+        >
           Tap Chest
         </Text>
       </Pressable>

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

@@ -19,7 +19,9 @@ import {
   type VolumeStatus,
 } from './muscleTaxonomy'
 import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { primitiveColors } from '../../../theme/tokens/primitives'
 import { liftStyle } from '../../../theme/lift'
+import { alpha } from '../../../utils/colors'
 
 const t = getSemanticColors('dark')
 
@@ -191,7 +193,7 @@ export function BodyMapDetailPanel({
           left: 0,
           right: 0,
           bottom: 0,
-          backgroundColor: '#000000',
+          backgroundColor: primitiveColors.black,
           opacity: backdrop,
         }}
         testID="body-map-detail-panel-backdrop-anim"
@@ -488,9 +490,9 @@ export function BodyMapDetailPanel({
                 paddingVertical: 10,
                 borderRadius: 8,
                 alignItems: 'center',
-                backgroundColor: 'rgba(255,121,0,0.12)',
+                backgroundColor: alpha(BRAND_PRIMARY, 0.12),
                 borderWidth: 1,
-                borderColor: 'rgba(255,121,0,0.3)',
+                borderColor: alpha(BRAND_PRIMARY, 0.3),
               }}
               testID="body-map-detail-panel-view-exercises"
             >

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

@@ -3,6 +3,7 @@ import { useState } from 'react'
 import { View, Text } from 'react-native'
 import { CapacityBandChart } from './CapacityBandChart'
 import type { CapacityBandDataPoint, CapacityBandProjection, WorkoutDot } from './CapacityBandChart'
+import { greyRamp } from '../../../theme/tokens/primitives'
 
 const band: CapacityBandDataPoint[] = [
   { date: '2026-06-01', bandLow: 40, bandHigh: 70 },
@@ -113,7 +114,7 @@ function InteractiveCapacityBandChart() {
         height={200}
         onWorkoutPress={setSelected}
       />
-      <Text style={{ fontSize: 12, fontFamily: 'Inter, sans-serif', color: '#9CA3AF' }}>
+      <Text style={{ fontSize: 12, fontFamily: 'Inter, sans-serif', color: greyRamp[400] }}>
         {selected
           ? `Selected ${selected.date}: load ${selected.load} (${selected.status})`
           : 'Tap a workout dot to inspect the session.'}

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

@@ -2,6 +2,7 @@
 import { useEffect, useState, useMemo } from 'react'
 import { View, Text, Pressable, Animated, Easing, type ViewProps } from 'react-native'
 import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { alpha } from '../../../utils/colors'
 
 const t = getSemanticColors('dark')
 
@@ -10,10 +11,11 @@ const STATUS_WARNING = t['status-warning']
 const STATUS_INFO = t['status-info']
 /** Dot outline: near-white ring so load dots read on the band fill and any
  *  surface (matches the MesoStatusCard gauge-marker convention). */
+// VW-82: no token at this value (nearest text-primary #F9F6F3). Left raw, proposed.
 const DOT_BORDER = '#F3F4F6'
-const BAND_FILL = 'rgba(46,213,115,0.1)'
-const BAND_EDGE = 'rgba(46,213,115,0.45)'
-const PROJECTION_FILL = 'rgba(46,213,115,0.05)'
+const BAND_FILL = alpha(STATUS_SUCCESS, 0.1)
+const BAND_EDGE = alpha(STATUS_SUCCESS, 0.45)
+const PROJECTION_FILL = alpha(STATUS_SUCCESS, 0.05)
 
 const PADDING_LEFT = 28
 const PADDING_RIGHT = 10

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

@@ -3,6 +3,10 @@ import { render, screen } from '@testing-library/react'
 import { axe } from 'jest-axe'
 import { DeviationBar } from './DeviationBar'
 import { greyRamp } from '../../../theme/tokens/primitives'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { alpha } from '../../../utils/colors'
+
+const t = getSemanticColors('dark')
 
 describe('DeviationBar', () => {
   it('renders the bar and dot', () => {
@@ -75,8 +79,7 @@ describe('DeviationBar', () => {
     const bar = getByTestId('deviation-bar')
     const track = bar.firstElementChild as HTMLElement
     expect(track).toHaveStyle({
-      backgroundImage:
-        'linear-gradient(90deg, rgba(46,213,115,0.25) 0%, rgba(107,114,128,0.15) 50%, rgba(249,180,21,0.25) 100%)',
+      backgroundImage: `linear-gradient(90deg, ${alpha(t['status-success'], 0.25)} 0%, rgba(107,114,128,0.15) 50%, ${alpha(t['status-warning'], 0.25)} 100%)`,
     })
   })
 

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

@@ -3,6 +3,7 @@ import { View, type ViewProps, type ViewStyle } from 'react-native'
 import { getSemanticColors } from '../../../theme/tokens/semantic'
 import { greyRamp } from '../../../theme/tokens/primitives'
 import { liftStyle } from '../../../theme/lift'
+import { alpha } from '../../../utils/colors'
 
 const t = getSemanticColors('dark')
 
@@ -60,8 +61,10 @@ export function DeviationBar({ deviation, width, className, ...props }: Deviatio
             width: resolvedWidth,
             borderRadius: 3,
             // react-native-web renders backgroundImage at runtime; not in RN ViewStyle types
-            backgroundImage:
-              'linear-gradient(90deg, rgba(46,213,115,0.25) 0%, rgba(107,114,128,0.15) 50%, rgba(249,180,21,0.25) 100%)',
+            // rgba(107,114,128,0.15) at 50% has no exact token match (nearest:
+            // semanticPins.textSecondaryLight #65748B, ΔRGB ~12.7) — left as a
+            // raw literal (VW-78).
+            backgroundImage: `linear-gradient(90deg, ${alpha(t['status-success'], 0.25)} 0%, rgba(107,114,128,0.15) 50%, ${alpha(t['status-warning'], 0.25)} 100%)`,
           } as ViewStyle
         }
       />

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

@@ -27,13 +27,14 @@ const meta: Meta<typeof DualVelocityStrip> = {
           'silhouette. Reuses VelocityStrip’s slot vocabulary (rep / todo / variable / ' +
           'continue), its velocity-zone colors, hero geometry, and the live-rep pop. Color is ' +
           'ALWAYS the velocity zone; SIDE is encoded by position only, never hue. `variant="hero"` ' +
-          'is the wall scale (value labels + per-side running-best reference lines); `variant="rail"` ' +
-          'is the compact rail-expanded scale. Single-voltra sets keep using VelocityStrip.',
+          'is the wall scale (value labels + per-side running-best reference lines); ' +
+          '`variant="dual-expanded"` is the compact rail-expanded scale (`"rail"` is a deprecated ' +
+          'alias for the same renderer). Single-voltra sets keep using VelocityStrip.',
       },
     },
   },
   argTypes: {
-    variant: { control: 'inline-radio', options: ['hero', 'rail'] },
+    variant: { control: 'inline-radio', options: ['hero', 'dual-expanded'] },
     targetReps: { control: 'number' },
     liveRepIndex: { control: 'number' },
     height: { control: { type: 'number', min: 48, max: 320, step: 4 } },
@@ -81,9 +82,9 @@ export const Hero: Story = {
   ),
 }
 
-/** RAIL — the same diverging language at the compact rail-expanded scale (no labels/refs). */
-export const RailExpanded: Story = {
-  args: { variant: 'rail', targetReps: 8, height: 84 },
+/** DUAL-EXPANDED — the same diverging language at the compact rail-expanded scale (no labels/refs). */
+export const DualExpanded: Story = {
+  args: { variant: 'dual-expanded', targetReps: 8, height: 84 },
   render: (args) => (
     <Page>
       <Panel width={320}>

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

@@ -182,16 +182,16 @@ describe('DualVelocityStrip side labels', () => {
     expect(screen.queryByTestId('dual-velocity-side-label-L')).not.toBeInTheDocument()
   })
 
-  it('drops the gutter/slot labels AND the centre axis at rail scale (the lean dual-expanded)', () => {
+  it('drops the gutter/slot labels AND the centre axis at dual-expanded scale', () => {
     render(
       <DualVelocityStrip
         left={{ velocities: [0.9], label: 'Left Arm' }}
         right={{ velocities: [0.8], label: 'Right Arm' }}
-        variant="rail"
+        variant="dual-expanded"
       />
     )
-    // Rail = the lean dual-expanded: no gutter/vertical-axis + no slot labels (the two wings read as
-    // separate rows via the vertical gap), and no centre axis — only the bolder hero keeps those.
+    // dual-expanded = the lean renderer: no gutter/vertical-axis + no slot labels (the two wings
+    // read as separate rows via the vertical gap), and no centre axis — only the bolder hero keeps those.
     expect(screen.queryByTestId('dual-velocity-side-label-L')).not.toBeInTheDocument()
     expect(screen.queryByTestId('dual-velocity-side-label-R')).not.toBeInTheDocument()
     expect(screen.queryByTestId('dual-velocity-axis')).not.toBeInTheDocument()
@@ -225,12 +225,12 @@ describe('DualVelocityStrip reference lines', () => {
     expect(wingDown().getByTestId('velocity-hero-reference')).toBeInTheDocument()
   })
 
-  it('omits reference lines at rail scale', () => {
+  it('omits reference lines at dual-expanded scale', () => {
     render(
       <DualVelocityStrip
         left={{ velocities: [0.9, 0.85] }}
         right={{ velocities: [0.82, 0.74] }}
-        variant="rail"
+        variant="dual-expanded"
       />
     )
     expect(screen.queryByTestId('velocity-hero-reference')).not.toBeInTheDocument()
@@ -478,12 +478,12 @@ describe('DualVelocityStrip live mode', () => {
     ])
   })
 
-  it('arms both wings at rail scale too — its wings are composed strips as well', () => {
+  it('arms both wings at dual-expanded scale too — its wings are composed strips as well', () => {
     render(
       <DualVelocityStrip
         left={{ velocities: [0.9, 0.85, 0.8] }}
         right={{ velocities: [0.82, 0.78, 0.7] }}
-        variant="rail"
+        variant="dual-expanded"
         liveRepIndex={2}
       />
     )
@@ -591,16 +591,16 @@ describe('DualVelocityStrip compact variant (folded)', () => {
   })
 })
 
-describe('DualVelocityStrip rail variant', () => {
+describe('DualVelocityStrip dual-expanded variant', () => {
   it('renders compact bars but no value labels or reference lines', () => {
     render(
       <DualVelocityStrip
         left={{ velocities: [0.9, 0.85] }}
         right={{ velocities: [0.82, 0.74] }}
-        variant="rail"
+        variant="dual-expanded"
       />
     )
-    // The rail is now COMPOSED from two bare `expanded` strips, so each wing emits the shared
+    // dual-expanded is COMPOSED from two bare `expanded` strips, so each wing emits the shared
     // SetBarChart testIDs rather than the old bespoke `dual-velocity-bar-*` ones. Query per wing.
     const up = within(screen.getByTestId('dual-velocity-wing-up'))
     const down = within(screen.getByTestId('dual-velocity-wing-down'))
@@ -616,7 +616,7 @@ describe('DualVelocityStrip rail variant', () => {
       <DualVelocityStrip
         left={{ velocities: [0.9] }}
         right={{ velocities: [0.8] }}
-        variant="rail"
+        variant="dual-expanded"
         targetReps={2}
       />
     )
@@ -633,7 +633,7 @@ describe('DualVelocityStrip rail variant', () => {
       <DualVelocityStrip
         left={{ velocities: [0.9, 0.86, 0.82] }}
         right={{ velocities: [0.85, 0.8] }}
-        variant="rail"
+        variant="dual-expanded"
       />
     )
     const up = within(screen.getByTestId('dual-velocity-wing-up'))
@@ -650,7 +650,7 @@ describe('DualVelocityStrip rail variant', () => {
       <DualVelocityStrip
         left={{ set: { type: 'range', velocities: [0.9, 0.86], floor: 3, max: 4 } }}
         right={{ set: { type: 'range', velocities: [0.85, 0.8], floor: 3, max: 4 } }}
-        variant="rail"
+        variant="dual-expanded"
       />
     )
     const up = within(screen.getByTestId('dual-velocity-wing-up'))
@@ -658,6 +658,19 @@ describe('DualVelocityStrip rail variant', () => {
     expect(up.queryAllByTestId('velocity-slot-variable').length).toBeGreaterThan(0)
     expect(down.queryAllByTestId('velocity-slot-variable').length).toBeGreaterThan(0)
   })
+
+  it('accepts the deprecated `rail` alias, rendering identically to `dual-expanded`', () => {
+    const props = {
+      left: { velocities: [0.9, 0.86, 0.82] },
+      right: { velocities: [0.85, 0.8] },
+      targetReps: 4,
+    }
+    const viaAlias = render(<DualVelocityStrip {...props} variant="rail" />)
+    const aliasHtml = viaAlias.container.innerHTML
+    viaAlias.unmount()
+    const viaCanonical = render(<DualVelocityStrip {...props} variant="dual-expanded" />)
+    expect(viaCanonical.container.innerHTML).toBe(aliasHtml)
+  })
 })
 
 describe('DualVelocityStrip accessibility', () => {
@@ -673,12 +686,12 @@ describe('DualVelocityStrip accessibility', () => {
     expect(await axe(container)).toHaveNoViolations()
   })
 
-  it('has no violations at rail scale', async () => {
+  it('has no violations at dual-expanded scale', async () => {
     const { container } = render(
       <DualVelocityStrip
         left={{ velocities: [0.9] }}
         right={{ velocities: [0.8] }}
-        variant="rail"
+        variant="dual-expanded"
       />
     )
     expect(await axe(container)).toHaveNoViolations()

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

@@ -11,14 +11,14 @@ const meta: Meta<typeof ExerciseCard> = {
     docs: {
       description: {
         component:
-          '**Organism** (data-contract card). Three representations: `upcoming` (a dimmed, ' +
-          'not-yet-reached row), collapsed (name + summary + per-set velocity strips), and expanded ' +
-          '— the unified card whose persistent header is the real ' +
-          '[ExerciseCardHeading](?path=/docs/custom-workout-exercisecardheading--docs) over a SET · REPS · ' +
-          'LBS · RPE body of [SetRow](?path=/docs/custom-workout-setrow--docs)s (compact spotlight on the ' +
-          'live set). Expand is controlled (`expanded` + `onExpandedChange`) or uncontrolled ' +
-          '(`defaultExpanded`); `upcoming` overrides expand.' +
-          ' Composes **VelocityStrip** · **PlaceholderStrip** · **PrBadge** · **SetRow** · **SetTableHeader** · **ExerciseCardHeading**.',
+          '**Organism** (data-contract card). Three representations, all ONE ' +
+          '[ExerciseCardHeading](?path=/docs/custom-workout-exercisecardheading--docs) selected by its ' +
+          '`density`: `upcoming` (a dimmed, not-yet-reached row), collapsed (name + prescription + the ' +
+          'per-set strip) and expanded — the `rail` heading over a SET · REPS · LBS · RPE body of ' +
+          '[SetRow](?path=/docs/custom-workout-setrow--docs)s (compact spotlight on the live set). ' +
+          'Expand is controlled (`expanded` + `onExpandedChange`) or uncontrolled (`defaultExpanded`); ' +
+          '`upcoming` overrides expand.' +
+          ' Composes **ExerciseCardHeading** · **SetRow** · **SetTableHeader**.',
       },
     },
   },