@titan-design/react-ui 0.12.0 → 0.13.0

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

@@ -1,20 +1,20 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
-import { View, Text } from 'react-native'
 import { SupersetWrapper } from './SupersetWrapper'
 import { ExerciseCard } from './ExerciseCard'
-import { getSemanticColors } from '../../../theme/tokens/semantic'
-
-const t = getSemanticColors('dark')
+import { Card } from '../../ui/card'
+import { Typography } from '../Typography'
+import { Surface } from '../../ui/surface'
+import { resolveColor } from '../../../theme/resolve-color'
 
 const meta: Meta<typeof SupersetWrapper> = {
-  title: 'Workout/SupersetWrapper',
+  title: 'Custom/Workout/SupersetWrapper',
   component: SupersetWrapper,
   tags: ['autodocs'],
   decorators: [
     (Story) => (
-      <View style={{ maxWidth: 400, padding: 16, backgroundColor: t['background-base'] }}>
+      <Surface level="background" style={{ maxWidth: 400, padding: 16 }}>
         <Story />
-      </View>
+      </Surface>
     ),
   ],
 }
@@ -22,28 +22,21 @@ const meta: Meta<typeof SupersetWrapper> = {
 export default meta
 type Story = StoryObj<typeof SupersetWrapper>
 
+/** Stand-in for a real exercise row: a filled Card on the wrapper's own plane. */
+function DemoExercise({ name }: { name: string }) {
+  return (
+    <Card variant="filled" elevation={1} className="p-3">
+      <Typography variant="body2">{name}</Typography>
+    </Card>
+  )
+}
+
 export const Default: Story = {
   args: {
     children: (
       <>
-        <View
-          style={{
-            padding: 12,
-            backgroundColor: t['surface-raised'],
-            borderRadius: 8,
-          }}
-        >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise A</Text>
-        </View>
-        <View
-          style={{
-            padding: 12,
-            backgroundColor: t['surface-raised'],
-            borderRadius: 8,
-          }}
-        >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise B</Text>
-        </View>
+        <DemoExercise name="Exercise A" />
+        <DemoExercise name="Exercise B" />
       </>
     ),
   },
@@ -54,24 +47,8 @@ export const CustomLabel: Story = {
     label: 'A1/A2',
     children: (
       <>
-        <View
-          style={{
-            padding: 12,
-            backgroundColor: t['surface-raised'],
-            borderRadius: 8,
-          }}
-        >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise A1</Text>
-        </View>
-        <View
-          style={{
-            padding: 12,
-            backgroundColor: t['surface-raised'],
-            borderRadius: 8,
-          }}
-        >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise A2</Text>
-        </View>
+        <DemoExercise name="Exercise A1" />
+        <DemoExercise name="Exercise A2" />
       </>
     ),
   },
@@ -79,39 +56,25 @@ export const CustomLabel: Story = {
 
 export const CustomColor: Story = {
   args: {
-    color: '#22C55E',
+    color: resolveColor('status-success'),
     children: (
       <>
-        <View
-          style={{
-            padding: 12,
-            backgroundColor: t['surface-raised'],
-            borderRadius: 8,
-          }}
-        >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise A</Text>
-        </View>
-        <View
-          style={{
-            padding: 12,
-            backgroundColor: t['surface-raised'],
-            borderRadius: 8,
-          }}
-        >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise B</Text>
-        </View>
+        <DemoExercise name="Exercise A" />
+        <DemoExercise name="Exercise B" />
       </>
     ),
   },
 }
 
+const supersetColor = resolveColor('brand-primary')
+
 const exerciseA = {
   name: 'Bench Press',
   state: 'collapsed' as const,
   onToggle: () => {},
   summary: { sets: 3, reps: 8, weight: 185, unit: 'lbs' as const },
   supersetPosition: 'first' as const,
-  supersetColor: '#FF7900',
+  supersetColor,
 }
 
 const exerciseB = {
@@ -120,7 +83,7 @@ const exerciseB = {
   onToggle: () => {},
   summary: { sets: 3, reps: 8, weight: 155, unit: 'lbs' as const },
   supersetPosition: 'last' as const,
-  supersetColor: '#FF7900',
+  supersetColor,
 }
 
 export const WithExerciseCards: Story = {

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

@@ -3,6 +3,7 @@ import { render, screen } from '@testing-library/react'
 import { axe } from 'jest-axe'
 import { View, Text } from 'react-native'
 import { SupersetWrapper } from './SupersetWrapper'
+import { resolveColor } from '../../../theme/resolve-color'
 
 describe('SupersetWrapper', () => {
   describe('label', () => {
@@ -10,7 +11,7 @@ describe('SupersetWrapper', () => {
       render(
         <SupersetWrapper>
           <View />
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
       expect(screen.getByTestId('superset-label')).toHaveTextContent('SS')
     })
@@ -19,31 +20,32 @@ describe('SupersetWrapper', () => {
       render(
         <SupersetWrapper label="A1/A2">
           <View />
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
       expect(screen.getByTestId('superset-label')).toHaveTextContent('A1/A2')
     })
   })
 
   describe('color', () => {
-    it('applies default color #FF7900 to border and label background', () => {
+    it('defaults border and label background to the brand-primary token', () => {
       render(
         <SupersetWrapper>
           <View />
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
+      const brand = resolveColor('brand-primary')
       const wrapper = screen.getByTestId('superset-wrapper')
-      expect(wrapper).toHaveStyle({ borderLeftColor: '#FF7900' })
+      expect(wrapper).toHaveStyle({ borderLeftColor: brand })
 
       const label = screen.getByTestId('superset-label')
-      expect(label).toHaveStyle({ backgroundColor: '#FF7900' })
+      expect(label).toHaveStyle({ backgroundColor: brand })
     })
 
     it('applies custom color to border and label background', () => {
       render(
         <SupersetWrapper color="#22C55E">
           <View />
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
       const wrapper = screen.getByTestId('superset-wrapper')
       expect(wrapper).toHaveStyle({ borderLeftColor: '#22C55E' })
@@ -59,7 +61,7 @@ describe('SupersetWrapper', () => {
         <SupersetWrapper>
           <Text testID="child-1">Exercise A</Text>
           <Text testID="child-2">Exercise B</Text>
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
       expect(screen.getByTestId('child-1')).toHaveTextContent('Exercise A')
       expect(screen.getByTestId('child-2')).toHaveTextContent('Exercise B')
@@ -71,7 +73,7 @@ describe('SupersetWrapper', () => {
       render(
         <SupersetWrapper>
           <View />
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
       expect(screen.getByRole('group')).toBeInTheDocument()
     })
@@ -80,7 +82,7 @@ describe('SupersetWrapper', () => {
       render(
         <SupersetWrapper>
           <View />
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
       expect(screen.getByLabelText('Superset: SS')).toBeInTheDocument()
     })
@@ -89,7 +91,7 @@ describe('SupersetWrapper', () => {
       render(
         <SupersetWrapper label="A1/A2">
           <View />
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
       expect(screen.getByLabelText('Superset: A1/A2')).toBeInTheDocument()
     })
@@ -99,7 +101,7 @@ describe('SupersetWrapper', () => {
         <SupersetWrapper>
           <Text>Exercise A</Text>
           <Text>Exercise B</Text>
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
       const results = await axe(container)
       expect(results).toHaveNoViolations()
@@ -111,7 +113,7 @@ describe('SupersetWrapper', () => {
       render(
         <SupersetWrapper>
           <View />
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
       const label = screen.getByTestId('superset-label')
       expect(label).toHaveStyle({ position: 'absolute' })
@@ -121,7 +123,7 @@ describe('SupersetWrapper', () => {
       render(
         <SupersetWrapper>
           <View />
-        </SupersetWrapper>,
+        </SupersetWrapper>
       )
       const label = screen.getByTestId('superset-label')
       expect(label).toHaveStyle({ top: '-1px', left: '-3px' })

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

@@ -1,31 +1,27 @@
 // Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
 import React from 'react'
-import { View, Text } from 'react-native'
-import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { View } from 'react-native'
+import { Typography } from '../Typography'
+import { resolveColor } from '../../../theme/resolve-color'
 
 export interface SupersetWrapperProps {
   label?: string
+  /** Rail and label-chip colour. Defaults to the `brand-primary` token. */
   color?: string
   children: React.ReactNode
 }
 
-const DEFAULTS = {
-  label: 'SS',
-  color: getSemanticColors('dark')['brand-primary'],
-  bgBase: getSemanticColors('dark')['background-base'],
-} as const
+const DEFAULT_LABEL = 'SS'
+
+export function SupersetWrapper({ label = DEFAULT_LABEL, color, children }: SupersetWrapperProps) {
+  const rail = color ?? resolveColor('brand-primary')
 
-export function SupersetWrapper({
-  label = DEFAULTS.label,
-  color = DEFAULTS.color,
-  children,
-}: SupersetWrapperProps) {
   return (
     <View
       style={{
         position: 'relative',
         borderLeftWidth: 3,
-        borderLeftColor: color,
+        borderLeftColor: rail,
         paddingLeft: 8,
         marginHorizontal: 12,
         marginBottom: 8,
@@ -35,26 +31,26 @@ export function SupersetWrapper({
       accessibilityLabel={`Superset: ${label}`}
       testID="superset-wrapper"
     >
-      <Text
+      {/* `microLabel` is the 10px uppercase micro-label form and carries its own
+          face, weight and tracking. The chip was 9px/700 with a hand-set 0.5px
+          tracking; 9px is off the type scale (TOKENS.md §4), so it rounds up. */}
+      <Typography
+        variant="microLabel"
+        color="inverse"
         style={{
           position: 'absolute',
           top: -1,
           left: -3,
-          fontSize: 9,
-          fontFamily: 'Inter, sans-serif',
-          fontWeight: '700',
-          backgroundColor: color,
-          color: DEFAULTS.bgBase,
+          backgroundColor: rail,
           paddingVertical: 2,
           paddingHorizontal: 6,
           borderBottomRightRadius: 4,
-          letterSpacing: 0.5,
           zIndex: 2,
         }}
         testID="superset-label"
       >
         {label}
-      </Text>
+      </Typography>
       <View style={{ gap: 2 }} testID="superset-children">
         {children}
       </View>

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

@@ -6,7 +6,7 @@ import { TempoDisplay, type TempoLivePhase, type TempoLiveState } from './TempoD
 
 // tempo = [eccentric, pauseBottom, concentric, pauseTop]
 const meta: Meta<typeof TempoDisplay> = {
-  title: 'Workout/TempoDisplay',
+  title: 'Custom/Workout/TempoDisplay',
   component: TempoDisplay,
   tags: ['autodocs'],
   parameters: {
@@ -14,9 +14,9 @@ const meta: Meta<typeof TempoDisplay> = {
       description: {
         component:
           '**Molecule.** The eccentric/pause/concentric/pause tempo display. Composes ' +
-          '[MetricCell](?path=/docs/workout-metriccell--docs) ' +
+          '[MetricCell](?path=/docs/custom-workout-metriccell--docs) ' +
           '(shared value/separator cell). Used-by ↑ ' +
-          '[ExerciseHeading](?path=/docs/workout-exerciseheading--docs) (`showLabel={false}`).',
+          '[ExerciseHeading](?path=/docs/custom-workout-exerciseheading--docs) (`showLabel={false}`).',
       },
     },
   },
@@ -26,7 +26,10 @@ const meta: Meta<typeof TempoDisplay> = {
       description: 'Tempo values [eccentric, pauseBottom, concentric, pauseTop] in seconds',
     },
     size: { control: 'select', options: ['sm', 'md'], description: 'Size variant' },
-    fontSize: { control: { type: 'range', min: 9, max: 48, step: 1 }, description: 'Digit size (overrides `size`)' },
+    fontSize: {
+      control: { type: 'range', min: 9, max: 48, step: 1 },
+      description: 'Digit size (overrides `size`)',
+    },
     showLabel: { control: 'boolean', description: 'Show the TEMPO caption' },
     showInfo: { control: 'boolean', description: 'Show info tooltip on press' },
     live: {
@@ -273,21 +276,33 @@ export const ActiveTempoConditions: Story = {
           caption="Compact (14) · label off"
           tempo={TEMPO}
           fontSize={14}
-          live={{ activePhase: 'concentric', phaseElapsedMs: 900, completed: { eccentric: 3000, pauseBottom: 1000 } }}
+          live={{
+            activePhase: 'concentric',
+            phaseElapsedMs: 900,
+            completed: { eccentric: 3000, pauseBottom: 1000 },
+          }}
         />
         <Condition
           caption="Default (22) · label on"
           tempo={TEMPO}
           fontSize={22}
           showLabel
-          live={{ activePhase: 'concentric', phaseElapsedMs: 900, completed: { eccentric: 3000, pauseBottom: 1000 } }}
+          live={{
+            activePhase: 'concentric',
+            phaseElapsedMs: 900,
+            completed: { eccentric: 3000, pauseBottom: 1000 },
+          }}
         />
         <Condition
           caption="Wall (34) · label on"
           tempo={TEMPO}
           fontSize={34}
           showLabel
-          live={{ activePhase: 'concentric', phaseElapsedMs: 900, completed: { eccentric: 3000, pauseBottom: 1000 } }}
+          live={{
+            activePhase: 'concentric',
+            phaseElapsedMs: 900,
+            completed: { eccentric: 3000, pauseBottom: 1000 },
+          }}
         />
       </Section>
 

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

@@ -120,12 +120,18 @@ describe('TempoDisplay', () => {
     it('locks the phases completed earlier in the rep, and resets on the first phase', () => {
       // Concentric active (3rd phase) → eccentric + pauseBottom are locked done.
       const mid = render(
-        <TempoDisplay tempo={[3, 1, 2, 1]} live={{ activePhase: 'concentric', phaseElapsedMs: 800 }} />
+        <TempoDisplay
+          tempo={[3, 1, 2, 1]}
+          live={{ activePhase: 'concentric', phaseElapsedMs: 800 }}
+        />
       )
       expect(mid.getAllByTestId('tempo-live-done')).toHaveLength(2)
       // Back to the first phase (next rep) → nothing is locked yet.
       mid.rerender(
-        <TempoDisplay tempo={[3, 1, 2, 1]} live={{ activePhase: 'eccentric', phaseElapsedMs: 200 }} />
+        <TempoDisplay
+          tempo={[3, 1, 2, 1]}
+          live={{ activePhase: 'eccentric', phaseElapsedMs: 200 }}
+        />
       )
       expect(mid.queryByTestId('tempo-live-done')).not.toBeInTheDocument()
     })
@@ -133,13 +139,21 @@ describe('TempoDisplay', () => {
     it('colours the TEMPO label live-muted while live', () => {
       const { getByText, rerender } = render(<TempoDisplay tempo={[3, 1, 1, 0]} />)
       const restColor = getByText('TEMPO').style.color
-      rerender(<TempoDisplay tempo={[3, 1, 1, 0]} live={{ activePhase: 'eccentric', phaseElapsedMs: 500 }} />)
+      rerender(
+        <TempoDisplay
+          tempo={[3, 1, 1, 0]}
+          live={{ activePhase: 'eccentric', phaseElapsedMs: 500 }}
+        />
+      )
       expect(getByText('TEMPO').style.color).not.toBe(restColor)
     })
 
     it('shows upcoming phases as their prescribed time and the active as the live readout', () => {
       render(
-        <TempoDisplay tempo={[5, 3, 2, 1]} live={{ activePhase: 'eccentric', phaseElapsedMs: 1000 }} />
+        <TempoDisplay
+          tempo={[5, 3, 2, 1]}
+          live={{ activePhase: 'eccentric', phaseElapsedMs: 1000 }}
+        />
       )
       // active eccentric: 5s target, 1s in → 4.0 remaining
       expect(screen.getByText('4.0')).toBeInTheDocument()

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

@@ -183,7 +183,15 @@ const muscles: TrainingStatusMuscle[] = [
 const meta: Meta<typeof TrainingStatusPage> = {
   title: 'Pages/Training Status',
   component: TrainingStatusPage,
-  parameters: { layout: 'fullscreen' },
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Composes **BodyMap** · **BodyMapDetailPanel** · **MesoStatusCard** · **MuscleGroup**.',
+      },
+    },
+  },
   tags: ['autodocs'],
   args: { title: 'Training Status', meso, muscles },
 }

package/src/components/custom/Workout/VelocityStrip.compact.stories.tsx

@@ -23,8 +23,11 @@ import {
  * vertical space as a single — 2x is only forced for the value-height expanded.
  */
 const meta: Meta<typeof VelocityStrip> = {
-  title: 'Workout/DataViz/VelocityStrip/Compact',
+  title: 'Custom/Workout/DataViz/VelocityStrip/Compact',
   component: VelocityStrip,
+  parameters: {
+    docs: { description: { component: 'Composes **SetBarChart** · **ChartSideRail**.' } },
+  },
   tags: ['autodocs'],
 }
 export default meta

package/src/components/custom/Workout/VelocityStrip.dual.stories.tsx

@@ -17,9 +17,9 @@ import {
  * Dual is **not a fourth view**, so its scenario coverage lives in the
  * per-view groups, where every scenario renders single ABOVE dual on one
  * dataset:
- * [Compact](?path=/docs/workout-dataviz-velocitystrip-compact--docs) ·
- * [Expanded](?path=/docs/workout-dataviz-velocitystrip-expanded--docs) ·
- * [Hero](?path=/docs/workout-dataviz-velocitystrip-hero--docs).
+ * [Compact](?path=/docs/custom-workout-dataviz-velocitystrip-compact--docs) ·
+ * [Expanded](?path=/docs/custom-workout-dataviz-velocitystrip-expanded--docs) ·
+ * [Hero](?path=/docs/custom-workout-dataviz-velocitystrip-hero--docs).
  *
  * This group exists for the two things a pairing cannot carry: the exported
  * **API** (`DualVelocityStripProps`, in the args table below) and the layout
@@ -37,8 +37,11 @@ import {
  * not a hardcoded side. Single-slot sets keep using `VelocityStrip`.
  */
 const meta: Meta<typeof DualVelocityStrip> = {
-  title: 'Workout/DataViz/VelocityStrip/Dual',
+  title: 'Custom/Workout/DataViz/VelocityStrip/Dual',
   component: DualVelocityStrip,
+  parameters: {
+    docs: { description: { component: 'Composes **SetBarChart** · **ChartSideRail**.' } },
+  },
   tags: ['autodocs'],
   decorators: [wallDecorator],
   argTypes: {

package/src/components/custom/Workout/VelocityStrip.expanded.stories.tsx

@@ -32,8 +32,11 @@ import {
  * meaning.
  */
 const meta: Meta<typeof VelocityStrip> = {
-  title: 'Workout/DataViz/VelocityStrip/Expanded',
+  title: 'Custom/Workout/DataViz/VelocityStrip/Expanded',
   component: VelocityStrip,
+  parameters: {
+    docs: { description: { component: 'Composes **SetBarChart** · **ChartSideRail**.' } },
+  },
   tags: ['autodocs'],
 }
 export default meta

package/src/components/custom/Workout/VelocityStrip.hero.stories.tsx

@@ -31,8 +31,11 @@ import {
  * sets and do not reflow as each rep lands.
  */
 const meta: Meta<typeof VelocityStrip> = {
-  title: 'Workout/DataViz/VelocityStrip/Hero',
+  title: 'Custom/Workout/DataViz/VelocityStrip/Hero',
   component: VelocityStrip,
+  parameters: {
+    docs: { description: { component: 'Composes **SetBarChart** · **ChartSideRail**.' } },
+  },
   tags: ['autodocs'],
 }
 export default meta

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

@@ -16,14 +16,15 @@ import {
   REP_SET_LAGGING,
   type StripView,
 } from './velocity-story-kit'
+import { Surface } from '../../ui/surface'
 
 /**
  * Per-rep velocity strip.
  *
  * Three views, each with its own story group:
- * - **[Compact](?path=/docs/workout-dataviz-velocitystrip-compact--docs)** — the flat resting strip
- * - **[Expanded](?path=/docs/workout-dataviz-velocitystrip-expanded--docs)** — the value-height chart
- * - **[Hero](?path=/docs/workout-dataviz-velocitystrip-hero--docs)** — the across-the-room wall treatment
+ * - **[Compact](?path=/docs/custom-workout-dataviz-velocitystrip-compact--docs)** — the flat resting strip
+ * - **[Expanded](?path=/docs/custom-workout-dataviz-velocitystrip-expanded--docs)** — the value-height chart
+ * - **[Hero](?path=/docs/custom-workout-dataviz-velocitystrip-hero--docs)** — the across-the-room wall treatment
  *
  * Dual is NOT a fourth view. It is the same strip when the exercise used two
  * Voltras, so every group pairs single above dual on one dataset.
@@ -39,8 +40,13 @@ import {
  * live in the three group files above.
  */
 const meta: Meta<typeof VelocityStrip> = {
-  title: 'Workout/DataViz/VelocityStrip',
+  title: 'Custom/Workout/DataViz/VelocityStrip',
   component: VelocityStrip,
+  parameters: {
+    docs: {
+      description: { component: 'Composes **SetBarChart** · **ChartSideRail** · **SessionRail**.' },
+    },
+  },
   tags: ['autodocs'],
   argTypes: {
     variant: {
@@ -98,9 +104,9 @@ export const Playground: Story = {
   },
   decorators: [
     (Story) => (
-      <View style={{ width: 300, padding: 16, backgroundColor: SURFACE_BG }}>
+      <Surface level="base" style={{ width: 300, padding: 16 }}>
         <Story />
-      </View>
+      </Surface>
     ),
   ],
 }

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

@@ -1252,6 +1252,9 @@ export function VelocityStrip({
         label={label}
         showValueLabels
         formatValue={formatVelocity}
+        // Only the diverging dual's composed wings opt in (TD-07.10) — the standalone single
+        // hero is unchanged, per columnSlots being the dual-only signal (see the comment above).
+        flipEdgeLabel={columnSlots != null}
         renderReference={(g) => velocityReferenceOverlay(g, lossBandsOn)}
         hideBaseline
         testID="velocity-strip-hero"

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

@@ -1,12 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { View } from 'react-native'
 import { VolumeLandmarkBar } from './VolumeLandmarkBar'
-import { getSemanticColors } from '../../../theme/tokens/semantic'
-
-const t = getSemanticColors('dark')
+import { Surface } from '../../ui/surface'
 
 const meta: Meta<typeof VolumeLandmarkBar> = {
-  title: 'Workout/DataViz/VolumeLandmarkBar',
+  title: 'Custom/Workout/DataViz/VolumeLandmarkBar',
   component: VolumeLandmarkBar,
   tags: ['autodocs'],
   parameters: {
@@ -15,7 +13,8 @@ const meta: Meta<typeof VolumeLandmarkBar> = {
         component:
           'Horizontal weekly-volume bar with MEV / MAV / MRV landmark ticks, a HEAT-scale ' +
           'fill positioned against the MAV target, and a % readout. Reuses the canonical ' +
-          'BodyMap volume heat scale (under → maintenance → productive → approaching → over).',
+          'BodyMap volume heat scale (under → maintenance → productive → approaching → over).' +
+          ' Composes **ZoneTrack** · **DataRow**.',
       },
     },
   },
@@ -31,9 +30,9 @@ const meta: Meta<typeof VolumeLandmarkBar> = {
   },
   decorators: [
     (Story) => (
-      <View style={{ padding: 24, paddingBottom: 40, backgroundColor: t['background-base'] }}>
+      <Surface level="background" style={{ padding: 24, paddingBottom: 40 }}>
         <Story />
-      </View>
+      </Surface>
     ),
   ],
 }