@titan-design/react-ui 0.9.3 → 0.10.0

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

@@ -22,6 +22,9 @@ import { WeightBadge } from './WeightBadge'
 import { PrBadge } from './PrBadge'
 import { PlaceholderStrip } from './PlaceholderStrip'
 import { SupersetWrapper } from './SupersetWrapper'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+const t = getSemanticColors('dark')
 
 // ----------------------------------------------------------------------------- gallery scaffold
 class Boundary extends Component<{ children: ReactNode }, { err: string | null }> {
@@ -364,10 +367,10 @@ export const AllRows: Story = {
         </Cell>
         <Cell name="SupersetWrapper" entity="grouping bracket" expand="no">
           <SupersetWrapper label="SS1" color="#FF7900">
-            <View style={{ padding: 10, backgroundColor: '#1C1C1C', borderRadius: 8 }}>
+            <View style={{ padding: 10, backgroundColor: t['surface-raised'], borderRadius: 8 }}>
               <Text style={{ color: '#F3F4F6' }}>Exercise A</Text>
             </View>
-            <View style={{ padding: 10, backgroundColor: '#1C1C1C', borderRadius: 8 }}>
+            <View style={{ padding: 10, backgroundColor: t['surface-raised'], borderRadius: 8 }}>
               <Text style={{ color: '#F3F4F6' }}>Exercise B</Text>
             </View>
           </SupersetWrapper>

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

@@ -4,6 +4,9 @@
  */
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { NavStub, Rail, Page, T_TERTIARY } from './setHeadingKit'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+const t = getSemanticColors('dark')
 
 type Args = { stripHeight: number }
 const meta: Meta<Args> = {
@@ -25,7 +28,16 @@ export const NextToNav: Story = {
       <div style={{ display: 'flex', alignItems: 'stretch', width: 'fit-content' }}>
         <NavStub />
         <Rail stripH={args.stripHeight} />
-        <div style={{ width: 140, background: '#161616', alignSelf: 'stretch', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+        <div
+          style={{
+            width: 140,
+            background: t['background-base'],
+            alignSelf: 'stretch',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+          }}
+        >
           <span style={{ fontSize: 10, color: T_TERTIARY, fontFamily: 'monospace' }}>stage</span>
         </div>
       </div>

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

@@ -8,8 +8,8 @@ import { MetricTiles, type MetricTileData } from './MetricTiles'
 import { ScheduleTiles } from './ScheduleTiles'
 import { paceTone, paceToneColor } from './paceTone'
 
-// The header shares the SideNav's `background-base` (charcoal 900, #101010) so the nav and
-// the rail header read as ONE continuous dark plane on the left — the sunk exercise list
+// The header shares the SideNav's `background-base` (warm-tapered ramp shell, #1C1916) so the
+// nav and the rail header read as ONE continuous dark plane on the left — the sunk exercise list
 // sits raised off it. A `<Surface level="background">` owns that plane so the header no
 // longer hand-sets it, and its title/label text resolve on-surface colours from context.
 

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

@@ -1,8 +1,11 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { View, Text } from 'react-native'
 import { primitiveRamps } from '../../../theme/tokens/primitives'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
 import { SessionRail, type SessionRailExercise } from './SessionRail'
 
+const t = getSemanticColors('dark')
+
 /**
  * `SessionRail` (shell organism) — the live-workout exercise list: a flat raised
  * `SessionHeader` glance (title, stat tiles, chunked pace bar) over a sunk, inset list
@@ -20,7 +23,7 @@ const meta: Meta<typeof SessionRail> = {
   },
   decorators: [
     (Story) => (
-      <View className="min-h-screen flex-row" style={{ backgroundColor: '#101010' }}>
+      <View className="min-h-screen flex-row" style={{ backgroundColor: t['background-base'] }}>
         <Story />
         <View className="flex-1 items-center justify-center">
           <Text style={{ color: '#6B7280', fontSize: 12 }}>main viewport</Text>

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

@@ -9,13 +9,13 @@ import type { MetricTileData } from './MetricTiles'
 import type { SetStripSet } from './SetStrip'
 import type { ExerciseIndicatorKind } from './ExerciseIndicator'
 
-// Charcoal-ramp surfaces (the locked S3 shell shades): the nav + the heading plane read as
-// ONE dark plane (charcoal 900, #101010, owned by SessionHeader's `<Surface level="background">`).
-// The exercise list is a LIGHTER inset panel — `<Surface level="elevated">` (charcoal 600,
-// #191919) — recessed via its inner shadow yet paler than the header, so the transparent
+// Warm-tapered ramp surfaces (the locked S3 shell shades): the nav + the heading plane read as
+// ONE dark plane (background shell, #1C1916, owned by SessionHeader's `<Surface level="background">`).
+// The exercise list is a LIGHTER inset panel — `<Surface level="elevated">` (#2A2827) —
+// recessed via its inner shadow yet paler than the header, so the transparent
 // exercise headings on it never blend into the header plane. Surface owns both backgrounds,
 // so the rail no longer hand-sets them.
-const DIVIDER = primitiveColors.charcoal[300] // #2C2C2C — row divider (raised to read on #191919)
+const DIVIDER = primitiveColors.charcoal[300] // #2C2C2C — row divider (raised to read on surface-elevated #2A2827)
 
 const DEFAULT_WIDTH = 246
 

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

@@ -2,6 +2,9 @@ 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')
 
 const meta: Meta<typeof SupersetWrapper> = {
   title: 'Workout/SupersetWrapper',
@@ -9,7 +12,7 @@ const meta: Meta<typeof SupersetWrapper> = {
   tags: ['autodocs'],
   decorators: [
     (Story) => (
-      <View style={{ maxWidth: 400, padding: 16, backgroundColor: '#121212' }}>
+      <View style={{ maxWidth: 400, padding: 16, backgroundColor: t['background-base'] }}>
         <Story />
       </View>
     ),
@@ -26,24 +29,20 @@ export const Default: Story = {
         <View
           style={{
             padding: 12,
-            backgroundColor: '#1C1C1C',
+            backgroundColor: t['surface-raised'],
             borderRadius: 8,
           }}
         >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>
-            Exercise A
-          </Text>
+          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise A</Text>
         </View>
         <View
           style={{
             padding: 12,
-            backgroundColor: '#1C1C1C',
+            backgroundColor: t['surface-raised'],
             borderRadius: 8,
           }}
         >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>
-            Exercise B
-          </Text>
+          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise B</Text>
         </View>
       </>
     ),
@@ -58,24 +57,20 @@ export const CustomLabel: Story = {
         <View
           style={{
             padding: 12,
-            backgroundColor: '#1C1C1C',
+            backgroundColor: t['surface-raised'],
             borderRadius: 8,
           }}
         >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>
-            Exercise A1
-          </Text>
+          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise A1</Text>
         </View>
         <View
           style={{
             padding: 12,
-            backgroundColor: '#1C1C1C',
+            backgroundColor: t['surface-raised'],
             borderRadius: 8,
           }}
         >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>
-            Exercise A2
-          </Text>
+          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise A2</Text>
         </View>
       </>
     ),
@@ -90,24 +85,20 @@ export const CustomColor: Story = {
         <View
           style={{
             padding: 12,
-            backgroundColor: '#1C1C1C',
+            backgroundColor: t['surface-raised'],
             borderRadius: 8,
           }}
         >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>
-            Exercise A
-          </Text>
+          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise A</Text>
         </View>
         <View
           style={{
             padding: 12,
-            backgroundColor: '#1C1C1C',
+            backgroundColor: t['surface-raised'],
             borderRadius: 8,
           }}
         >
-          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>
-            Exercise B
-          </Text>
+          <Text style={{ color: '#F3F4F6', fontFamily: 'Inter, sans-serif' }}>Exercise B</Text>
         </View>
       </>
     ),

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

@@ -12,7 +12,7 @@ export interface SupersetWrapperProps {
 const DEFAULTS = {
   label: 'SS',
   color: getSemanticColors('dark')['brand-primary'],
-  bgBase: '#101010',
+  bgBase: getSemanticColors('dark')['background-base'],
 } as const
 
 export function SupersetWrapper({

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

@@ -84,11 +84,7 @@ function activeNumberTone(elapsedMs: number, targetMs: number | null): string {
 }
 
 /** The active number: `countup` elapsed (→ target) or `countdown` remaining (→ 0.0, then −). */
-function liveReadoutText(
-  elapsedMs: number,
-  targetMs: number,
-  readout: TempoLiveReadout,
-): string {
+function liveReadoutText(elapsedMs: number, targetMs: number, readout: TempoLiveReadout): string {
   const seconds = readout === 'countup' ? elapsedMs / 1000 : (targetMs - elapsedMs) / 1000
   return seconds.toFixed(1)
 }
@@ -308,7 +304,7 @@ export function TempoDisplay({
       style={{
         flexDirection: 'row',
         alignItems: 'center',
-        backgroundColor: '#1C1C1C',
+        backgroundColor: t['surface-raised'],
         paddingHorizontal: chromePadX,
         paddingVertical: chromePadY,
         borderRadius: chromeRadius,
@@ -378,7 +374,7 @@ export function TempoDisplay({
         >
           <View
             style={{
-              backgroundColor: '#191919',
+              backgroundColor: t['surface-overlay'],
               borderRadius: 6,
               paddingVertical: 8,
               paddingHorizontal: 12,

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

@@ -1,6 +1,9 @@
 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')
 
 const meta: Meta<typeof VolumeLandmarkBar> = {
   title: 'Workout/DataViz/VolumeLandmarkBar',
@@ -28,7 +31,7 @@ const meta: Meta<typeof VolumeLandmarkBar> = {
   },
   decorators: [
     (Story) => (
-      <View style={{ padding: 24, paddingBottom: 40, backgroundColor: '#101010' }}>
+      <View style={{ padding: 24, paddingBottom: 40, backgroundColor: t['background-base'] }}>
         <Story />
       </View>
     ),

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

@@ -26,7 +26,7 @@ const statusBgColors: Record<WorkoutPillStatus, string> = {
   completed: 'rgba(46,213,115,0.15)',
   current: 'rgba(255,121,0,0.15)',
   next: 'transparent',
-  upcoming: '#1C1C1C',
+  upcoming: t['surface-raised'],
   missed: 'rgba(209,67,67,0.1)',
   deload: 'rgba(186,41,150,0.15)',
 }
@@ -72,7 +72,7 @@ function usePulse(enabled: boolean) {
           easing: Easing.inOut(Easing.ease),
           useNativeDriver: true,
         }),
-      ]),
+      ])
     )
     animation.start()
 

package/src/components/ui/surface/Surface.stories.tsx

@@ -15,9 +15,13 @@ const meta: Meta<typeof Surface> = {
     },
     level: {
       control: 'select',
-      options: ['background', 'base', 'elevated', 'raised', 'overlay'],
+      options: ['inset', 'background', 'base', 'elevated', 'raised', 'overlay'],
       description: 'Named charcoal plane (flat background from a semantic token)',
     },
+    pressed: {
+      control: 'boolean',
+      description: 'Sunken well: one ramp step DOWN from the parent level + inner-shadow recess',
+    },
     theme: {
       control: 'select',
       options: ['light', 'dark'],
@@ -99,6 +103,62 @@ export const NamedPlanes: Story = {
   ),
 }
 
+// The pressed (sunken well) model: a `<Surface pressed>` renders ONE ramp step
+// DOWN from its parent's level — the symmetric twin of a raised surface stepping
+// up — plus an inner-shadow recess. It's RELATIVE: the same `pressed` well reads
+// as a consistent recess on every host plane (base → background, raised →
+// elevated, overlay → raised), not a single fixed black hole. It clamps at the
+// `inset` floor so a well in `background` bottoms out at the ramp's pit.
+function WellCard({ level }: { level: SurfaceLevel }) {
+  return (
+    <Surface level={level} style={{ padding: 16, gap: 12, flex: 1, borderRadius: 14 }}>
+      <Eyebrow>HOST · LEVEL = {level.toUpperCase()}</Eyebrow>
+      <Surface pressed style={{ padding: 16, gap: 4 }}>
+        <Eyebrow>PRESSED WELL</Eyebrow>
+        <OnSurfaceBody title="Sunken panel" sub="one step down + inner recess" />
+      </Surface>
+    </Surface>
+  )
+}
+
+export const PressedWells: Story = {
+  render: () => (
+    <Surface level="background" style={{ flexDirection: 'row', gap: 16, padding: 24 }}>
+      {(['base', 'raised', 'overlay'] as SurfaceLevel[]).map((level) => (
+        <WellCard key={level} level={level} />
+      ))}
+    </Surface>
+  ),
+}
+
+// Clamp + nesting — a well in `background` bottoms out at the inset floor
+// (#13100D), and pressing again inside it stays at the floor (no underflow),
+// while a well in a lighter plane still steps down normally.
+export const PressedClampAndNesting: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 16, padding: 24 }}>
+      <Surface level="background" style={{ padding: 16, gap: 12, flex: 1, borderRadius: 14 }}>
+        <Eyebrow>HOST · LEVEL = BACKGROUND</Eyebrow>
+        <Surface pressed style={{ padding: 16, gap: 10 }}>
+          <Eyebrow>PRESSED → INSET FLOOR</Eyebrow>
+          <Surface pressed style={{ padding: 12 }}>
+            <Eyebrow>PRESSED AGAIN → CLAMPED</Eyebrow>
+          </Surface>
+        </Surface>
+      </Surface>
+      <Surface level="raised" style={{ padding: 16, gap: 12, flex: 1, borderRadius: 14 }}>
+        <Eyebrow>HOST · LEVEL = RAISED</Eyebrow>
+        <Surface pressed style={{ padding: 16, gap: 10 }}>
+          <Eyebrow>PRESSED → ELEVATED</Eyebrow>
+          <Surface pressed style={{ padding: 12 }}>
+            <Eyebrow>PRESSED AGAIN → BASE</Eyebrow>
+          </Surface>
+        </Surface>
+      </Surface>
+    </View>
+  ),
+}
+
 // On-surface colour context: descendant text reads its colour from the Surface
 // via `useOnSurfaceColor` — no hard-coded hex, so it never renders black when the
 // tree mounts as raw RN in the standalone wall SPA.
@@ -138,3 +198,137 @@ export const LightTheme: Story = {
     </View>
   ),
 }
+
+// ===========================================================================
+// The Surface WORK — composition, context inheritance, and the real wall lockup.
+// The stories above exercise the primitive in isolation; these show it doing the
+// job it was built for (TD-05.12): stacking planes, propagating the on-surface
+// colour context, and backing the migrated shell / rail / stage.
+// ===========================================================================
+
+/** An all-caps eyebrow whose colour resolves on whatever Surface encloses it. */
+function Eyebrow({ children }: { children: string }) {
+  return (
+    <Text
+      style={{
+        color: useOnSurfaceColor('tertiary'),
+        fontSize: 10,
+        fontWeight: '700',
+        letterSpacing: 1,
+      }}
+    >
+      {children}
+    </Text>
+  )
+}
+
+/** Primary + secondary body text, both on-surface — no hard-coded hex. */
+function OnSurfaceBody({ title, sub }: { title: string; sub: string }) {
+  return (
+    <View style={{ gap: 2 }}>
+      <Text style={{ color: useOnSurfaceColor('primary'), fontSize: 14, fontWeight: '600' }}>
+        {title}
+      </Text>
+      <Text style={{ color: useOnSurfaceColor('secondary'), fontSize: 12 }}>{sub}</Text>
+    </View>
+  )
+}
+
+// Nesting + context inheritance — the core mechanic. Each Surface publishes its
+// level; the planes read darkest → lightest as they nest (background < base <
+// elevated < raised). The labels call `useOnSurfaceColor` and stay legible on
+// every plane WITHOUT a hard-coded hex — on-surface text resolves from the mode,
+// so one set of roles reads correctly across all the dark planes.
+export const NestedPlanes: Story = {
+  render: () => (
+    <Surface level="background" style={{ padding: 20, gap: 14 }}>
+      <Eyebrow>LEVEL = BACKGROUND</Eyebrow>
+      <Surface level="base" style={{ padding: 16, gap: 14, borderRadius: 14 }}>
+        <Eyebrow>LEVEL = BASE</Eyebrow>
+        <Surface level="elevated" style={{ padding: 16, gap: 14, borderRadius: 12 }}>
+          <Eyebrow>LEVEL = ELEVATED</Eyebrow>
+          <Surface level="raised" style={{ padding: 16, gap: 6, borderRadius: 10 }}>
+            <Eyebrow>LEVEL = RAISED</Eyebrow>
+            <OnSurfaceBody title="On-surface text" sub="resolves from the enclosing Surface" />
+          </Surface>
+        </Surface>
+      </Surface>
+    </Surface>
+  ),
+}
+
+// Theme inheritance — a Surface seeds the mode; the nested Surfaces and text with
+// NO explicit `theme` inherit it. The SAME subtree renders on both grounds and
+// stays legible, because on-surface colours resolve from the inherited mode
+// rather than a fixed hex. (A numeric `elevation` Surface inherits mode too.)
+function InheritingCard() {
+  return (
+    <Surface level="base" style={{ padding: 14, gap: 10, borderRadius: 12 }}>
+      <OnSurfaceBody title="Inherited mode" sub="no theme prop on this card" />
+      <Surface level="raised" style={{ padding: 12, borderRadius: 8 }}>
+        <Eyebrow>NESTED · STILL INHERITS</Eyebrow>
+      </Surface>
+    </Surface>
+  )
+}
+
+export const ThemeInheritance: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 16, padding: 24 }}>
+      <Surface theme="dark" level="background" style={{ padding: 16, gap: 10, flex: 1 }}>
+        <Eyebrow>THEME = DARK (SEEDS CONTEXT)</Eyebrow>
+        <InheritingCard />
+      </Surface>
+      <Surface theme="light" level="background" style={{ padding: 16, gap: 10, flex: 1 }}>
+        <Eyebrow>THEME = LIGHT (SEEDS CONTEXT)</Eyebrow>
+        <InheritingCard />
+      </Surface>
+    </View>
+  ),
+}
+
+// The wall lockup, as migrated (DashboardShell / SessionRail / stage). The shell
+// is a `background` plane; the page a `base` plane; the session rail an
+// `elevated` inset; the live stage a `raised` panel. Every eyebrow/label reads
+// on-surface — this composition is what replaced the inline `getSemanticColors`
+// text patches the standalone wall SPA used to carry.
+function RailRow({ name, sets }: { name: string; sets: string }) {
+  return (
+    <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
+      <Text style={{ color: useOnSurfaceColor('primary'), fontSize: 13 }}>{name}</Text>
+      <Text style={{ color: useOnSurfaceColor('tertiary'), fontSize: 13 }}>{sets}</Text>
+    </View>
+  )
+}
+
+export const WallLockup: Story = {
+  render: () => (
+    <Surface level="background" style={{ flexDirection: 'row', height: 320, padding: 12, gap: 12 }}>
+      {/* left nav — flush to the shell edge, on the same background plane */}
+      <View style={{ width: 56, alignItems: 'center', paddingTop: 10 }}>
+        <Eyebrow>NAV</Eyebrow>
+      </View>
+      {/* page — a base plane holding the rail + stage */}
+      <Surface
+        level="base"
+        style={{ flex: 1, flexDirection: 'row', padding: 12, gap: 12, borderRadius: 14 }}
+      >
+        {/* session rail — an elevated inset */}
+        <Surface level="elevated" style={{ width: 150, padding: 12, gap: 10, borderRadius: 12 }}>
+          <Eyebrow>SESSION</Eyebrow>
+          <RailRow name="Bench" sets="3/3" />
+          <RailRow name="Cable Row" sets="1/3" />
+          <RailRow name="Curl" sets="0/3" />
+        </Surface>
+        {/* live stage — a raised panel */}
+        <Surface
+          level="raised"
+          style={{ flex: 1, padding: 16, gap: 6, justifyContent: 'center', borderRadius: 12 }}
+        >
+          <Eyebrow>LIVE</Eyebrow>
+          <OnSurfaceBody title="Seated Cable Row" sub="set 2 · 8 reps · 0.42 m/s" />
+        </Surface>
+      </Surface>
+    </Surface>
+  ),
+}