@titan-design/react-ui 0.12.1 → 0.13.0

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

@@ -12,8 +12,21 @@ import {
   useSurfaceMode,
 } from './SurfaceContext'
 import { getSemanticColors } from '../../../theme/tokens/semantic'
+import { greyRamp, primitiveColors } from '../../../theme/tokens/primitives'
 import { getPressedRecessShadow } from '../../../theme/elevation'
 
+// Planes by RAMP STEP, never by literal bytes: a re-space of the grey ramp
+// should move these expectations with it, not break them. Which step backs
+// which plane is still asserted — that mapping is the behaviour.
+const FRAME = greyRamp[975]
+const BACKGROUND = greyRamp[950]
+const BASE = greyRamp[925]
+const ELEVATED = greyRamp[900]
+const RAISED = greyRamp[875]
+const OVERLAY = greyRamp[850]
+const LIGHT_BASE = primitiveColors.white
+const LIGHT_TEXT_PRIMARY = getSemanticColors('light')['text-primary']
+
 // 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' }) {
@@ -72,11 +85,56 @@ describe('Surface (card model)', () => {
     expect(screen.getByTestId('my-surface')).toBeInTheDocument()
   })
 
-  it('paints the default flat dark card surface', () => {
+  it('sits flat on the inherited plane by default (dark base, no treatment)', () => {
     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' })
+    const el = screen.getByTestId('s')
+    expect(el).toHaveStyle({ backgroundColor: BASE })
+    expect(el.style.boxShadow).toBe('')
+  })
+
+  it('lifts onto ramp planes with rim + shadow: elevation 2 from the page is the card plane', () => {
+    render(<Surface elevation={2} testID="s" />)
+    const el = screen.getByTestId('s')
+    expect(el).toHaveStyle({ backgroundColor: RAISED })
+    expect(el.style.boxShadow).toContain('inset 0 1px 0')
+    expect(el.style.boxShadow).toMatch(/, 0 \d+px \d+px rgba\(0,0,0/)
+  })
+
+  it('raise is relative: one step up from an elevated host lands on raised', () => {
+    render(
+      <Surface level="elevated">
+        <Surface raise={1} testID="s" />
+      </Surface>
+    )
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: RAISED })
+  })
+
+  it('clamps at overlay so raised-on-raised cannot leave the ramp', () => {
+    render(
+      <Surface level="overlay">
+        <Surface raise={2} testID="s" />
+      </Surface>
+    )
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: OVERLAY })
+  })
+
+  it('floats on the overlay plane with a larger shadow and no ring', () => {
+    render(<Surface elevation={4} testID="s" />)
+    const el = screen.getByTestId('s')
+    expect(el).toHaveStyle({ backgroundColor: OVERLAY })
+    expect(el.style.boxShadow.split(', ').length).toBe(4)
+    expect(el.style.borderWidth).toBe('')
+  })
+
+  it('lets a caller switch the lift off on a raised plane, or on for a named one', () => {
+    render(
+      <>
+        <Surface raise={1} lift={false} testID="flat" />
+        <Surface level="raised" lift testID="lifted" />
+      </>
+    )
+    expect(screen.getByTestId('flat').style.boxShadow).toBe('')
+    expect(screen.getByTestId('lifted').style.boxShadow).toContain('inset 0 1px 0')
   })
 
   describe('accessibility', () => {
@@ -94,10 +152,10 @@ describe('Surface (card model)', () => {
 
 describe('Surface (named plane)', () => {
   it.each([
-    ['background', '#1C1916'],
-    ['base', '#252321'],
-    ['elevated', '#2C2A28'],
-    ['raised', '#31302F'],
+    ['background', BACKGROUND],
+    ['base', BASE],
+    ['elevated', ELEVATED],
+    ['raised', RAISED],
   ] 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 })
@@ -105,7 +163,7 @@ describe('Surface (named plane)', () => {
 
   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' })
+    expect(screen.getByTestId('s')).toHaveStyle({ backgroundColor: LIGHT_BASE })
   })
 
   it('lets a caller style override the owned background', () => {
@@ -134,12 +192,12 @@ function lstar(hex: string): number {
 
 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
+    // TD-surface-tokens S-3 re-space widened the top steps; base and
+    // background were unchanged. The pairs below are ramp-adjacent by index.
+    ['overlay', OVERLAY, RAISED], // → raised
+    ['raised', RAISED, ELEVATED], // → elevated
+    ['elevated', ELEVATED, BASE], // → base
+    ['base', BASE, BACKGROUND], // → background
   ] as const)(
     'in a %s parent renders one ramp step down (%s → %s), darker than its parent',
     (parent, parentHex, pressedHex) => {
@@ -155,7 +213,7 @@ describe('Surface (pressed well)', () => {
 
   it('with no enclosing Surface (default base) presses to the background plane', () => {
     render(<Surface pressed testID="well" />)
-    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#1C1916' })
+    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: BACKGROUND })
   })
 
   it('clamps at the frame floor: pressed directly in background does not underflow', () => {
@@ -164,8 +222,8 @@ describe('Surface (pressed well)', () => {
         <Surface pressed testID="well" />
       </Surface>
     )
-    // background (#1C1916) steps down to the frame floor (#100D0A), the bezel.
-    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#100D0A' })
+    // background steps down to the frame floor, the bezel.
+    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: FRAME })
   })
 
   it('does not step below the floor: pressed within a floor-pressed well stays at frame', () => {
@@ -176,7 +234,7 @@ describe('Surface (pressed well)', () => {
         </Surface>
       </Surface>
     )
-    expect(screen.getByTestId('deeper')).toHaveStyle({ backgroundColor: '#100D0A' })
+    expect(screen.getByTestId('deeper')).toHaveStyle({ backgroundColor: FRAME })
   })
 
   it('publishes the stepped-down level to descendants so a nested press steps again', () => {
@@ -209,8 +267,8 @@ describe('Surface (pressed well)', () => {
         <Surface pressed testID="well" style={{ boxShadow: undefined }} />
       </Surface>
     )
-    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: '#1C1916' })
-    expect(lstar('#1C1916')).toBeLessThan(lstar('#252321'))
+    expect(screen.getByTestId('well')).toHaveStyle({ backgroundColor: BACKGROUND })
+    expect(lstar(BACKGROUND)).toBeLessThan(lstar(BASE))
   })
 
   it('rounds the well by default and honours an explicit rounded override', () => {
@@ -240,7 +298,7 @@ describe('pressedLevel helper', () => {
 
 describe('getPressedRecessShadow', () => {
   it('returns an inset recess tuned to the fill colour on the web path', () => {
-    const style = getPressedRecessShadow('#1C1916', 'dark') as { boxShadow?: string }
+    const style = getPressedRecessShadow(BACKGROUND, 'dark') as { boxShadow?: string }
     expect(style.boxShadow).toContain('inset')
   })
 })
@@ -262,7 +320,9 @@ describe('Surface on-surface colour context', () => {
 
   it('resolves dark on-surface colours even with no enclosing Surface', () => {
     render(<Probe role="primary" label="p" />)
-    expect(screen.getByTestId('p')).toHaveStyle({ color: getSemanticColors('dark')['text-primary'] })
+    expect(screen.getByTestId('p')).toHaveStyle({
+      color: getSemanticColors('dark')['text-primary'],
+    })
   })
 
   it('flows an overridden theme to descendant text', () => {
@@ -271,7 +331,7 @@ describe('Surface on-surface colour context', () => {
         <Probe role="primary" label="p" />
       </Surface>
     )
-    expect(screen.getByTestId('p')).toHaveStyle({ color: '#121828' })
+    expect(screen.getByTestId('p')).toHaveStyle({ color: LIGHT_TEXT_PRIMARY })
     expect(screen.getByTestId('p')).toHaveTextContent('light')
   })
 
@@ -283,15 +343,15 @@ describe('Surface on-surface colour context', () => {
         </Surface>
       </Surface>
     )
-    expect(screen.getByTestId('p')).toHaveStyle({ color: '#121828' })
+    expect(screen.getByTestId('p')).toHaveStyle({ color: LIGHT_TEXT_PRIMARY })
   })
 })
 
 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')
+    expect(surfaceBackground('elevated', 'dark')).toBe(ELEVATED)
+    expect(surfaceBackground('background', 'dark')).toBe(BACKGROUND)
+    expect(surfaceBackground('base', 'light')).toBe(LIGHT_BASE)
   })
 
   it('resolves the frame floor from its own semantic token', () => {

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

@@ -1,57 +1,14 @@
 import React, { useMemo } from 'react'
-import { View, type ViewProps, type ViewStyle } from 'react-native'
+import { View, type ViewProps } 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'
+import { type GlowIntensity, getGlowShadow } from '../../../theme/elevation'
+import { SurfaceContext, type SurfaceContextValue } from './SurfaceContext'
+import { useResolvedSurface, type SurfaceDepthProps } from './resolveSurface'
 
-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 grey 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
+export interface SurfaceProps extends ViewProps, SurfaceDepthProps {
   glowColor?: string
   glowIntensity?: GlowIntensity
-  /**
-   * 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. */
+  /** Round the corners. Defaults on for a lifted or pressed surface, off for an absolute plane. */
   rounded?: boolean
   className?: string
   children?: React.ReactNode
@@ -59,17 +16,23 @@ export interface SurfaceProps extends ViewProps {
 
 /**
  * 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 grey 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')`.
+ * context. Depth is relative to the enclosing Surface:
+ *  - `raise` / positive `elevation`: step up the ramp and wear the lift
+ *    treatment (rim-light + ambient shadow). Clamps at `overlay`.
+ *  - `pressed` / negative `elevation`: step down with an inner-shadow recess.
+ *  - `level` (absolute): a flat grey plane straight from a token, for shell
+ *    roots only (shell = background, page = base). No lift.
+ *  - nothing: sit flat on the inherited plane.
+ * Descendants read the surface via {@link useOnSurfaceColor} / {@link useSurfaceMode}
+ * rather than hard-coding `getSemanticColors('dark')`.
  */
 export function Surface({
-  elevation = 0,
+  elevation,
   level,
+  raise,
   pressed = false,
+  lift,
+  liftOptions,
   glowColor,
   glowIntensity,
   theme,
@@ -79,39 +42,21 @@ export function Surface({
   children,
   ...props
 }: SurfaceProps) {
-  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 grey 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 resolved = useResolvedSurface({
+    elevation,
+    level,
+    raise,
+    pressed,
+    lift,
+    liftOptions,
+    theme,
+  })
   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 applyRounded = rounded ?? (pressed || level == null)
 
   const value = useMemo<SurfaceContextValue>(
-    () => ({ mode, level: resolvedLevel }),
-    [mode, resolvedLevel]
+    () => ({ mode: resolved.mode, level: resolved.plane }),
+    [resolved.mode, resolved.plane]
   )
 
   return (
@@ -119,7 +64,12 @@ export function Surface({
       <View
         className={cn(applyRounded && 'rounded-2xl', className)}
         // backgroundColor first so a caller `style` can still override it.
-        style={[{ backgroundColor }, shadowStyle, glowStyle, style]}
+        style={[
+          { backgroundColor: resolved.backgroundColor },
+          resolved.depthStyle,
+          glowStyle,
+          style,
+        ]}
         {...props}
       >
         {children}

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

@@ -1,52 +1,31 @@
 // 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.
+// A <Surface> owns a background from the surface ramp 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), which is the bug class this primitive retires.
 import { createContext, useContext } from 'react'
 import { getSemanticColors, type ThemeMode } from '../../../theme/tokens/semantic'
+import type { SurfaceLevel } from '../../../theme/surface-planes'
 
-type ColorToken = keyof ReturnType<typeof getSemanticColors>
+// The plane vocabulary lives in the theme so `elevation.ts` can resolve levels
+// to planes without importing a component. Re-exported here for callers that
+// reached it through the Surface module.
+export {
+  SURFACE_LEVEL_TOKEN,
+  PLANE_ORDER,
+  surfaceBackground,
+  pressedLevel,
+  raisedLevel,
+  type SurfaceLevel,
+} from '../../../theme/surface-planes'
 
-/**
- * A Surface's depth on the dark surface ramp. Each addressable level maps to an
- * EXISTING semantic surface/background token (already grounded in the derived
- * surface ramp — TD-surface-tokens S-1 — and theme-aware) — Surface introduces
- * no new hexes. Darkest → lightest:
- *   inset (#13100D) < background (#1C1916) < base (#252321) < elevated (#2A2827) < raised (#2D2C2B) < overlay (#302F2E)
- *
- * `frame` is the bezel the ramp sits inside — the top bar / side nav chrome —
- * and the floor a `<Surface pressed>` clamps at (see {@link pressedLevel}).
- *
- * It replaced a separate `inset` level in TD-07.14. That level was RETIRED, not
- * renamed: at ΔE 1.10 from the frame it was an imperceptible duplicate, which is
- * exactly why pressed (surface − 1) kept collapsing into it.
- */
-export type SurfaceLevel = 'frame' | 'background' | 'base' | 'elevated' | 'raised' | 'overlay'
+type ColorToken = keyof ReturnType<typeof getSemanticColors>
 
 /** 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 grey ramp — this map never carries literal hexes. Every level
-// is present now: swapping `inset` (which had no token) for `frame` (which does)
-// is what made this a total map and removed `surfaceBackground`'s special case.
-export const SURFACE_LEVEL_TOKEN = {
-  frame: 'background-frame',
-  background: 'background-base',
-  base: 'surface-base',
-  elevated: 'surface-elevated',
-  raised: 'surface-raised',
-  overlay: 'surface-overlay',
-} as const satisfies Record<SurfaceLevel, ColorToken>
-
-// Darkest → lightest. A `<Surface pressed>` renders one index DOWN from its
-// parent's level and clamps at `frame` (index 0). Kept in lockstep with the grey
-// ramp and the surface.contract.test PLANE_ORDER.
-const PRESSED_RAMP = ['frame', 'background', 'base', 'elevated', 'raised', 'overlay'] as const
-
 const ON_SURFACE_TOKEN = {
   primary: 'text-primary',
   secondary: 'text-secondary',
@@ -56,7 +35,7 @@ const ON_SURFACE_TOKEN = {
 export interface SurfaceContextValue {
   /** Active theme mode. Defaults to dark (the wall). */
   mode: ThemeMode
-  /** Depth of the nearest enclosing Surface. */
+  /** Plane of the nearest enclosing Surface. */
   level: SurfaceLevel
 }
 
@@ -78,9 +57,9 @@ export function useSurfaceMode(): ThemeMode {
 
 /**
  * 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.
+ * `getSemanticColors` (literal hex), 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)
@@ -95,22 +74,3 @@ export function onSurfaceColors(mode: ThemeMode): Record<OnSurfaceRole, string>
 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]]
-}
-
-/**
- * The level a `<Surface pressed>` resolves to: its parent's level stepped one
- * index DOWN the ramp — the symmetric twin of a raised surface stepping up —
- * clamped at the `frame` floor so a pressed surface never underflows the bezel.
- *   overlay→raised, raised→elevated, elevated→base, base→background,
- *   background→frame, frame→frame (clamped).
- * Pressed exposes ONE level of depth only (no pressed-2).
- */
-export function pressedLevel(parent: SurfaceLevel): SurfaceLevel {
-  const index = PRESSED_RAMP.indexOf(parent)
-  const down = Math.max(0, index - 1)
-  return PRESSED_RAMP[down]
-}

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

@@ -1,4 +1,10 @@
 export { Surface, type SurfaceProps } from './Surface'
+export {
+  resolveSurfaceDepth,
+  useResolvedSurface,
+  type SurfaceDepthProps,
+  type ResolvedSurface,
+} from './resolveSurface'
 export {
   SurfaceContext,
   useSurface,
@@ -7,7 +13,9 @@ export {
   onSurfaceColors,
   surfaceBackground,
   pressedLevel,
+  raisedLevel,
   SURFACE_LEVEL_TOKEN,
+  PLANE_ORDER,
   type SurfaceLevel,
   type OnSurfaceRole,
   type SurfaceContextValue,

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

@@ -0,0 +1,98 @@
+// How a container decides which plane it sits on and what it wears there.
+//
+// One resolution path shared by <Surface> and <Card>, so the two can never
+// disagree about depth. Everything is RELATIVE to the enclosing Surface unless
+// an absolute `level` names a shell root.
+import { useMemo } from 'react'
+import type { ViewStyle } from 'react-native'
+import {
+  FLOATING_ELEVATION_MIN,
+  getPressedRecessShadow,
+  type ElevationLevel,
+} from '../../../theme/elevation'
+import { liftStyle, type LiftOptions, type LiftStep } from '../../../theme/lift'
+import {
+  pressedLevel,
+  raisedLevel,
+  surfaceBackground,
+  type SurfaceLevel,
+} from '../../../theme/surface-planes'
+import type { ThemeMode } from '../../../theme/tokens/semantic'
+import { useSurface, type SurfaceContextValue } from './SurfaceContext'
+
+export interface SurfaceDepthProps {
+  /** Absolute plane, for shell roots (shell = background, page = base). No lift. */
+  level?: SurfaceLevel
+  /** Planes to step UP from the enclosing Surface, with the lift treatment. */
+  raise?: 1 | 2 | 3
+  /**
+   * Numeric depth relative to the enclosing Surface: negative recesses, 0 sits
+   * flat on the same plane, 1–3 lift, 4–5 float on the overlay plane.
+   */
+  elevation?: ElevationLevel
+  /** One plane DOWN with an inner-shadow recess. */
+  pressed?: boolean
+  /** Force the lift treatment on or off regardless of the step taken. */
+  lift?: boolean
+  /** Tune the lift (rim alpha). Specimens and hero surfaces only. */
+  liftOptions?: LiftOptions
+  /** Override the inherited theme mode. */
+  theme?: ThemeMode
+}
+
+export interface ResolvedSurface {
+  mode: ThemeMode
+  plane: SurfaceLevel
+  backgroundColor: string
+  /** Recess or lift, to compose after `backgroundColor`. */
+  depthStyle: ViewStyle
+  /** Planes stepped up (0 when flat, pressed, or an absolute plane). */
+  step: number
+  lifted: boolean
+}
+
+function recessDepth(inherited: SurfaceContextValue, planesDown: number, mode: ThemeMode) {
+  let plane = inherited.level
+  for (let i = 0; i < planesDown; i++) plane = pressedLevel(plane)
+  const backgroundColor = surfaceBackground(plane, mode)
+  return { plane, backgroundColor, depthStyle: getPressedRecessShadow(backgroundColor, mode) }
+}
+
+/** Pure resolution: the plane, its hex, and the treatment. */
+export function resolveSurfaceDepth(
+  inherited: SurfaceContextValue,
+  props: SurfaceDepthProps
+): ResolvedSurface {
+  const mode = props.theme ?? inherited.mode
+  const elevation = props.elevation ?? 0
+  if (props.pressed || elevation < 0) {
+    const down = props.pressed ? 1 : -elevation
+    return { mode, step: 0, lifted: false, ...recessDepth(inherited, down, mode) }
+  }
+  const step = props.level != null ? 0 : (props.raise ?? elevation)
+  const floating = step >= FLOATING_ELEVATION_MIN
+  const plane = props.level ?? (floating ? 'overlay' : raisedLevel(inherited.level, step))
+  const lifted = props.lift ?? step > 0
+  const liftStep = Math.max(1, Math.min(5, step)) as LiftStep
+  const depthStyle = lifted ? liftStyle(liftStep, mode, props.liftOptions) : {}
+  return { mode, plane, backgroundColor: surfaceBackground(plane, mode), depthStyle, step, lifted }
+}
+
+/** The resolved depth of a container at this point in the tree. */
+export function useResolvedSurface(props: SurfaceDepthProps): ResolvedSurface {
+  const inherited = useSurface()
+  const { level, raise, elevation, pressed, lift, liftOptions, theme } = props
+  return useMemo(
+    () =>
+      resolveSurfaceDepth(inherited, {
+        level,
+        raise,
+        elevation,
+        pressed,
+        lift,
+        liftOptions,
+        theme,
+      }),
+    [inherited, level, raise, elevation, pressed, lift, liftOptions, theme]
+  )
+}

package/src/components/ui/surface/surface.contract.test.ts

@@ -8,7 +8,8 @@ import { getSemanticColors } from '../../../theme/tokens/semantic'
  * palette locks its eligibility mask with a value-level test.
  *
  * Scope: DARK mode only. The north-star diagnosis
- * (sources/design/surface-system-north-star.md) measured and
+ * (`sources/design/surface-system-north-star.md`, in the `voltras-workspace`
+ * active-work initiative rather than this repo) measured and
  * fixed the dark ramp specifically; light mode has its own latent collisions
  * (e.g. `surface-overlay` === `surface-base`, both `#FFFFFF`) that were never
  * part of this investigation — flagged as a follow-up, not silently patched
@@ -91,6 +92,10 @@ describe('surface ramp contract (dark) — token-value guardrails', () => {
     // Locked values from surface-system-north-star.md (re-spaced S-3) — see
     // surfaceRampDark in primitives.ts for the derivation this must match
     // byte-for-byte. background/base are unchanged by the re-space.
+    //
+    // The literal hexes are the POINT of this one test: it pins the bytes, so a
+    // re-space has to come here and say so. Every other test in the suite
+    // references the ramp instead.
     expect(dark['background-frame']).toBe('#100D0A')
     expect(dark['background-base']).toBe('#1C1916')
     expect(dark['surface-base']).toBe('#252321')

package/src/components/ui/switch/Switch.stories.tsx

@@ -5,7 +5,7 @@ import { Switch } from './Switch'
 const meta: Meta<typeof Switch> = {
   title: 'Components/Molecules/Switch',
   component: Switch,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'status:stable', '!status:review'],
   argTypes: {
     isChecked: {
       control: 'boolean',