@titan-design/react-ui 0.9.3 → 0.10.0

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

@@ -6,9 +6,12 @@ import { Surface } from './Surface'
 import {
   onSurfaceColors,
   surfaceBackground,
+  pressedLevel,
   useOnSurfaceColor,
+  useSurface,
   useSurfaceMode,
 } from './SurfaceContext'
+import { getPressedRecessShadow } from '../../../theme/elevation'
 
 // 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.
@@ -70,8 +73,9 @@ describe('Surface (card model)', () => {
 
   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' })
+    // 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', () => {
@@ -89,11 +93,11 @@ describe('Surface (card model)', () => {
 
 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) => {
+    ['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 })
   })
@@ -109,6 +113,137 @@ describe('Surface (named plane)', () => {
   })
 })
 
+// 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(
@@ -152,11 +287,15 @@ describe('Surface on-surface colour context', () => {
 
 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('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',

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

@@ -1,11 +1,12 @@
 import React, { useMemo } from 'react'
-import { View, type ViewProps } from 'react-native'
+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,
@@ -13,6 +14,7 @@ import {
 import {
   SurfaceContext,
   surfaceBackground,
+  pressedLevel,
   useSurface,
   type SurfaceContextValue,
   type SurfaceLevel,
@@ -32,6 +34,14 @@ export interface SurfaceProps extends ViewProps {
    * 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
   /**
@@ -59,6 +69,7 @@ export interface SurfaceProps extends ViewProps {
 export function Surface({
   elevation = 0,
   level,
+  pressed = false,
   glowColor,
   glowIntensity,
   theme,
@@ -72,18 +83,35 @@ export function Surface({
   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 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 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) : {}
-  const applyRounded = rounded ?? !isPlane
+  // 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: level ?? inherited.level }),
-    [mode, level, inherited.level]
+    () => ({ mode, level: resolvedLevel }),
+    [mode, resolvedLevel]
   )
 
   return (

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

@@ -7,29 +7,43 @@
 // (no global.css, no nativewind) — the bug class this primitive retires.
 import { createContext, useContext } from 'react'
 import { getSemanticColors, type ThemeMode } from '../../../theme/tokens/semantic'
+import { surfaceRampDark } from '../../../theme/tokens/primitives'
 
 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)
+ * 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)
+ *
+ * `inset` is the ramp's deepest pit — the sub-shell well. It's the floor a
+ * `<Surface pressed>` clamps at (see {@link pressedLevel}); it has no shipped
+ * semantic token yet, so {@link surfaceBackground} resolves it from the
+ * `surface-inset` token when present, else the `surfaceRampDark.inset` primitive.
  */
-export type SurfaceLevel = 'background' | 'base' | 'elevated' | 'raised' | 'overlay'
+export type SurfaceLevel = 'inset' | '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.
+// Which semantic token backs each ADDRESSABLE level. Values live in `semantic.ts`
+// and stay in sync with the charcoal ramp — this map never carries literal hexes.
+// `inset` is intentionally absent: it has no shipped semantic token yet, so it's
+// resolved separately (token-or-primitive) in `surfaceBackground`.
 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>
+} as const satisfies Record<Exclude<SurfaceLevel, 'inset'>, ColorToken>
+
+// Darkest → lightest, INCLUDING the inset floor. A `<Surface pressed>` renders
+// one index DOWN from its parent's level and clamps at `inset` (index 0). Kept
+// in lockstep with the derived ramp and the surface.contract.test PLANE_ORDER.
+const PRESSED_RAMP = ['inset', 'background', 'base', 'elevated', 'raised', 'overlay'] as const
 
 const ON_SURFACE_TOKEN = {
   primary: 'text-primary',
@@ -80,7 +94,33 @@ export function useOnSurfaceColor(role: OnSurfaceRole = 'primary'): string {
   return getSemanticColors(useSurfaceMode())[ON_SURFACE_TOKEN[role]]
 }
 
+/**
+ * The inset floor hex — the ramp's deepest pit that a pressed surface clamps at.
+ * Prefers the `surface-inset` semantic token (theme-aware; being promoted in a
+ * parallel token change) and falls back to the `surfaceRampDark.inset` primitive
+ * (#13100D, dark-ramp only) until that token ships.
+ */
+function insetFloor(mode: ThemeMode): string {
+  const colors = getSemanticColors(mode) as Record<string, string>
+  return colors['surface-inset'] ?? surfaceRampDark.inset
+}
+
 /** The background hex for a surface level under a theme mode (literal hex). */
 export function surfaceBackground(level: SurfaceLevel, mode: ThemeMode): string {
+  if (level === 'inset') return insetFloor(mode)
   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 `inset` floor so a pressed surface never underflows the pit.
+ *   overlay→raised, raised→elevated, elevated→base, base→background,
+ *   background→inset, inset→inset (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

@@ -6,6 +6,7 @@ export {
   useOnSurfaceColor,
   onSurfaceColors,
   surfaceBackground,
+  pressedLevel,
   SURFACE_LEVEL_TOKEN,
   type SurfaceLevel,
   type OnSurfaceRole,

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

@@ -0,0 +1,283 @@
+import { describe, it, expect } from 'vitest'
+import { getSemanticColors } from '../../../theme/tokens/semantic'
+
+/**
+ * Token-value contract for the dark surface ramp (TD-surface-tokens, S-1).
+ * Mirrors `config.completeness.test.ts`'s role — this fails CI on the raw
+ * token VALUES, independent of any component, the same way the categorical
+ * palette locks its eligibility mask with a value-level test.
+ *
+ * Scope: DARK mode only. The north-star diagnosis
+ * (coordination/design-explorations/surface-system-north-star.md) 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
+ * here (see the report / open item list).
+ *
+ * ── R1 note — why this does NOT assert a flat ΔL* >= 4 on every step ──
+ * An earlier draft of the north-star doc (§3) proposed 5 EVEN steps at
+ * ΔL*≈4. The LOCKED derivation that ships here (§ "Surface-ramp SYSTEM —
+ * derived, not hand-picked") deliberately supersedes that with DIMINISHING
+ * steps — the frame->content jump is biggest, each plane above adds less.
+ * As of S-3 (this re-space) the steps are 4.5 / 4.5 / 3.5 / 3 / 2.5
+ * (inset->background / background->base / base->elevated / elevated->raised /
+ * raised->overlay) — the top three widened from the original 2.5/2/1.5 taper
+ * so the content planes read as distinct without leaning on the hairline
+ * alone (R3 still carries the rest, per "lightness is a *secondary* cue").
+ * So R1 here asserts what the locked design actually guarantees: strict
+ * monotonicity, a >=4 L* foundational jump at the frame/shell boundary, and
+ * a >=2.5 L* floor on each of the three re-spaced upper steps — not a flat
+ * "always diminishing" rule (quantizing to whole hex bytes can make two
+ * adjacent re-spaced steps land within ~0.02 L* of each other; the floor is
+ * the guarantee that matters, not strict ordering between them).
+ */
+
+// --- CIELAB L* (perceptual lightness), matching the calculation in
+// surface-lab-shared.tsx's `lstar()` (the derivation source) verbatim, so
+// this test measures the SAME metric the ramp was designed against. ---
+function channels(hex: string): [number, number, number] {
+  const h = hex.replace('#', '')
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)) as [number, number, number]
+}
+
+function lstar(hex: string): number {
+  const lin = channels(hex)
+    .map((c) => c / 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
+}
+
+/** Flatten an rgba(...) alpha color over an opaque hex background -> opaque hex. */
+function compositeOver(baseHex: string, overlay: string): string {
+  const match = overlay.match(
+    /rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)/
+  )
+  if (!match) throw new Error(`not an rgba() color: ${overlay}`)
+  const [, r, g, b, a = '1'] = match
+  const alpha = parseFloat(a)
+  const base = channels(baseHex)
+  const tint = [parseFloat(r), parseFloat(g), parseFloat(b)]
+  const mixed = base.map((c, i) => c * (1 - alpha) + tint[i] * alpha)
+  return (
+    '#' +
+    mixed
+      .map((v) =>
+        Math.max(0, Math.min(255, Math.round(v)))
+          .toString(16)
+          .padStart(2, '0')
+      )
+      .join('')
+  )
+}
+
+const dark = getSemanticColors('dark')
+
+// The 6-plane derivation, in darkest -> lightest order. `inset` is now a real
+// shipped token (`surface-inset`, promoted at S-3 — see semantic.ts comment).
+const RAMP_HEX = {
+  inset: dark['surface-inset'],
+  background: dark['background-base'],
+  base: dark['surface-base'],
+  elevated: dark['surface-elevated'],
+  raised: dark['surface-raised'],
+  overlay: dark['surface-overlay'],
+} as const
+
+const PLANE_ORDER = ['inset', 'background', 'base', 'elevated', 'raised', 'overlay'] as const
+
+describe('surface ramp contract (dark) — token-value guardrails', () => {
+  it('ships the deriveSurfaceRamp() output verbatim for the addressable planes', () => {
+    // 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/inset are unchanged by the re-space.
+    expect(dark['surface-inset']).toBe('#13100D')
+    expect(dark['background-base']).toBe('#1C1916')
+    expect(dark['surface-base']).toBe('#252321')
+    expect(dark['surface-elevated']).toBe('#2C2A28')
+    expect(dark['surface-raised']).toBe('#31302F')
+    expect(dark['surface-overlay']).toBe('#373635')
+  })
+
+  describe('R1 — monotonic ramp with a real foundational jump', () => {
+    it('is strictly increasing in L* across all 6 planes', () => {
+      const Ls = PLANE_ORDER.map((name) => lstar(RAMP_HEX[name]))
+      for (let i = 1; i < Ls.length; i++) {
+        expect(
+          Ls[i],
+          `${PLANE_ORDER[i]} should be lighter than ${PLANE_ORDER[i - 1]}`
+        ).toBeGreaterThan(Ls[i - 1])
+      }
+    })
+
+    it('clears ΔL* >= 4 at the two foundational steps (inset->background, background->base)', () => {
+      const dL_insetToBackground = lstar(RAMP_HEX.background) - lstar(RAMP_HEX.inset)
+      const dL_backgroundToBase = lstar(RAMP_HEX.base) - lstar(RAMP_HEX.background)
+      expect(dL_insetToBackground).toBeGreaterThanOrEqual(4)
+      expect(dL_backgroundToBase).toBeGreaterThanOrEqual(4)
+    })
+
+    it('each re-spaced upper step (base->elevated->raised->overlay) clears ΔL* >= 2.5', () => {
+      // S-3 widened the top three steps to 3.5/3/2.5 specifically so they no
+      // longer need to lean on the "keep diminishing" clause the old 2.5/2/1.5
+      // taper required — each step now stands on its own >=2.5 L* floor.
+      // (Quantizing to whole hex bytes can make two of these land within
+      // ~0.02 L* of strict diminishing order; that's expected and not asserted.)
+      const upperSteps = ['base', 'elevated', 'raised', 'overlay'] as const
+      for (let i = 1; i < upperSteps.length; i++) {
+        const d = lstar(RAMP_HEX[upperSteps[i]]) - lstar(RAMP_HEX[upperSteps[i - 1]])
+        expect(d, `${upperSteps[i - 1]} -> ${upperSteps[i]}`).toBeGreaterThanOrEqual(2.5)
+      }
+    })
+  })
+
+  describe('R2 — no footgun collisions', () => {
+    it('surface-elevated and surface-overlay are distinct (previously both #191919)', () => {
+      expect(dark['surface-elevated']).not.toBe(dark['surface-overlay'])
+    })
+
+    it('the 5 addressable surface-family hexes are pairwise distinct', () => {
+      const family = [
+        'surface-base',
+        'surface-elevated',
+        'surface-raised',
+        'surface-overlay',
+      ] as const
+      const values = family.map((k) => dark[k])
+      expect(new Set(values).size).toBe(values.length)
+    })
+
+    it('no solid border token equals any surface/background fill hex', () => {
+      const surfaceHexes = new Set([
+        dark['background-base'],
+        dark['background-default'],
+        dark['background-subtle'],
+        dark['background-frame'],
+        dark['surface-base'],
+        dark['surface-elevated'],
+        dark['surface-raised'],
+        dark['surface-overlay'],
+        dark['surface-input'],
+        dark['surface-inset'],
+      ])
+      const solidBorders = [
+        'border-default',
+        'border-subtle',
+        'border-strong',
+        'border-prominent',
+      ] as const
+      for (const token of solidBorders) {
+        expect(
+          surfaceHexes.has(dark[token]),
+          `${token} (${dark[token]}) collides with a surface hex`
+        ).toBe(false)
+      }
+    })
+  })
+
+  describe('R3 — alpha hairline clears its ΔL* floor on every plane', () => {
+    // Doc floors (subtle>=6/default>=9/strong>=13) were calibrated on the OLD,
+    // much darker ramp (L* 4.7-10.3). The S-1 ramp compressed into a narrower,
+    // lighter band (L* 9-19.5); S-3's re-space widens it further still
+    // (L* 4.5-22.5) — the wider top steps push `overlay` even lighter, so the
+    // SAME alpha values composite to a slightly smaller (but still solid,
+    // still near-constant) ΔL* there. Floors below are re-measured against
+    // the S-3 ramp (default dropped 8->7 — the `overlay` plane now measures
+    // ~7.97, just under the old floor); a wall-display calibration pass (S-6)
+    // may retune the alpha values themselves.
+    const HAIRLINES = {
+      subtle: { token: 'hairline-subtle', floor: 5 },
+      default: { token: 'hairline-default', floor: 7 },
+      strong: { token: 'hairline-strong', floor: 12 },
+    } as const
+
+    for (const [name, { token, floor }] of Object.entries(HAIRLINES)) {
+      it(`${name} (${token}) clears ΔL* >= ${floor} on every ramp plane`, () => {
+        const hairlineColor = dark[token as keyof typeof dark]
+        for (const plane of PLANE_ORDER) {
+          const planeHex = RAMP_HEX[plane]
+          const composited = compositeOver(planeHex, hairlineColor)
+          const dL = lstar(composited) - lstar(planeHex)
+          expect(dL, `${name} on ${plane}`).toBeGreaterThanOrEqual(floor)
+        }
+      })
+    }
+
+    it('is near-constant (self-normalizing) across all planes: spread < 4 L* per tier', () => {
+      // Measured spread (inset..overlay): subtle ~1.6, default ~2.2, strong ~3.2 —
+      // still far tighter than a solid border token (which swings ~5.6 -> 0
+      // across this same ramp, see R4). "Near-constant" is relative to that,
+      // not perfectly flat — alpha-over-white is sublinear in L* as the base
+      // lightens, which is exactly the R3 floor-vs-doc discrepancy noted above.
+      for (const { token } of Object.values(HAIRLINES)) {
+        const hairlineColor = dark[token as keyof typeof dark]
+        const deltas = PLANE_ORDER.map((plane) => {
+          const planeHex = RAMP_HEX[plane]
+          return lstar(compositeOver(planeHex, hairlineColor)) - lstar(planeHex)
+        })
+        expect(Math.max(...deltas) - Math.min(...deltas)).toBeLessThan(4)
+      }
+    })
+  })
+
+  describe('R4 — border-on-surface clears ΔL* >= 3 (fixes the invisible-hairline collision)', () => {
+    it('border-subtle is no longer invisible on surface-raised (the original bug)', () => {
+      const dL = Math.abs(lstar(dark['border-subtle']) - lstar(dark['surface-raised']))
+      expect(dL).toBeGreaterThanOrEqual(3)
+    })
+
+    it('border-subtle clears ΔL* >= 3 against base/elevated/raised/overlay', () => {
+      const planes = [
+        'surface-base',
+        'surface-elevated',
+        'surface-raised',
+        'surface-overlay',
+      ] as const
+      for (const plane of planes) {
+        const dL = Math.abs(lstar(dark['border-subtle']) - lstar(dark[plane]))
+        expect(dL, `border-subtle vs ${plane}`).toBeGreaterThanOrEqual(3)
+      }
+    })
+  })
+
+  describe('R5 — background-frame and surface-inset (S-3 new tokens)', () => {
+    it('background-frame is darker than background-base', () => {
+      expect(lstar(dark['background-frame'])).toBeLessThan(lstar(dark['background-base']))
+    })
+
+    it('background-frame is distinct from every surface/background token', () => {
+      const otherTokens = [
+        'background-base',
+        'background-default',
+        'background-subtle',
+        'surface-base',
+        'surface-elevated',
+        'surface-raised',
+        'surface-overlay',
+        'surface-input',
+        'surface-inset',
+      ] as const
+      for (const token of otherTokens) {
+        expect(dark['background-frame'], `background-frame vs ${token}`).not.toBe(dark[token])
+      }
+    })
+
+    it('surface-inset is the darkest surface-family token', () => {
+      const surfaceFamily = [
+        'surface-base',
+        'surface-elevated',
+        'surface-raised',
+        'surface-overlay',
+        'surface-input',
+      ] as const
+      const insetL = lstar(dark['surface-inset'])
+      for (const token of surfaceFamily) {
+        expect(insetL, `surface-inset vs ${token}`).toBeLessThan(lstar(dark[token]))
+      }
+    })
+
+    it('surface-inset is distinct from background-frame', () => {
+      expect(dark['surface-inset']).not.toBe(dark['background-frame'])
+    })
+  })
+})