@titan-design/react-ui 0.9.2 → 0.10.0

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,19 @@ const meta: Meta<typeof Surface> = {
       control: { type: 'range', min: -2, max: 5, step: 1 },
       description: 'Elevation level (-2 to 5)',
     },
+    level: {
+      control: 'select',
+      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'],
-      description: 'Color theme',
+      description: 'Color theme (also seeds the on-surface colour context)',
     },
     glowColor: {
       control: 'color',
@@ -78,6 +88,105 @@ 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>
+  ),
+}
+
+// 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.
+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' }}>
@@ -89,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>
+  ),
+}

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

@@ -1,9 +1,31 @@
 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,
+  pressedLevel,
+  useOnSurfaceColor,
+  useSurface,
+  useSurfaceMode,
+} from './SurfaceContext'
+import { getPressedRecessShadow } from '../../../theme/elevation'
 
-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 +71,13 @@ 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) with no lightening.
+    // TD-surface-tokens S-3 re-space: was #2A2827.
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: '#2C2A28' })
+  })
+
   describe('accessibility', () => {
     it('has no accessibility violations', async () => {
       const { container } = render(
@@ -61,3 +90,217 @@ describe('Surface', () => {
     })
   })
 })
+
+describe('Surface (named plane)', () => {
+  it.each([
+    ['background', '#1C1916'],
+    ['base', '#252321'],
+    ['elevated', '#2C2A28'],
+    ['raised', '#31302F'],
+  ] as const)('maps level %s to the surface-ramp 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' })
+  })
+})
+
+// A descendant probe that reports the surface LEVEL it resolves from context,
+// so tests can assert what a nested Surface publishes to its children.
+function LevelProbe({ label = 'lvl' }) {
+  const { level } = useSurface()
+  return <Text testID={label}>{level}</Text>
+}
+
+// CIELAB L* (perceptual lightness) — same calc as surface.contract.test, so the
+// "darker" assertions measure the metric the ramp was designed against.
+function lstar(hex: string): number {
+  const h = hex.replace('#', '')
+  const lin = [0, 2, 4]
+    .map((i) => parseInt(h.slice(i, i + 2), 16) / 255)
+    .map((c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4))
+  const y = 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
+  return y <= 0.008856 ? y * 903.3 : 116 * Math.cbrt(y) - 16
+}
+
+describe('Surface (pressed well)', () => {
+  it.each([
+    // TD-surface-tokens S-3 re-space: top steps widened (elevated #2C2A28,
+    // raised #31302F, overlay #373635); base/background unchanged.
+    ['overlay', '#373635', '#31302F'], // → raised
+    ['raised', '#31302F', '#2C2A28'], // → elevated
+    ['elevated', '#2C2A28', '#252321'], // → base
+    ['base', '#252321', '#1C1916'], // → background
+  ] as const)(
+    'in a %s parent renders one ramp step down (%s → %s), darker than its parent',
+    (parent, parentHex, pressedHex) => {
+      render(
+        <Surface level={parent}>
+          <Surface pressed testID="well" />
+        </Surface>
+      )
+      expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: pressedHex })
+      expect(lstar(pressedHex)).toBeLessThan(lstar(parentHex))
+    }
+  )
+
+  it('with no enclosing Surface (default base) presses to the background plane', () => {
+    render(<Surface pressed testID="well" />)
+    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#1C1916' })
+  })
+
+  it('clamps at the inset floor: pressed directly in background does not underflow', () => {
+    render(
+      <Surface level="background">
+        <Surface pressed testID="well" />
+      </Surface>
+    )
+    // background (#1C1916) steps down to the inset floor (#13100D), the pit.
+    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#13100D' })
+  })
+
+  it('does not step below the floor: pressed within a floor-pressed well stays at inset', () => {
+    render(
+      <Surface level="background">
+        <Surface pressed>
+          <Surface pressed testID="deeper" />
+        </Surface>
+      </Surface>
+    )
+    expect(screen.getByTestId('deeper')).toHaveStyle({ backgroundColor: '#13100D' })
+  })
+
+  it('publishes the stepped-down level to descendants so a nested press steps again', () => {
+    render(
+      <Surface level="raised">
+        <Surface pressed>
+          <LevelProbe label="lvl" />
+        </Surface>
+      </Surface>
+    )
+    // raised → elevated; descendants read the well's own level.
+    expect(screen.getByTestId('lvl')).toHaveTextContent('elevated')
+  })
+
+  it('adds an inner-shadow recess composed with the darker fill (web path)', () => {
+    render(
+      <Surface level="base">
+        <Surface pressed testID="well" />
+      </Surface>
+    )
+    const boxShadow = screen.getByTestId('well').style.boxShadow
+    expect(boxShadow).toContain('inset')
+  })
+
+  it('reads recessed via the darker fill alone when the shadow path is absent (no-shadow/native)', () => {
+    // The recess is carried by BOTH fill + shadow; strip the shadow and the fill
+    // still darkens one ramp step, so a pressed surface never becomes invisible.
+    render(
+      <Surface level="base">
+        <Surface pressed testID="well" style={{ boxShadow: undefined }} />
+      </Surface>
+    )
+    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#1C1916' })
+    expect(lstar('#1C1916')).toBeLessThan(lstar('#252321'))
+  })
+
+  it('rounds the well by default and honours an explicit rounded override', () => {
+    render(
+      <Surface level="base">
+        <Surface pressed testID="rounded" />
+        <Surface pressed rounded={false} testID="flat" />
+      </Surface>
+    )
+    expect(screen.getByTestId('rounded')).toBeInTheDocument()
+    expect(screen.getByTestId('flat')).toBeInTheDocument()
+  })
+})
+
+describe('pressedLevel helper', () => {
+  it.each([
+    ['overlay', 'raised'],
+    ['raised', 'elevated'],
+    ['elevated', 'base'],
+    ['base', 'background'],
+    ['background', 'inset'],
+    ['inset', 'inset'],
+  ] as const)('steps %s down to %s (clamped at inset)', (parent, expected) => {
+    expect(pressedLevel(parent)).toBe(expected)
+  })
+})
+
+describe('getPressedRecessShadow', () => {
+  it('returns an inset recess tuned to the fill colour on the web path', () => {
+    const style = getPressedRecessShadow('#1C1916', 'dark') as { boxShadow?: string }
+    expect(style.boxShadow).toContain('inset')
+  })
+})
+
+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('#2C2A28')
+    expect(surfaceBackground('background', 'dark')).toBe('#1C1916')
+    expect(surfaceBackground('base', 'light')).toBe('#FFFFFF')
+  })
+
+  it('resolves the inset floor from the surfaceRampDark.inset primitive (no token yet)', () => {
+    expect(surfaceBackground('inset', 'dark')).toBe('#13100D')
+  })
+
+  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,51 +1,129 @@
-import React from 'react'
-import { View, type ViewProps } from 'react-native'
+import React, { useMemo } from 'react'
+import { View, type ViewProps, type ViewStyle } from 'react-native'
 import { cn } from '../../../utils/cn'
+import { type ThemeMode } from '../../../theme/tokens/semantic'
 import {
   type ElevationLevel,
   getElevationSurface,
   getElevationShadow,
+  getPressedRecessShadow,
   getBaseSurfaceColor,
   type GlowIntensity,
   getGlowShadow,
 } from '../../../theme/elevation'
+import {
+  SurfaceContext,
+  surfaceBackground,
+  pressedLevel,
+  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
+  /**
+   * Sunken "well": render ONE ramp step DOWN from the parent surface's level —
+   * the symmetric twin of a raised surface stepping up — and add an inner-shadow
+   * recess so the surface reads pressed (darker fill + inset shadow). Relative to
+   * the enclosing Surface's level (not this surface's own `level`), and clamped
+   * at the ramp's `inset` floor so it never underflows. One level of depth only.
+   */
+  pressed?: boolean
   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,
+  pressed = false,
   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
+
+  // Three grounded ways to own a background, in precedence order:
+  //  - pressed: a well ONE ramp step DOWN from the parent level (relative),
+  //    with an inner-shadow recess — clamps at the `inset` floor.
+  //  - level (named plane): a flat charcoal plane straight from a token.
+  //  - elevation (numeric): the raised-card model — lighten-from-base + shadow.
+  const baseColor = getBaseSurfaceColor(mode)
+  const resolvedLevel = pressed ? pressedLevel(inherited.level) : (level ?? inherited.level)
+
+  let backgroundColor: string
+  let shadowStyle: ViewStyle
+  if (pressed) {
+    backgroundColor = surfaceBackground(resolvedLevel, mode)
+    shadowStyle = getPressedRecessShadow(backgroundColor, mode)
+  } else if (isPlane) {
+    backgroundColor = surfaceBackground(level, mode)
+    // Planes own a flat full-bleed background — no depth shadow.
+    shadowStyle = {}
+  } else {
+    backgroundColor = getElevationSurface(baseColor, elevation, mode)
+    shadowStyle = getElevationShadow(baseColor, elevation, mode)
+  }
+
   const glowStyle = glowColor ? getGlowShadow(glowColor, glowIntensity) : {}
+  // A pressed well and the card model round by default; a flat plane doesn't.
+  const applyRounded = rounded ?? (pressed || !isPlane)
+
+  const value = useMemo<SurfaceContextValue>(
+    () => ({ mode, level: resolvedLevel }),
+    [mode, resolvedLevel]
+  )
 
   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>
   )
 }