@titan-design/react-ui 0.9.3 → 0.11.0

package/src/theme/config.ts

@@ -77,10 +77,12 @@ export const lightThemeCSSVars = {
   '--color-surface-base': semanticColorsLight['surface-base'],
   '--color-surface-elevated': semanticColorsLight['surface-elevated'],
   '--color-surface-raised': semanticColorsLight['surface-raised'],
+  '--color-surface-inset': semanticColorsLight['surface-inset'],
 
   '--color-background-base': semanticColorsLight['background-base'],
   '--color-background-default': semanticColorsLight['background-default'],
   '--color-background-subtle': semanticColorsLight['background-subtle'],
+  '--color-background-frame': semanticColorsLight['background-frame'],
 
   '--color-border-default': semanticColorsLight['border-default'],
   '--color-border-subtle': semanticColorsLight['border-subtle'],
@@ -150,6 +152,10 @@ export const lightThemeCSSVars = {
   '--color-border-input-focus': semanticColorsLight['border-input-focus'],
   '--color-border-input-error': semanticColorsLight['border-input-error'],
 
+  '--color-hairline-subtle': semanticColorsLight['hairline-subtle'],
+  '--color-hairline-default': semanticColorsLight['hairline-default'],
+  '--color-hairline-strong': semanticColorsLight['hairline-strong'],
+
   '--color-interactive-disabled-text': semanticColorsLight['interactive-disabled-text'],
 
   '--color-avatar-background': semanticColorsLight['avatar-background'],
@@ -198,10 +204,12 @@ export const darkThemeCSSVars = {
   '--color-surface-base': semanticColorsDark['surface-base'],
   '--color-surface-elevated': semanticColorsDark['surface-elevated'],
   '--color-surface-raised': semanticColorsDark['surface-raised'],
+  '--color-surface-inset': semanticColorsDark['surface-inset'],
 
   '--color-background-base': semanticColorsDark['background-base'],
   '--color-background-default': semanticColorsDark['background-default'],
   '--color-background-subtle': semanticColorsDark['background-subtle'],
+  '--color-background-frame': semanticColorsDark['background-frame'],
 
   '--color-border-default': semanticColorsDark['border-default'],
   '--color-border-subtle': semanticColorsDark['border-subtle'],
@@ -271,6 +279,10 @@ export const darkThemeCSSVars = {
   '--color-border-input-focus': semanticColorsDark['border-input-focus'],
   '--color-border-input-error': semanticColorsDark['border-input-error'],
 
+  '--color-hairline-subtle': semanticColorsDark['hairline-subtle'],
+  '--color-hairline-default': semanticColorsDark['hairline-default'],
+  '--color-hairline-strong': semanticColorsDark['hairline-strong'],
+
   '--color-interactive-disabled-text': semanticColorsDark['interactive-disabled-text'],
 
   '--color-avatar-background': semanticColorsDark['avatar-background'],

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)
  *