@titan-design/react-ui 0.9.1 → 0.9.3

package/package.json

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

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

@@ -10,7 +10,8 @@ export interface ExerciseHeadingProps {
   /** Prescription line values (sets × reps @ load). */
   sets: number
   reps: number | string
-  load: number
+  /** Load value; a string (e.g. "—") passes through verbatim for an unset/discovery load. */
+  load: number | string
   unit?: 'lbs' | 'kg'
   /** Tempo tuple [eccentric, pauseBottom, concentric, pauseTop]; hidden when absent. */
   tempo?: [number, number, number, number]
@@ -26,10 +27,11 @@ function headingLabel(
   name: string,
   sets: number,
   reps: number | string,
-  load: number,
+  load: number | string,
   unit: string
 ) {
-  return `${name}, ${sets}×${reps} @ ${roundWeight(load)} ${unit}`
+  const loadLabel = typeof load === 'number' ? roundWeight(load) : load
+  return `${name}, ${sets}×${reps} @ ${loadLabel} ${unit}`
 }
 
 /**

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

@@ -1,7 +1,6 @@
 // Font mapping: font-heading=Space Grotesk, font-body=Nunito Sans (UI), font-sans=Inter (body)
 import { View, Text, type ViewProps } from 'react-native'
-import { primitiveColors } from '../../../theme/tokens/primitives'
-import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { Surface, onSurfaceColors, useSurfaceMode } from '../../ui/surface'
 import { Typography } from '../Typography'
 import { TimerReadout } from '../TimerReadout'
 import { SegmentedProgressBar } from './SegmentedProgressBar'
@@ -9,11 +8,10 @@ import { MetricTiles, type MetricTileData } from './MetricTiles'
 import { ScheduleTiles } from './ScheduleTiles'
 import { paceTone, paceToneColor } from './paceTone'
 
-const t = getSemanticColors('dark')
-
-// The raised charcoal heading plane (charcoal 400) — reads as one flat surface with
-// the nav; depth lives on the sunk list below it, not here.
-const RAISED = primitiveColors.charcoal[400] // #1F1F1F
+// 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
+// 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.
 
 // The chunked pace bar matches the SetStrip language but sits tighter than the default
 // SetStrip gap (5) — the locked design uses a 3px gap and a 9px track.
@@ -72,21 +70,22 @@ export function SessionHeader({
 }: SessionHeaderProps) {
   const upcoming = next != null
   const totalSets = plan.reduce((sum, e) => sum + e.sets, 0)
+  const onSurface = onSurfaceColors(useSurfaceMode())
 
   const hasPace = !upcoming && budgetMs != null && elapsedMs != null
   const target = hasPace ? (elapsedMs as number) / (budgetMs as number) : undefined
 
   const setsLabel = upcoming ? `${totalSets} sets` : `${Math.floor(setsDone)}/${totalSets} sets`
   const setsLabelColor = upcoming
-    ? t['text-secondary']
+    ? onSurface.secondary
     : paceToneColor(paceTone(totalSets > 0 ? setsDone / totalSets : 0, target))
 
   return (
-    <View
+    <Surface
+      level="background"
       className={className}
       style={[
         {
-          backgroundColor: RAISED,
           paddingTop: 11,
           paddingRight: 12,
           paddingBottom: 12,
@@ -105,7 +104,7 @@ export function SessionHeader({
           lineHeight: 18,
           fontWeight: '700',
           fontFamily: '"Space Grotesk", sans-serif',
-          color: t['text-primary'],
+          color: onSurface.primary,
           marginBottom: 10,
         }}
         testID="session-rail-title"
@@ -147,6 +146,6 @@ export function SessionHeader({
           />
         </View>
       </View>
-    </View>
+    </Surface>
   )
 }

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

@@ -2,17 +2,20 @@
 import { View, type ViewProps } from 'react-native'
 import { primitiveColors } from '../../../theme/tokens/primitives'
 import { neumorphicShadows } from '../../../theme/shadows'
+import { Surface } from '../../ui/surface'
 import { ExerciseCardHeading } from './ExerciseCardHeading'
 import { SessionHeader } from './SessionHeader'
 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 flat raised surface; the exercise list is sunk. Depth comes only from
-// the list's subtle inset shadow (top cast by the heading, faint left edge by the nav).
-const INSET = primitiveColors.charcoal[800] // #131313 — sunk exercise list
-const DIVIDER = primitiveColors.charcoal[500] // #1C1C1C — row divider
+// 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
+// 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 DEFAULT_WIDTH = 246
 
@@ -20,7 +23,15 @@ export interface SessionRailExercise {
   /** Stable key + press payload. Falls back to list index when absent. */
   id?: string
   name: string
-  summary: { sets: number; reps: number | string; weight: number; unit: 'lbs' | 'kg' }
+  /** `weight` accepts a string (e.g. "—") for an unset/discovery load — never a faked 0. */
+  summary: { sets: number; reps: number | string; weight: number | string; unit: 'lbs' | 'kg' }
+  /**
+   * Prescribed set count for the header total + pace-bar segment width. Distinct from
+   * `summary.sets`, which is the row's live DONE count (0 for the active exercise before
+   * its first set) — using that for the total under-counts by the active exercise's
+   * remaining sets. Falls back to `summary.sets` when absent.
+   */
+  plannedSets?: number
   tempo?: [number, number, number, number]
   indicator?: ExerciseIndicatorKind
   /** Per-set performance data driving the heading strip. */
@@ -76,15 +87,16 @@ export function SessionRail({
   ...props
 }: SessionRailProps) {
   return (
-    <View
+    <Surface
+      level="elevated"
       className={className}
-      style={[{ width, flexDirection: 'column', backgroundColor: INSET }, style]}
+      style={[{ width, flexDirection: 'column' }, style]}
       testID="session-rail"
       {...props}
     >
       <SessionHeader
         title={title}
-        plan={exercises.map((ex) => ({ name: ex.name, sets: ex.summary.sets }))}
+        plan={exercises.map((ex) => ({ name: ex.name, sets: ex.plannedSets ?? ex.summary.sets }))}
         setsDone={setsDone}
         elapsedMs={elapsedMs}
         budgetMs={budgetMs}
@@ -93,8 +105,9 @@ export function SessionRail({
         next={next}
       />
 
-      <View
-        style={[{ flex: 1, backgroundColor: INSET }, neumorphicShadows.charcoal.pressed.subtle]}
+      <Surface
+        level="elevated"
+        style={[{ flex: 1 }, neumorphicShadows.charcoal.pressed.subtle]}
         testID="session-rail-list"
       >
         {exercises.map((ex, i) => (
@@ -120,7 +133,7 @@ export function SessionRail({
             />
           </View>
         ))}
-      </View>
-    </View>
+      </Surface>
+    </Surface>
   )
 }

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

@@ -11,7 +11,8 @@ const AT = '@'
 export interface SetsRepsLoadProps extends ViewProps {
   sets: number
   reps: number | string
-  load: number
+  /** Load value; a string (e.g. "—") passes through verbatim for an unset/discovery load. */
+  load: number | string
   /** Displayed load unit label (e.g. "lb", "kg"). */
   unit?: string
   /** Cell font size (px). Default 11 — the compact rail/card scale. Raise for a wall read-out. */

package/src/components/shell/DashboardShell.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react'
 import { View, Text } from 'react-native'
 import { cn } from '../../utils/cn'
+import { Surface } from '../ui/surface'
 import { SideNav, type SideNavItem } from './SideNav'
 import { TopBar } from './TopBar'
 import { type Device } from './DeviceRow'
@@ -58,17 +59,17 @@ export function DashboardShell({
   className,
 }: DashboardShellProps) {
   return (
-    <View className={cn('flex-1 flex-row bg-surface-base', className)}>
-      <SideNav activeKey={activeKey} items={navItems} liveKey={liveKey} onNavigate={onNavigate} />
-      <View className="flex-1">
-        <TopBar
-          state={state}
-          devices={devices}
-          subtitle={subtitle}
-          onSelectDevice={onSelectDevice}
-        />
+    // Column: the TopBar spans the FULL width across the top, and the SideNav sits BELOW it
+    // in the content row (not a full-height left rail). This keeps the brand/status band
+    // unbroken edge-to-edge and lets the nav align under it. The shell is the outermost
+    // Surface — it owns the base plane and seeds the on-surface colour context (mode) for
+    // the whole dashboard tree.
+    <Surface level="base" className={cn('flex-1', className)}>
+      <TopBar state={state} devices={devices} subtitle={subtitle} onSelectDevice={onSelectDevice} />
+      <View className="flex-1 flex-row">
+        <SideNav activeKey={activeKey} items={navItems} liveKey={liveKey} onNavigate={onNavigate} />
         <View className="flex-1">{children ?? <ContentPlaceholder />}</View>
       </View>
-    </View>
+    </Surface>
   )
 }

package/src/components/shell/NavItem.tsx

@@ -65,7 +65,12 @@ export function NavItem({
         <Typography
           variant="button"
           color="inherit"
-          className={cn('text-[8.5px] font-bold uppercase tracking-[0.4px]', labelColor)}
+          // fontSize inline, not `text-[8.5px]`: the `button` variant's `text-sm` (14px) and the
+          // arbitrary `text-[8.5px]` are a same-property class conflict that the consumer's
+          // Tailwind build resolved the wrong way (labels rendered ~14px on the wall). Inline
+          // size wins unambiguously; className keeps weight/case/tracking.
+          style={{ fontSize: 8.5, lineHeight: 11 }}
+          className={cn('font-bold uppercase tracking-[0.4px]', labelColor)}
         >
           {label}
         </Typography>

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

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { View, Text } from 'react-native'
 import { Surface } from './Surface'
+import { useOnSurfaceColor, type SurfaceLevel } from './SurfaceContext'
 import type { ElevationLevel } from '../../../theme/elevation'
 
 const meta: Meta<typeof Surface> = {
@@ -12,10 +13,15 @@ const meta: Meta<typeof Surface> = {
       control: { type: 'range', min: -2, max: 5, step: 1 },
       description: 'Elevation level (-2 to 5)',
     },
+    level: {
+      control: 'select',
+      options: ['background', 'base', 'elevated', 'raised', 'overlay'],
+      description: 'Named charcoal plane (flat background from a semantic token)',
+    },
     theme: {
       control: 'select',
       options: ['light', 'dark'],
-      description: 'Color theme',
+      description: 'Color theme (also seeds the on-surface colour context)',
     },
     glowColor: {
       control: 'color',
@@ -78,6 +84,49 @@ export const WithGlow: Story = {
   ),
 }
 
+// The named-plane model: flat, full-bleed charcoal planes straight from the
+// semantic surface tokens — reaching the darker nav/page shades the numeric
+// lighten model can't. These back the shell / rail / stage.
+export const NamedPlanes: Story = {
+  render: () => (
+    <View style={{ gap: 12, padding: 24 }}>
+      {(['background', 'base', 'elevated', 'raised', 'overlay'] as SurfaceLevel[]).map((level) => (
+        <Surface key={level} level={level} style={{ padding: 16 }}>
+          <Text style={{ color: '#fff' }}>level=&quot;{level}&quot;</Text>
+        </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.
+function OnSurfaceLabels() {
+  return (
+    <View style={{ gap: 4 }}>
+      <Text style={{ color: useOnSurfaceColor('primary'), fontSize: 16, fontWeight: '700' }}>
+        Primary on this surface
+      </Text>
+      <Text style={{ color: useOnSurfaceColor('secondary') }}>Secondary on this surface</Text>
+      <Text style={{ color: useOnSurfaceColor('tertiary') }}>Tertiary on this surface</Text>
+    </View>
+  )
+}
+
+export const OnSurfaceText: Story = {
+  render: () => (
+    <View style={{ gap: 16, padding: 24 }}>
+      <Surface level="background" style={{ padding: 16 }}>
+        <OnSurfaceLabels />
+      </Surface>
+      <Surface theme="light" level="base" style={{ padding: 16 }}>
+        <OnSurfaceLabels />
+      </Surface>
+    </View>
+  ),
+}
+
 export const LightTheme: Story = {
   render: () => (
     <View style={{ gap: 16, padding: 24, backgroundColor: '#F3F4F6' }}>

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

@@ -1,9 +1,28 @@
 import { describe, it, expect } from 'vitest'
 import { render, screen } from '@testing-library/react'
+import { Text } from 'react-native'
 import { axe } from 'jest-axe'
 import { Surface } from './Surface'
+import {
+  onSurfaceColors,
+  surfaceBackground,
+  useOnSurfaceColor,
+  useSurfaceMode,
+} from './SurfaceContext'
 
-describe('Surface', () => {
+// A descendant probe that renders the on-surface colour + mode it resolves from
+// context, so tests can assert what a nested consumer would actually paint.
+function Probe({ role = 'primary' as const, label = 'probe' }) {
+  const color = useOnSurfaceColor(role)
+  const mode = useSurfaceMode()
+  return (
+    <Text testID={label} style={{ color }}>
+      {mode}
+    </Text>
+  )
+}
+
+describe('Surface (card model)', () => {
   it('renders children', () => {
     render(
       <Surface>
@@ -49,6 +68,12 @@ describe('Surface', () => {
     expect(screen.getByTestId('my-surface')).toBeInTheDocument()
   })
 
+  it('paints the default flat dark card surface', () => {
+    render(<Surface testID="s" />)
+    // elevation 0 → base surface (surface-elevated, charcoal 600) with no lightening.
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: '#191919' })
+  })
+
   describe('accessibility', () => {
     it('has no accessibility violations', async () => {
       const { container } = render(
@@ -61,3 +86,82 @@ describe('Surface', () => {
     })
   })
 })
+
+describe('Surface (named plane)', () => {
+  it.each([
+    ['background', '#101010'],
+    ['base', '#161616'],
+    ['elevated', '#191919'],
+    ['raised', '#1C1C1C'],
+  ] as const)('maps level %s to the charcoal token %s', (level, hex) => {
+    render(<Surface level={level} testID="s" />)
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: hex })
+  })
+
+  it('resolves the light-mode background when theme is overridden', () => {
+    render(<Surface level="base" theme="light" testID="s" />)
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: '#FFFFFF' })
+  })
+
+  it('lets a caller style override the owned background', () => {
+    render(<Surface level="base" testID="s" style={{ backgroundColor: '#000000' }} />)
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: '#000000' })
+  })
+})
+
+describe('Surface on-surface colour context', () => {
+  it('gives descendants literal-hex dark text colours', () => {
+    render(
+      <Surface level="background">
+        <Probe role="primary" label="p" />
+        <Probe role="secondary" label="s" />
+        <Probe role="tertiary" label="t" />
+      </Surface>
+    )
+    expect(screen.getByTestId('p')).toHaveStyle({ color: '#F3F4F6' })
+    expect(screen.getByTestId('s')).toHaveStyle({ color: '#9CA3AF' })
+    expect(screen.getByTestId('t')).toHaveStyle({ color: '#6B7280' })
+  })
+
+  it('resolves dark on-surface colours even with no enclosing Surface', () => {
+    render(<Probe role="primary" label="p" />)
+    expect(screen.getByTestId('p')).toHaveStyle({ color: '#F3F4F6' })
+  })
+
+  it('flows an overridden theme to descendant text', () => {
+    render(
+      <Surface theme="light">
+        <Probe role="primary" label="p" />
+      </Surface>
+    )
+    expect(screen.getByTestId('p')).toHaveStyle({ color: '#121828' })
+    expect(screen.getByTestId('p')).toHaveTextContent('light')
+  })
+
+  it('inherits mode through a nested Surface that sets only a level', () => {
+    render(
+      <Surface theme="light" level="background">
+        <Surface level="raised">
+          <Probe role="primary" label="p" />
+        </Surface>
+      </Surface>
+    )
+    expect(screen.getByTestId('p')).toHaveStyle({ color: '#121828' })
+  })
+})
+
+describe('surface colour helpers', () => {
+  it('surfaceBackground returns literal hex per level + mode', () => {
+    expect(surfaceBackground('elevated', 'dark')).toBe('#191919')
+    expect(surfaceBackground('background', 'dark')).toBe('#101010')
+    expect(surfaceBackground('base', 'light')).toBe('#FFFFFF')
+  })
+
+  it('onSurfaceColors returns the neutral text ramp as literal hex', () => {
+    expect(onSurfaceColors('dark')).toEqual({
+      primary: '#F3F4F6',
+      secondary: '#9CA3AF',
+      tertiary: '#6B7280',
+    })
+  })
+})

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

@@ -1,6 +1,7 @@
-import React from 'react'
+import React, { useMemo } from 'react'
 import { View, type ViewProps } from 'react-native'
 import { cn } from '../../../utils/cn'
+import { type ThemeMode } from '../../../theme/tokens/semantic'
 import {
   type ElevationLevel,
   getElevationSurface,
@@ -9,43 +10,92 @@ import {
   type GlowIntensity,
   getGlowShadow,
 } from '../../../theme/elevation'
+import {
+  SurfaceContext,
+  surfaceBackground,
+  useSurface,
+  type SurfaceContextValue,
+  type SurfaceLevel,
+} from './SurfaceContext'
 
 export interface SurfaceProps extends ViewProps {
+  /**
+   * Numeric depth → a computed lighten + shadow (the raised-card model). The
+   * background is derived from the base surface by lightening. Ignored for the
+   * background when `level` is set. Default 0 (flat card).
+   */
   elevation?: ElevationLevel
+  /**
+   * Named charcoal plane (shell / rail / stage). Sets the background directly
+   * from a semantic surface token — reaching the darker nav/page planes the
+   * lighten model can't — and drops the default rounding + auto shadow so the
+   * plane reads full-bleed. Composable with `elevation`'s glow.
+   */
+  level?: SurfaceLevel
   glowColor?: string
   glowIntensity?: GlowIntensity
-  theme?: 'light' | 'dark'
+  /**
+   * Theme mode. Also seeds the on-surface colour CONTEXT so descendant text /
+   * icons resolve their colour from this surface instead of a `text-*` className
+   * that silently fails to black on raw RN. Inherits the nearest Surface /
+   * ThemeProvider when omitted (default dark — the wall).
+   */
+  theme?: ThemeMode
+  /** Round the corners. Defaults on for the card model, off for a `level` plane. */
+  rounded?: boolean
   className?: string
-  children: React.ReactNode
+  children?: React.ReactNode
 }
 
+/**
+ * A container that OWNS its background and establishes an on-surface colour
+ * context. Two grounded ways to pick the background:
+ *  - `elevation` (numeric): the raised-card model — lighten-from-base + shadow.
+ *  - `level` (named): a flat charcoal plane straight from a semantic token,
+ *    for the shell / rail / stage backgrounds.
+ * Either way, descendants read the surface via {@link useOnSurfaceColor} /
+ * {@link useSurfaceMode} rather than hard-coding `getSemanticColors('dark')`.
+ */
 export function Surface({
   elevation = 0,
+  level,
   glowColor,
   glowIntensity,
-  theme = 'dark',
+  theme,
+  rounded,
   className,
   style,
   children,
   ...props
 }: SurfaceProps) {
-  const baseColor = getBaseSurfaceColor(theme)
-  const surfaceColor = getElevationSurface(baseColor, elevation, theme)
-  const shadowStyle = getElevationShadow(baseColor, elevation, theme)
+  const inherited = useSurface()
+  const mode = theme ?? inherited.mode
+  const isPlane = level != null
+
+  const baseColor = getBaseSurfaceColor(mode)
+  const backgroundColor = isPlane
+    ? surfaceBackground(level, mode)
+    : getElevationSurface(baseColor, elevation, mode)
+  // Planes own a flat full-bleed background; the card model keeps its depth shadow.
+  const shadowStyle = isPlane ? {} : getElevationShadow(baseColor, elevation, mode)
   const glowStyle = glowColor ? getGlowShadow(glowColor, glowIntensity) : {}
+  const applyRounded = rounded ?? !isPlane
+
+  const value = useMemo<SurfaceContextValue>(
+    () => ({ mode, level: level ?? inherited.level }),
+    [mode, level, inherited.level]
+  )
 
   return (
-    <View
-      className={cn('rounded-2xl', className)}
-      style={[
-        { backgroundColor: surfaceColor },
-        shadowStyle,
-        glowStyle,
-        style,
-      ]}
-      {...props}
-    >
-      {children}
-    </View>
+    <SurfaceContext.Provider value={value}>
+      <View
+        className={cn(applyRounded && 'rounded-2xl', className)}
+        // backgroundColor first so a caller `style` can still override it.
+        style={[{ backgroundColor }, shadowStyle, glowStyle, style]}
+        {...props}
+      >
+        {children}
+      </View>
+    </SurfaceContext.Provider>
   )
 }

package/src/components/ui/surface/SurfaceContext.ts

@@ -0,0 +1,86 @@
+// On-surface colour context (TD-05.12).
+//
+// A <Surface> owns a background from a small elevation scale AND publishes the
+// current theme mode so descendant text/icons resolve their colour from "what
+// surface am I on" instead of a `text-*` className. Those classNames silently
+// fail to black when the tree renders as raw RN in the standalone wall SPA
+// (no global.css, no nativewind) — the bug class this primitive retires.
+import { createContext, useContext } from 'react'
+import { getSemanticColors, type ThemeMode } from '../../../theme/tokens/semantic'
+
+type ColorToken = keyof ReturnType<typeof getSemanticColors>
+
+/**
+ * A Surface's depth on the dark charcoal ramp. Each level maps to an EXISTING
+ * semantic surface/background token (already grounded in the charcoal ramp and
+ * theme-aware) — Surface introduces no new hexes. Darkest → lightest:
+ *   background (#101010) < base (#161616) < elevated (#191919) < raised (#1C1C1C)
+ */
+export type SurfaceLevel = 'background' | 'base' | 'elevated' | 'raised' | 'overlay'
+
+/** On-surface neutral text roles, resolved for the current surface + theme. */
+export type OnSurfaceRole = 'primary' | 'secondary' | 'tertiary'
+
+// Which semantic token backs each level. Values live in `semantic.ts` and stay
+// in sync with the charcoal ramp — this map never carries literal hexes.
+export const SURFACE_LEVEL_TOKEN = {
+  background: 'background-base',
+  base: 'surface-base',
+  elevated: 'surface-elevated',
+  raised: 'surface-raised',
+  overlay: 'surface-overlay',
+} as const satisfies Record<SurfaceLevel, ColorToken>
+
+const ON_SURFACE_TOKEN = {
+  primary: 'text-primary',
+  secondary: 'text-secondary',
+  tertiary: 'text-tertiary',
+} as const satisfies Record<OnSurfaceRole, ColorToken>
+
+export interface SurfaceContextValue {
+  /** Active theme mode. Defaults to dark (the wall). */
+  mode: ThemeMode
+  /** Depth of the nearest enclosing Surface. */
+  level: SurfaceLevel
+}
+
+// Default context: dark 'base' plane, so descendants OUTSIDE any Surface still
+// resolve to real dark colours (never black) on the dark-only wall.
+const DEFAULT_CONTEXT: SurfaceContextValue = { mode: 'dark', level: 'base' }
+
+export const SurfaceContext = createContext<SurfaceContextValue>(DEFAULT_CONTEXT)
+
+/** The nearest surface context ({ mode, level }); default dark 'base'. */
+export function useSurface(): SurfaceContextValue {
+  return useContext(SurfaceContext)
+}
+
+/** The active theme mode from the nearest Surface/provider (default dark). */
+export function useSurfaceMode(): ThemeMode {
+  return useContext(SurfaceContext).mode
+}
+
+/**
+ * Literal-hex on-surface neutral text colours for a theme mode. Uses
+ * `getSemanticColors` (literal hex — the TempoBar pattern), never `resolveColor`
+ * (which returns `var()` under the RNW vitest alias), so values stay real in
+ * tested component code and on raw-RN surfaces alike.
+ */
+export function onSurfaceColors(mode: ThemeMode): Record<OnSurfaceRole, string> {
+  const c = getSemanticColors(mode)
+  return {
+    primary: c[ON_SURFACE_TOKEN.primary],
+    secondary: c[ON_SURFACE_TOKEN.secondary],
+    tertiary: c[ON_SURFACE_TOKEN.tertiary],
+  }
+}
+
+/** Resolve one on-surface text colour for descendants of a Surface. */
+export function useOnSurfaceColor(role: OnSurfaceRole = 'primary'): string {
+  return getSemanticColors(useSurfaceMode())[ON_SURFACE_TOKEN[role]]
+}
+
+/** The background hex for a surface level under a theme mode (literal hex). */
+export function surfaceBackground(level: SurfaceLevel, mode: ThemeMode): string {
+  return getSemanticColors(mode)[SURFACE_LEVEL_TOKEN[level]]
+}