@titan-design/react-ui 0.9.2 → 0.10.0

package/src/theme/elevation.ts

@@ -1,21 +1,21 @@
 /**
  * Elevation System
- * 
+ *
  * A unified depth system where each elevation level corresponds to:
  * - Calculated surface color (derived from base using lighten)
  * - Shadow intensity and style (raised/pressed)
  * - Dynamically calculated shadow colors (derived from surface color)
  * - Semantic name for reference
- * 
+ *
  * Elevation range: -2 (deep inset) to +5 (floating overlay)
- * 
+ *
  * Negative elevations: Inset/pressed elements (sunken into surface)
  * Zero elevation: Base surface (background/page level)
  * Positive elevations: Raised elements (floating above surface)
- * 
+ *
  * All colors are calculated dynamically from a base surface color,
  * allowing for custom surfaces and consistent color relationships.
- * 
+ *
  * Lighting Model: Light source from upper-right corner
  * - Raised elements are always lighter than base (consistent across themes)
  * - Base colors must allow sufficient lightening in both themes
@@ -49,7 +49,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
     shadowStyle: 'pressed',
     description: 'Deeply recessed elements (e.g., input fields, deeply pressed buttons)',
   },
-  
+
   // Shallow inset (pressed buttons, sunken panels)
   [-1]: {
     name: 'inset',
@@ -58,7 +58,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
     shadowStyle: 'pressed',
     description: 'Shallow inset elements (e.g., pressed buttons, sunken panels within cards)',
   },
-  
+
   // Base level (page background, default surface)
   [0]: {
     name: 'base',
@@ -67,7 +67,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
     shadowStyle: 'raised',
     description: 'Base surface level (page background, default containers)',
   },
-  
+
   // Level 1: Subtle elevation (outline cards, subtle containers)
   [1]: {
     name: 'subtle',
@@ -76,7 +76,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
     shadowStyle: 'raised',
     description: 'Subtle elevation (outline cards, subtle containers)',
   },
-  
+
   // Level 2: Standard elevation (default cards, buttons)
   [2]: {
     name: 'standard',
@@ -85,7 +85,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
     shadowStyle: 'raised',
     description: 'Standard elevation (default cards, raised buttons)',
   },
-  
+
   // Level 3: Prominent elevation (important cards, modals)
   [3]: {
     name: 'prominent',
@@ -94,7 +94,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
     shadowStyle: 'raised',
     description: 'Prominent elevation (important cards, modals, dropdowns)',
   },
-  
+
   // Level 4: High elevation (overlays, popovers)
   [4]: {
     name: 'high',
@@ -103,7 +103,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
     shadowStyle: 'raised',
     description: 'High elevation (overlays, popovers, tooltips)',
   },
-  
+
   // Level 5: Floating (toasts, floating action buttons)
   [5]: {
     name: 'floating',
@@ -117,14 +117,14 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
 /**
  * Calculate rim light color from the BASE color.
  * Creates a consistent bright highlight with opacity that scales with elevation.
- * 
- * The rim light represents light hitting the edge of raised elements from a 
+ *
+ * The rim light represents light hitting the edge of raised elements from a
  * consistent light source. Uses ABSOLUTE HSV value (not relative lightening)
  * for consistent intensity across all surface colors.
- * 
+ *
  * For colored surfaces: preserves hue/saturation, sets value to fixed bright level
  * For gray surfaces: uses white with appropriate opacity
- * 
+ *
  * @param baseColor - The base surface color (hex)
  * @param level - Elevation level (used to scale opacity)
  */
@@ -133,22 +133,22 @@ function calculateRimLightColor(baseColor: string, level: ElevationLevel): strin
   if (!rgb) {
     return 'rgba(255, 255, 255, 0.5)'
   }
-  
+
   const hsv = rgbToHsv(rgb.r, rgb.g, rgb.b)
   const isLight = hsv.v > 0.6
-  const isSaturated = hsv.s > 0.3  // Colored (not gray)
-  
+  const isSaturated = hsv.s > 0.3 // Colored (not gray)
+
   // Opacity scales with elevation to compensate for lighter surfaces at higher levels
   // Range: +0% at level 1 to +20% at level 5
   const absLevel = Math.abs(level)
-  const opacityBoost = Math.max(0, (absLevel - 1) * 0.05)  // +5% per level above 1 (0% to 20%)
-  
+  const opacityBoost = Math.max(0, (absLevel - 1) * 0.05) // +5% per level above 1 (0% to 20%)
+
   if (isSaturated) {
     // For colored surfaces, preserve hue and saturation but set value to fixed bright level
     // This ensures consistent rim light intensity across all colored surfaces
-    const rimLightValue = 0.95  // Fixed bright value for rim light
-    const rimLightRgb = hsvToRgb(hsv.h, hsv.s * 0.3, rimLightValue)  // Reduce saturation for brighter appearance
-    
+    const rimLightValue = 0.95 // Fixed bright value for rim light
+    const rimLightRgb = hsvToRgb(hsv.h, hsv.s * 0.3, rimLightValue) // Reduce saturation for brighter appearance
+
     // Base opacity + elevation boost, capped at 1.0
     const baseOpacity = isLight ? 0.9 : 0.5
     const finalOpacity = Math.min(1, baseOpacity + opacityBoost)
@@ -164,10 +164,10 @@ function calculateRimLightColor(baseColor: string, level: ElevationLevel): strin
 /**
  * Calculate dark shadow colors from the surface color.
  * The dark shadow is cast BY the element, so it should match the surface color.
- * 
+ *
  * Uses ABSOLUTE HSV value (not relative darkening) for consistent shadow intensity
  * across all surface colors - simulating a consistent light source.
- * 
+ *
  * For colored surfaces: preserves hue/saturation, sets value to fixed dark level
  * For gray surfaces: uses black with appropriate opacity
  */
@@ -182,17 +182,17 @@ function calculateDarkShadowColors(surfaceColor: string): {
       darker: 'rgba(0, 0, 0, 0.4)',
     }
   }
-  
+
   const hsv = rgbToHsv(rgb.r, rgb.g, rgb.b)
   const isLight = hsv.v > 0.6
   const isSaturated = hsv.s > 0.3
-  
+
   if (isSaturated) {
     // For colored surfaces, preserve hue and saturation but set value to fixed dark level
     // This ensures consistent shadow intensity across all colored surfaces
-    const darkShadowValue = 0.15  // Fixed dark value for shadows
+    const darkShadowValue = 0.15 // Fixed dark value for shadows
     const darkShadowRgb = hsvToRgb(hsv.h, hsv.s, darkShadowValue)
-    
+
     if (isLight) {
       return {
         dark: `rgba(${darkShadowRgb.r}, ${darkShadowRgb.g}, ${darkShadowRgb.b}, 0.3)`,
@@ -227,8 +227,8 @@ function calculateDarkShadowColors(surfaceColor: string): {
  */
 function getRimLightConfig(): { offset: number; blur: number } {
   return {
-    offset: 1,  // Fixed 1px for crisp rim
-    blur: 1,    // Tight blur for crisp edge
+    offset: 1, // Fixed 1px for crisp rim
+    blur: 1, // Tight blur for crisp edge
   }
 }
 
@@ -253,18 +253,18 @@ function calculateElevationSurface(
   theme: 'light' | 'dark'
 ): string {
   const config = elevationSystem[level]
-  
+
   if (config.colorAdjustment === 0) {
     return baseColor
   }
-  
+
   // For raised elevations (positive), always lighten (consistent lighting model)
   // Light source is from upper-right, so raised elements are always lighter
   // For inset elevations (negative), we keep base color (shadow creates depth)
   if (level < 0) {
-    return baseColor  // Inset elements use base color
+    return baseColor // Inset elements use base color
   }
-  
+
   // Always lighten for raised elements (consistent across themes)
   // Base colors must be chosen to allow sufficient lightening in dark mode
   return lighten(baseColor, config.colorAdjustment)
@@ -273,7 +273,7 @@ function calculateElevationSurface(
 /**
  * Calculate surface color for an elevation level from a base color.
  * Results are cached to avoid redundant calculations.
- * 
+ *
  * @param baseColor - Base surface color (hex)
  * @param level - Elevation level
  * @param theme - Current theme ('light' or 'dark')
@@ -285,15 +285,15 @@ export function getElevationSurface(
   theme: 'light' | 'dark'
 ): string {
   const cacheKey = getCacheKey(baseColor, level, theme)
-  
+
   // Check cache
   if (elevationSurfaceCache.has(cacheKey)) {
     return elevationSurfaceCache.get(cacheKey)!
   }
-  
+
   // Calculate
   const result = calculateElevationSurface(baseColor, level, theme)
-  
+
   // Cache result (with size limit to prevent memory leaks)
   if (elevationSurfaceCache.size >= MAX_CACHE_SIZE) {
     // Remove oldest entry (simple FIFO)
@@ -301,7 +301,7 @@ export function getElevationSurface(
     elevationSurfaceCache.delete(firstKey)
   }
   elevationSurfaceCache.set(cacheKey, result)
-  
+
   return result
 }
 
@@ -309,7 +309,12 @@ export function getElevationSurface(
 const elevationShadowCache = new Map<string, ViewStyle>()
 const MAX_SHADOW_CACHE_SIZE = 50
 
-function getShadowCacheKey(baseColor: string, level: ElevationLevel, theme: 'light' | 'dark', isHovered: boolean): string {
+function getShadowCacheKey(
+  baseColor: string,
+  level: ElevationLevel,
+  theme: 'light' | 'dark',
+  isHovered: boolean
+): string {
   return `${baseColor}-${level}-${theme}-${isHovered}`
 }
 
@@ -320,35 +325,35 @@ function calculateElevationShadow(
   isHovered: boolean = false
 ): ViewStyle {
   const config = elevationSystem[level]
-  
+
   // Base level has no shadow
   if (level === 0) {
     return {}
   }
-  
+
   // Calculate the actual elevated surface color
   const elevatedSurfaceColor = calculateElevationSurface(baseColor, level, theme)
-  
+
   // Rim light: calculated from BASE color (consistent across all elevations)
   // This represents a consistent light source - only size changes with elevation
   const rimLightColor = calculateRimLightColor(baseColor, level)
-  
+
   // Dark shadow: calculated from ELEVATED surface color
   // The shadow is cast by the element, so it should match the surface
   const darkShadowColors = calculateDarkShadowColors(elevatedSurfaceColor)
-  
+
   // Get shadow intensity config (for dark shadow)
   const intensityConfig = {
     subtle: { offset: 1, blur: 2 },
     medium: { offset: 2, blur: 4 },
     strong: { offset: 2, blur: 5 },
   }
-  
+
   const { offset, blur } = intensityConfig[config.shadowIntensity]
-  
+
   // Get rim light config (scales with elevation level)
   const rimConfig = getRimLightConfig()
-  
+
   if (config.shadowStyle === 'pressed') {
     // Inset shadow (pressed elements)
     if (isHovered) {
@@ -365,7 +370,7 @@ function calculateElevationShadow(
         },
       }) as ViewStyle
     }
-    
+
     return Platform.select({
       web: {
         boxShadow: `inset ${offset}px ${offset}px ${blur}px ${darkShadowColors.darker}, inset -${rimConfig.offset}px -${rimConfig.offset}px ${rimConfig.blur}px ${rimLightColor}`,
@@ -394,7 +399,7 @@ function calculateElevationShadow(
         },
       }) as ViewStyle
     }
-    
+
     return Platform.select({
       web: {
         boxShadow: `${offset}px ${offset}px ${blur}px ${darkShadowColors.dark}, -${rimConfig.offset}px -${rimConfig.offset}px ${rimConfig.blur}px ${rimLightColor}`,
@@ -413,7 +418,7 @@ function calculateElevationShadow(
 /**
  * Get shadow style for an elevation level, calculated dynamically from surface color.
  * Results are cached to avoid redundant calculations.
- * 
+ *
  * @param baseColor - Base surface color (hex)
  * @param level - Elevation level
  * @param theme - Current theme ('light' or 'dark')
@@ -427,44 +432,65 @@ export function getElevationShadow(
   isHovered: boolean = false
 ): ViewStyle {
   const cacheKey = getShadowCacheKey(baseColor, level, theme, isHovered)
-  
+
   // Check cache
   if (elevationShadowCache.has(cacheKey)) {
     return elevationShadowCache.get(cacheKey)!
   }
-  
+
   // Calculate shadow
   const result = calculateElevationShadow(baseColor, level, theme, isHovered)
-  
+
   // Cache result
   if (elevationShadowCache.size >= MAX_SHADOW_CACHE_SIZE) {
     const firstKey = elevationShadowCache.keys().next().value!
     elevationShadowCache.delete(firstKey)
   }
   elevationShadowCache.set(cacheKey, result)
-  
+
   return result
 }
 
+/**
+ * Elevation level backing a `<Surface pressed>` recess: the shallow `inset`
+ * (-1) step. Pressed exposes ONE level of depth — pressed-2 is intentionally
+ * not surfaced (the deeper `-2` deep-inset stays available to `elevation`).
+ */
+export const PRESSED_ELEVATION_LEVEL: ElevationLevel = -1
+
+/**
+ * Inner-shadow recess for a pressed (sunken) surface, tuned to the well's own
+ * fill colour so the rim/shadow tints track the darker fill. Composes WITH the
+ * darker pressed fill: on web it adds an inset boxShadow; on the native path
+ * (no inset-shadow support) it's a no-op and the recess reads via the fill
+ * alone — so a pressed surface stays legibly sunken with or without the shadow.
+ *
+ * @param fillColor - The pressed surface's own fill (one ramp step down).
+ * @param theme - Current theme ('light' or 'dark').
+ */
+export function getPressedRecessShadow(fillColor: string, theme: 'light' | 'dark'): ViewStyle {
+  return getElevationShadow(fillColor, PRESSED_ELEVATION_LEVEL, theme)
+}
+
 /**
  * Get base surface color from theme.
  * This is the foundation color that all elevations are calculated from.
- * 
+ *
  * IMPORTANT: Base colors must be chosen to allow sufficient lightening.
- * 
+ *
  * **Light Mode**: Cannot use `#FFFFFF` (white) - cannot lighten white!
  *   - Use `#F3F4F6` (neutral[100]) - can lighten to `#FAFAFA` → `#FFFFFF`
  *   - This allows raised elevations to be lighter (closer to white)
- * 
+ *
  * **Dark Mode**: Need lighter base to allow sufficient lightening
- *   - Use `#191919` (charcoal[600]) - allows lightening to `#2A2A2A` at max elevation
- * 
+ *   - Use `surface-elevated` (#2A2827, TD-surface-tokens ramp) - allows further lightening
+ *
  * Can be overridden to use custom base colors for special cases.
  */
 export function getBaseSurfaceColor(theme: 'light' | 'dark'): string {
   // Use semantic token values so elevation colors stay in sync with the token pipeline.
   // Light mode: surface-raised (#F3F4F6 / neutral[100]) - NOT white, so we can lighten it
-  // Dark mode: surface-elevated (#191919 / charcoal[600]) - allows sufficient lightening
+  // Dark mode: surface-elevated (#2A2827, TD-surface-tokens ramp) - allows sufficient lightening
 
   return theme === 'light'
     ? semanticColorsLight['surface-raised']
@@ -544,10 +570,7 @@ const glowConfig: Record<GlowIntensity, { blur: number; spread: number; opacity:
  * @param intensity - Glow intensity level
  * @returns ViewStyle with platform-specific shadow properties
  */
-export function getGlowShadow(
-  color: string,
-  intensity: GlowIntensity = 'medium'
-): ViewStyle {
+export function getGlowShadow(color: string, intensity: GlowIntensity = 'medium'): ViewStyle {
   const config = glowConfig[intensity]
   const rgb = hexToRgb(color)
   if (!rgb) return {}

package/src/theme/global.css

@@ -94,15 +94,25 @@
     --color-text-link: #828DF8;
     --color-text-link-hover: #60A5FA;
 
-    --color-surface-base: #161616;
-    --color-surface-elevated: #191919;
-    --color-surface-raised: #1C1C1C;
-    --color-surface-overlay: #191919;
-    --color-surface-input: #191919;
-
-    --color-background-base: #101010;
-    --color-background-default: #161616;
-    --color-background-subtle: #1C1C1C;
+    /* Surface ramp — warm-tapered DERIVED, shipped verbatim from deriveSurfaceRamp()
+       (TD-surface-tokens, S-1, re-spaced S-3). surface-overlay and surface-elevated
+       are distinct (were both #191919 pre-S-1); see surfaceRampDark in
+       tokens/primitives.ts. surface-inset is the ramp's floor, promoted to a real
+       token at S-3 (was unwired). */
+    --color-surface-base: #252321;
+    --color-surface-elevated: #2C2A28;
+    --color-surface-raised: #31302F;
+    --color-surface-overlay: #373635;
+    --color-surface-input: #2C2A28;
+    --color-surface-inset: #13100D;
+
+    --color-background-base: #1C1916;
+    --color-background-default: #252321;
+    --color-background-subtle: #2C2A28;
+    /* Frame/bezel chrome (S-3) — top bar + side nav shell, one step below
+       background-base, darker even than surface-inset. See backgroundFrameDark
+       in tokens/primitives.ts. */
+    --color-background-frame: #100D0A;
 
     --color-border-default: #1F1F1F;
     --color-border-subtle: #1C1C1C;
@@ -113,6 +123,11 @@
     --color-border-input-focus: #828DF8;
     --color-border-input-error: #EF4444;
 
+    /* Alpha hairline separators — self-normalizing on any plane (§4/S-2) */
+    --color-hairline-subtle: rgba(255, 255, 255, 0.06);
+    --color-hairline-default: rgba(255, 255, 255, 0.09);
+    --color-hairline-strong: rgba(255, 255, 255, 0.14);
+
     --color-interactive-hover: rgba(255, 255, 255, 0.04);
     --color-interactive-focus: rgba(255, 255, 255, 0.12);
     --color-interactive-active: rgba(255, 255, 255, 0.16);
@@ -236,10 +251,15 @@
     --color-surface-raised: #F3F4F6;
     --color-surface-overlay: #FFFFFF;
     --color-surface-input: #FAFAFA;
+    /* Placeholder pairing (S-3) — light-mode counterpart of the dark ramp's
+       inset plane; not part of the dark-ramp investigation. */
+    --color-surface-inset: #D1D5DB;
 
     --color-background-base: #EBEBEB;
     --color-background-default: #FFFFFF;
     --color-background-subtle: #FAFAFA;
+    /* Placeholder pairing (S-3) — see --color-surface-inset note above. */
+    --color-background-frame: #9CA3AF;
 
     --color-border-default: #E8E9EB;
     --color-border-subtle: #F3F4F6;
@@ -250,6 +270,12 @@
     --color-border-input-focus: #5048E5;
     --color-border-input-error: #D14343;
 
+    /* Alpha hairline separators — mirrors the dark-mode white-alpha family,
+       composited toward black on light surfaces (§4/S-2). */
+    --color-hairline-subtle: rgba(0, 0, 0, 0.06);
+    --color-hairline-default: rgba(0, 0, 0, 0.09);
+    --color-hairline-strong: rgba(0, 0, 0, 0.14);
+
     --color-interactive-hover: rgba(55, 65, 81, 0.04);
     --color-interactive-focus: rgba(55, 65, 81, 0.12);
     --color-interactive-active: rgba(55, 65, 81, 0.16);

package/src/theme/tokens/primitives.ts

@@ -84,6 +84,46 @@ export const primitiveColors = {
   transparent: 'transparent',
 } as const
 
+/**
+ * Surface ramp — dark mode (TD-surface-tokens, S-1, re-spaced S-3)
+ *
+ * Warm-tapered, DERIVED ramp — NOT hand-picked. Shipped verbatim as the output of
+ * `deriveSurfaceRamp(shellL=9, steps=[4.5,3.5,3,2.5], rbShadow=6, rbHilite=1.5)`
+ * (see `packages/ui/src/components/ui/surface/surface-lab-shared.tsx` on branch
+ * `feat/TD-unified-lab`, story `Lab/Surface Exploration -> Surface Ramp System`
+ * — that lab default is `[4.5,2.5,2,1.5]` as of this writing and should be
+ * updated to match on that branch, follow-up, not done here).
+ * Lightness is CIELAB L* off the shell, with DIMINISHING steps (4.5/3.5/3/2.5) —
+ * the frame->content jump is biggest, each plane above adds less, but the top
+ * three planes (elevated/raised/overlay) were re-spaced WIDER (S-3) than the
+ * original 2.5/2/1.5 taper so they read as distinct planes without leaning on
+ * the hairline alone. `background`/`base`/`inset` are unchanged by the re-space.
+ * Warmth (R-B) tapers 6 -> 1.5 from frame to hero so bright content planes stay
+ * near-neutral.
+ * Kept separate from the `charcoal` scale above (which several existing
+ * components reference directly for unrelated shadow/track tints) so this
+ * change is additive and doesn't ripple into those consumers.
+ * See coordination/design-explorations/surface-system-north-star.md.
+ */
+export const surfaceRampDark = {
+  inset: '#13100D',      // L*4.5  — sub-shell well / pressed
+  background: '#1C1916', // L*9    — shell / frame
+  base: '#252321',       // L*13.5 — main content plane
+  elevated: '#2C2A28',   // L*17   — nav / rail
+  raised: '#31302F',     // L*20   — cards
+  overlay: '#373635',    // L*22.5 — hero / popover
+} as const
+
+/**
+ * Frame/bezel primitive — dark mode (TD-surface-tokens, S-3)
+ *
+ * The chrome that "exits the content ramp" entirely: the top bar + side nav
+ * shell. Sits ONE STEP BELOW `surfaceRampDark.background` (L*9), darker even
+ * than `surfaceRampDark.inset` (L*4.5) — it isn't a plane IN the ramp, it's
+ * the bezel the ramp sits inside. Literal, not `deriveSurfaceRamp()` output.
+ */
+export const backgroundFrameDark = '#100D0A' // L*3.79
+
 /**
  * Derived tonal ramps (TD-05.09 color foundations)
  *

package/src/theme/tokens/semantic.ts

@@ -17,7 +17,13 @@
  * - interactive-* : Hover/focus/active/disabled states
  */
 
-import { primitiveColors as p, primitiveRamps as ramp, discreteRainbow } from './primitives'
+import {
+  primitiveColors as p,
+  primitiveRamps as ramp,
+  discreteRainbow,
+  surfaceRampDark as surf,
+  backgroundFrameDark,
+} from './primitives'
 
 // Light mode semantic colors (default)
 export const semanticColorsLight = {
@@ -120,11 +126,20 @@ export const semanticColorsLight = {
   'surface-raised': p.neutral[100],           // light gray for raised cards
   'surface-overlay': p.white,
   'surface-input': p.neutral[50],             // Input field background (filled variant)
+  // Deepest pressed pit (TD-surface-tokens, S-3) — light-mode counterpart of
+  // the dark ramp's `inset` plane; a placeholder pairing, not part of the
+  // dark-ramp investigation (surface.contract.test.ts is dark-mode only).
+  'surface-inset': p.neutral[300],
 
   // Background colors (background-*)
   'background-base': '#EBEBEB',
   'background-default': p.white,
   'background-subtle': p.neutral[50],
+  // Frame/bezel chrome (TD-surface-tokens, S-3) — top bar + side nav shell,
+  // one step below `background-base` (darker still than `surface-inset`
+  // above, mirroring the dark-mode ordering). Placeholder pairing for light
+  // mode (see dark-mode note on `surface-inset` above).
+  'background-frame': p.neutral[400],
 
   // Border colors (border-*)
   'border-default': '#E8E9EB',
@@ -137,6 +152,12 @@ export const semanticColorsLight = {
   'border-input-focus': p.blue[600],          // Input field border on focus
   'border-input-error': p.red[600],           // Input field border on error
 
+  // Alpha hairline separators (surface-independent — composite toward black on
+  // light surfaces, mirroring the dark-mode white-alpha family). See §4/S-2.
+  'hairline-subtle': 'rgba(0, 0, 0, 0.06)',
+  'hairline-default': 'rgba(0, 0, 0, 0.09)',
+  'hairline-strong': 'rgba(0, 0, 0, 0.14)',
+
   // Interactive states (interactive-*)
   'interactive-hover': 'rgba(55, 65, 81, 0.04)',
   'interactive-focus': 'rgba(55, 65, 81, 0.12)',
@@ -247,19 +268,38 @@ export const semanticColorsDark = {
   'text-link': '#828DF8',
   'text-link-hover': p.blue[400],
 
-  // Surface colors - dark backgrounds
-  'surface-base': p.charcoal[700],         // main surface
-  'surface-elevated': p.charcoal[600],     // elevated surface
-  'surface-raised': p.charcoal[500],       // raised surface
-  'surface-overlay': p.charcoal[600],      // overlay surface
-  'surface-input': p.charcoal[600],        // input surface
-
-  // Background colors
-  'background-base': p.charcoal[900],      // darkest charcoal
-  'background-default': p.charcoal[700],    // main background
-  'background-subtle': p.charcoal[500],     // subtle background
-
-  // Border colors
+  // Surface colors - dark backgrounds — warm-tapered DERIVED ramp (TD-surface-tokens,
+  // S-1, re-spaced S-3). Shipped verbatim from `deriveSurfaceRamp()` — see
+  // `surfaceRampDark` in primitives.ts for the full derivation note. `surface-overlay`
+  // and `surface-elevated` are distinct (were both #191919 pre-S-1); `surface-input`
+  // tracks one plane above `surface-base`, same relative position as before the remap.
+  // `background-base` backs `Surface level="background"` (SurfaceContext.SURFACE_LEVEL_TOKEN),
+  // so it takes the ramp's `background` (shell/frame) role, NOT `inset`. The ramp's
+  // deepest `inset` plane is now promoted to `surface-inset` below (S-3) — still no
+  // `SurfaceLevel` member for it (follow-up, alongside the elevation.ts -1/-2 pressed
+  // levels — parallel workstream, not this branch).
+  'surface-base': surf.base,               // main surface        (#252321, L*13.5)
+  'surface-elevated': surf.elevated,       // elevated surface     (#2C2A28, L*17   — nav/rail)
+  'surface-raised': surf.raised,           // raised surface       (#31302F, L*20   — cards)
+  'surface-overlay': surf.overlay,         // overlay surface      (#373635, L*22.5 — hero/popover)
+  'surface-input': surf.elevated,          // input surface        (#2C2A28 — one plane above base)
+  'surface-inset': surf.inset,             // deepest pressed pit  (#13100D, L*4.5  — sub-shell well)
+
+  // Background colors — same ramp, the frame/shell end of it.
+  'background-base': surf.background,      // shell / frame        (#1C1916, L*9 — Surface level="background")
+  'background-default': surf.base,         // main background      (#252321, L*13.5 — matches surface-base)
+  'background-subtle': surf.elevated,      // subtle background    (#2C2A28, L*17 — matches surface-elevated)
+  // Frame/bezel chrome (S-3) — the top bar + side nav shell; one step BELOW
+  // `background-base`, darker even than `surface-inset` — it exits the content
+  // ramp entirely rather than sitting in it. See `backgroundFrameDark` in
+  // primitives.ts.
+  'background-frame': backgroundFrameDark, // frame / bezel        (#100D0A, L*3.79)
+
+  // Border colors — `border-subtle` (#1C1C1C) previously collided with
+  // `surface-raised` (also #1C1C1C, an invisible border on raised cards). The
+  // re-spaced ramp above moved `surface-raised` to #2D2C2B, so this value is now
+  // distinct from every surface hex without needing to change it — see
+  // `surface.contract.test.ts` R2/R4.
   'border-default': p.charcoal[400],       // default border
   'border-subtle': p.charcoal[500],        // subtle border
   'border-strong': p.charcoal[300],        // strong border
@@ -270,6 +310,15 @@ export const semanticColorsDark = {
   'border-input-focus': '#828DF8',
   'border-input-error': p.red[500],
 
+  // Alpha hairline separators — the primary separation cue (§4/S-2). Self-
+  // normalizing: composites toward white by ~the same amount on ANY plane, so
+  // one family works at every elevation instead of per-surface border tokens.
+  // Shadows are demoted to floating-overlay use only (not shipped as a fill
+  // separator here — see elevation.ts, follow-up S-4).
+  'hairline-subtle': 'rgba(255, 255, 255, 0.06)',
+  'hairline-default': 'rgba(255, 255, 255, 0.09)',
+  'hairline-strong': 'rgba(255, 255, 255, 0.14)',
+
   // Interactive states
   'interactive-hover': 'rgba(255, 255, 255, 0.04)',
   'interactive-focus': 'rgba(255, 255, 255, 0.12)',