@titan-design/react-ui 0.11.0 → 0.12.0

package/src/theme/barrel.ts

@@ -8,7 +8,8 @@
 // top for the native consumers that deliberately import it.
 export * from './tokens'
 export * from './config'
-export * from './shadows'
+export * from './materials'
+export * from './color-utils'
 export * from './elevation'
 export * from './manifest'
 export { resolveColor } from './resolve-color'
@@ -22,24 +23,16 @@ export type { ThemeProviderProps, ThemeProviderMode } from './ThemeProvider'
 export { getSemanticColors, type ThemeMode } from './tokens/semantic'
 export { getThemeCSSVars, gluestackConfig } from './config'
 export {
-  neumorphicShadows,
-  // Color math utilities (HSV-based)
+  hexToRgb,
+  rgbToHsv,
+  hsvToRgb,
+  rgbToHex,
   lighten,
   darken,
   getHoverColors,
   isDark,
-  hexToRgb,
-  rgbToHsv,
-  // Shadow creation functions
-  createRaisedShadow,
-  createRaisedHoverShadow,
-  createPressedShadow,
-  createPressedHoverShadow,
-  createFlatShadow,
-  shadowColors,
   type ShadowIntensity,
-  type ShadowSurface,
-} from './shadows'
+} from './color-utils'
 export {
   getElevationConfig,
   getElevationSurface,

package/src/theme/color-stories.coverage.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest'
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { surfaceRampDark, backgroundFrameDark } from './tokens/primitives'
+import { greyRamp, SURFACE_PLANE_STEPS } from './tokens/primitives'
 import { semanticColorsDark } from './tokens/semantic'
 
 /**
@@ -11,7 +11,7 @@ import { semanticColorsDark } from './tokens/semantic'
  * The color stories are the documentation of record for the token layer, and
  * they have drifted twice: once when the categorical palette replaced the
  * Paul-Tol scale, and again when the v0.10.0 surface redesign added four
- * planes (`surface-inset`, `surface-overlay`, `background-frame`,
+ * planes (`surface-overlay`, `background-frame`,
  * `background-subtle`) that no story rendered. Both times the values stayed
  * correct while the *coverage* silently fell behind — which a screenshot test
  * cannot catch, because a story that was never written renders nothing.
@@ -41,7 +41,9 @@ const storySources = ['ColorPrimitives.stories.tsx', 'ColorPalettes.stories.tsx'
   .join('\n')
 
 /** Every plane a surface/background token is allowed to land on. */
-const RAMP_PLANES = new Set<string>([...Object.values(surfaceRampDark), backgroundFrameDark])
+const RAMP_PLANES = new Set<string>(
+  Object.values(SURFACE_PLANE_STEPS).map((step) => greyRamp[step])
+)
 
 /**
  * Token families the color stories are NOT the documentation of record for,
@@ -69,9 +71,9 @@ describe('Foundations/Color story coverage', () => {
 
     expect(
       offRamp,
-      'surface/background tokens whose value is not a step of surfaceRampDark ' +
-        '(or the backgroundFrameDark bezel). Either fold the value into the ramp, ' +
-        'or add the plane to SURFACE_PLANES in ColorPalettes.stories.tsx and document why ' +
+      'surface/background tokens whose value is not one of the greyRamp steps ' +
+        'named in SURFACE_PLANE_STEPS. Either fold the value into the ramp, or add ' +
+        'the plane to SURFACE_PLANES in ColorPalettes.stories.tsx and document why ' +
         'it sits outside the ramp.'
     ).toEqual([])
   })
@@ -86,22 +88,15 @@ describe('Foundations/Color story coverage', () => {
   })
 
   it('the surface story renders every ramp plane', () => {
-    // SURFACE_PLANES is built from the ramp exports, so covering the exports
-    // is what proves no plane is missing from the rendered ladder.
-    const referenced = [
-      'surfaceRampDark.inset',
-      'surfaceRampDark.background',
-      'surfaceRampDark.base',
-      'surfaceRampDark.elevated',
-      'surfaceRampDark.raised',
-      'surfaceRampDark.overlay',
-      'backgroundFrameDark',
-    ]
-    const missing = referenced.filter((ref) => !storySources.includes(ref))
+    // Each plane is a greyRamp step now, so the ladder must reference the step
+    // rather than a named member of a separate ramp object.
+    const missing = Object.values(SURFACE_PLANE_STEPS)
+      .map((step) => `greyRamp[${step}]`)
+      .filter((ref) => !storySources.includes(ref))
 
     expect(missing, 'ramp planes absent from the SURFACE_PLANES ladder').toEqual([])
-    // Guard the count too: a step added to the ramp must gain a row.
-    expect(Object.keys(surfaceRampDark)).toHaveLength(6)
+    // Guard the count too: a plane added to the ramp must gain a row.
+    expect(Object.keys(SURFACE_PLANE_STEPS)).toHaveLength(6)
   })
 
   it('every other semantic token is named in a color story', () => {

package/src/theme/color-story-kit.tsx

@@ -22,7 +22,7 @@ import { semanticColorsDark } from './tokens/semantic'
  * reads as one. Sourced from the token layer rather than a literal — the color
  * stories should not be where raw hexes creep back in.
  */
-export const SWATCH_BORDER = semanticColorsDark['border-default']
+export const SWATCH_BORDER = semanticColorsDark['hairline-default']
 
 export function SectionIntro({ children }: { children: ReactNode }) {
   return <Text className="text-text-secondary mb-6">{children}</Text>

package/src/theme/color-utils.ts

@@ -0,0 +1,197 @@
+/**
+ * Colour math shared by the depth system.
+ *
+ * This file used to be `shadows.ts` and shipped a neumorphic shadow builder —
+ * dual opposing shadows, dark bottom-right and light top-left. That was removed
+ * in TD-07.16. Neumorphism needs a mid-tone background (roughly 75-90%
+ * lightness) so BOTH shadows have somewhere to fall; our surfaces sit near 10%,
+ * which leaves the dark half nothing to fall onto. It collapsed to a one-sided
+ * rim light and read as noise on the wall.
+ *
+ * Inline depth is a hairline now (`hairline-*`, self-normalising alpha), texture
+ * is `materials.ts`, and drop-shadow survives only for genuinely FLOATING
+ * things — see `elevation.ts`.
+ *
+ * What is left here is the HSV/hex maths that `elevation.ts` still uses to
+ * derive rim and shadow tints from whatever surface colour it is handed.
+ */
+
+// ============================================================================
+// Color Math Utilities
+// ============================================================================
+
+/**
+ * Parse a hex color to RGB values (0-255).
+ * Supports both #RGB and #RRGGBB formats.
+ */
+export function hexToRgb(hex: string): { r: number; g: number; b: number } | null {
+  const cleaned = hex.replace('#', '')
+  
+  let r: number, g: number, b: number
+  
+  if (cleaned.length === 3) {
+    r = parseInt(cleaned[0] + cleaned[0], 16)
+    g = parseInt(cleaned[1] + cleaned[1], 16)
+    b = parseInt(cleaned[2] + cleaned[2], 16)
+  } else if (cleaned.length === 6) {
+    r = parseInt(cleaned.slice(0, 2), 16)
+    g = parseInt(cleaned.slice(2, 4), 16)
+    b = parseInt(cleaned.slice(4, 6), 16)
+  } else {
+    return null
+  }
+  
+  return { r, g, b }
+}
+
+/**
+ * Convert RGB (0-255) to HSV (h: 0-360, s: 0-1, v: 0-1).
+ */
+export function rgbToHsv(r: number, g: number, b: number): { h: number; s: number; v: number } {
+  const rNorm = r / 255
+  const gNorm = g / 255
+  const bNorm = b / 255
+  
+  const max = Math.max(rNorm, gNorm, bNorm)
+  const min = Math.min(rNorm, gNorm, bNorm)
+  const delta = max - min
+  
+  // Value
+  const v = max
+  
+  // Saturation
+  const s = max === 0 ? 0 : delta / max
+  
+  // Hue
+  let h = 0
+  if (delta !== 0) {
+    if (max === rNorm) {
+      h = 60 * (((gNorm - bNorm) / delta) % 6)
+    } else if (max === gNorm) {
+      h = 60 * ((bNorm - rNorm) / delta + 2)
+    } else {
+      h = 60 * ((rNorm - gNorm) / delta + 4)
+    }
+  }
+  if (h < 0) h += 360
+  
+  return { h, s, v }
+}
+
+/**
+ * Convert HSV (h: 0-360, s: 0-1, v: 0-1) to RGB (0-255).
+ */
+export function hsvToRgb(h: number, s: number, v: number): { r: number; g: number; b: number } {
+  const c = v * s
+  const x = c * (1 - Math.abs((h / 60) % 2 - 1))
+  const m = v - c
+  
+  let rPrime: number, gPrime: number, bPrime: number
+
+  if (h >= 0 && h < 60) {
+    rPrime = c; gPrime = x; bPrime = 0
+  } else if (h >= 60 && h < 120) {
+    rPrime = x; gPrime = c; bPrime = 0
+  } else if (h >= 120 && h < 180) {
+    rPrime = 0; gPrime = c; bPrime = x
+  } else if (h >= 180 && h < 240) {
+    rPrime = 0; gPrime = x; bPrime = c
+  } else if (h >= 240 && h < 300) {
+    rPrime = x; gPrime = 0; bPrime = c
+  } else {
+    rPrime = c; gPrime = 0; bPrime = x
+  }
+  
+  return {
+    r: Math.round((rPrime + m) * 255),
+    g: Math.round((gPrime + m) * 255),
+    b: Math.round((bPrime + m) * 255),
+  }
+}
+
+/**
+ * Convert RGB values to hex string.
+ */
+export function rgbToHex(r: number, g: number, b: number): string {
+  const toHex = (n: number) => {
+    const clamped = Math.max(0, Math.min(255, Math.round(n)))
+    return clamped.toString(16).padStart(2, '0')
+  }
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
+}
+
+/**
+ * Lighten a color by increasing its HSV Value component.
+ * 
+ * @param hex - The hex color to lighten
+ * @param amount - Amount to increase V by (0-1)
+ */
+export function lighten(hex: string, amount: number = 0.1): string {
+  const rgb = hexToRgb(hex)
+  if (!rgb) return hex
+  
+  const hsv = rgbToHsv(rgb.r, rgb.g, rgb.b)
+  const newV = Math.min(1, hsv.v + amount)
+  
+  const newRgb = hsvToRgb(hsv.h, hsv.s, newV)
+  return rgbToHex(newRgb.r, newRgb.g, newRgb.b)
+}
+
+/**
+ * Darken a color by decreasing its HSV Value component.
+ * 
+ * @param hex - The hex color to darken
+ * @param amount - Amount to decrease V by (0-1)
+ */
+export function darken(hex: string, amount: number = 0.1): string {
+  const rgb = hexToRgb(hex)
+  if (!rgb) return hex
+  
+  const hsv = rgbToHsv(rgb.r, rgb.g, rgb.b)
+  const newV = Math.max(0, hsv.v - amount)
+  
+  const newRgb = hsvToRgb(hsv.h, hsv.s, newV)
+  return rgbToHex(newRgb.r, newRgb.g, newRgb.b)
+}
+
+/**
+ * Get hover colors for a button based on its background color.
+ * Automatically adapts intensity based on the color's luminance.
+ * 
+ * @param bgColor - The button's background color (hex)
+ * @param intensity - How strong the hover effect should be ('subtle' | 'medium' | 'strong')
+ */
+export function getHoverColors(
+  bgColor: string, 
+  intensity: 'subtle' | 'medium' | 'strong' = 'medium'
+): { raised: string; pressed: string } {
+  const amounts = {
+    subtle: 0.01,
+    medium: 0.02,
+    strong: 0.03,
+  }
+  
+  const amount = amounts[intensity]
+  
+  return {
+    raised: lighten(bgColor, amount),  // Raised hover: lighten (lifting up)
+    pressed: darken(bgColor, amount),  // Pressed hover: darken (pressing down)
+  }
+}
+
+/**
+ * Check if a color is considered "dark" (for choosing text color).
+ * Uses HSV Value component for simplicity.
+ */
+export function isDark(hex: string): boolean {
+  const rgb = hexToRgb(hex)
+  if (!rgb) return true
+  const hsv = rgbToHsv(rgb.r, rgb.g, rgb.b)
+  return hsv.v < 0.6
+}
+
+/**
+ * Shadow strength tiers. Retained because `elevation.ts` keys its level table on
+ * them; the neumorphic shadow BUILDERS that used to live here are gone.
+ */
+export type ShadowIntensity = 'subtle' | 'medium' | 'strong'

package/src/theme/config.ts

@@ -77,16 +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'],
-  '--color-border-strong': semanticColorsLight['border-strong'],
   '--color-border-prominent': semanticColorsLight['border-prominent'],
   '--color-border-focus': semanticColorsLight['border-focus'],
 
@@ -204,16 +200,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'],
-  '--color-border-strong': semanticColorsDark['border-strong'],
   '--color-border-prominent': semanticColorsDark['border-prominent'],
   '--color-border-focus': semanticColorsDark['border-focus'],
 

package/src/theme/depth-calibration.test.tsx

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { composeStories } from '@storybook/react'
+import * as stories from './DepthCalibration.stories'
+
+/**
+ * The calibration rig is the gate on a release tag, and its whole value rests on
+ * one property: the answer key is NOT on screen until the operator asks for it.
+ * A leaked key does not make the panels look broken — it makes them look fine,
+ * and silently converts a measurement into a confirmation.
+ *
+ * The theme stories are outside `stories-smoke.test.tsx`'s
+ * `../components/**` glob, so this file also carries the render smoke for them.
+ */
+const { Hairlines, ToneSteps, PaperMaterial, Banding } = composeStories(stories)
+const ALL = { Hairlines, ToneSteps, PaperMaterial, Banding }
+
+describe('depth calibration rig', () => {
+  for (const [name, Story] of Object.entries(ALL)) {
+    it(`${name} renders`, () => {
+      const result = render(<Story />)
+      expect(result.container.firstChild).toBeTruthy()
+      result.unmount()
+    })
+  }
+
+  it('hides every answer until Reveal is pressed, then shows them', () => {
+    render(<Hairlines />)
+
+    // grey-975 is the ground of row 1; naming a ground names an answer.
+    expect(screen.queryByText(/grey-975/)).toBeNull()
+    expect(screen.queryByText(/decoy/)).toBeNull()
+
+    fireEvent.click(screen.getByText('Reveal key'))
+
+    expect(screen.getAllByText(/grey-975/).length).toBeGreaterThan(0)
+    expect(screen.getAllByText(/decoy/).length).toBe(4)
+  })
+
+  it('seeds exactly four blank cells across four distinct grounds', () => {
+    render(<Hairlines />)
+    fireEvent.click(screen.getByText('Reveal key'))
+
+    // One decoy per row, so no row can be answered by "the blank one is here again".
+    const decoys = screen.getAllByText(/NONE \(decoy\)/)
+    expect(decoys).toHaveLength(4)
+
+    const rows = decoys.map((n) => n.textContent?.match(/^[A-D](\d)/)?.[1])
+    expect(new Set(rows).size).toBe(4)
+  })
+
+  it('seeds an identical pair among the paper sheets', () => {
+    render(<PaperMaterial />)
+    expect(screen.queryByText(/FLAT \(decoy\)/)).toBeNull()
+
+    // Two byte-identical flats, so "all three look the same" stays an available
+    // answer rather than an admission — the material has to be picked OUT.
+    fireEvent.click(screen.getByText('Reveal key'))
+    expect(screen.getAllByText(/FLAT \(decoy\)/)).toHaveLength(2)
+  })
+
+  it('pairs the smooth banding control with a hand-quantised reference', () => {
+    // Run 1 was VOID because nothing could band. Run 2 then found the smooth
+    // control ALSO reading clean, which is ambiguous: a blind panel and a render
+    // path that simply does not band both look like "no steps". The hard-edged
+    // reference disambiguates them, so the panel needs BOTH gradients — and
+    // neither may be one of the shipped-material fields.
+    const { container } = render(<Banding />)
+    expect(container.querySelectorAll('[style*="linear-gradient"]')).toHaveLength(2)
+  })
+
+  it('labels the control and the reference distinctly, and only on reveal', () => {
+    render(<Banding />)
+    expect(screen.queryByText(/CONTROL/)).toBeNull()
+    expect(screen.queryByText(/REFERENCE/)).toBeNull()
+
+    fireEvent.click(screen.getByText('Reveal key'))
+    expect(screen.getAllByText(/CONTROL/)).toHaveLength(1)
+    expect(screen.getAllByText(/REFERENCE/)).toHaveLength(1)
+  })
+
+  it('seeds a no-floor-line decoy among the inset wells', () => {
+    render(<PaperMaterial />)
+    expect(screen.queryByText(/NONE \(decoy\)/)).toBeNull()
+
+    fireEvent.click(screen.getByText('Reveal key'))
+    expect(screen.getAllByText(/NONE \(decoy\)/)).toHaveLength(1)
+  })
+
+  it('seeds an identical pair among the tone-step pairs', () => {
+    render(<ToneSteps />)
+    expect(screen.queryByText(/SAME \(decoy\)/)).toBeNull()
+
+    fireEvent.click(screen.getByText('Reveal key'))
+    expect(screen.getAllByText(/SAME \(decoy\)/)).toHaveLength(1)
+  })
+})

package/src/theme/elevation.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { getGlowShadow } from './elevation'
+import { getGlowShadow, getElevationSurface, getElevationShadow, getBaseSurfaceColor, FLOATING_ELEVATION_MIN } from './elevation'
 
 describe('getGlowShadow', () => {
   it('returns shadow style for valid hex color', () => {
@@ -25,3 +25,64 @@ describe('getGlowShadow', () => {
     expect(defaultStyle).toEqual(mediumStyle)
   })
 })
+
+// ── TD-07.16: the depth model ───────────────────────────────────────────────
+
+describe('elevation depth model', () => {
+  const hex2rgb = (h: string): [number, number, number] => {
+    const n = parseInt(h.slice(1), 16)
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+  }
+  const srgb2lin = (c: number) => {
+    const s = c / 255
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+  }
+  const fl = (t: number) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116)
+  const Lstar = (hex: string) => {
+    const [r, g, b] = hex2rgb(hex).map(srgb2lin)
+    return 116 * fl(r * 0.2126729 + g * 0.7151522 + b * 0.072175) - 16
+  }
+
+  const base = getBaseSurfaceColor('dark')
+
+  /**
+   * With drop-shadow gated off below FLOATING_ELEVATION_MIN, TONE is the only
+   * thing separating levels 0-3. Level 1 previously moved 0.01 (~2 RGB), which
+   * is under the perceptual floor — so the level existed in the type system and
+   * nowhere on screen.
+   */
+  it('separates every adjacent content level by a visible tonal step', () => {
+    const levels = [0, 1, 2, 3] as const
+    for (let i = 1; i < levels.length; i++) {
+      const prev = Lstar(getElevationSurface(base, levels[i - 1], 'dark'))
+      const cur = Lstar(getElevationSurface(base, levels[i], 'dark'))
+      const step = cur - prev
+      expect(step, `L${levels[i - 1]}→L${levels[i]} moves ΔL* ${step.toFixed(2)}`).toBeGreaterThan(1)
+    }
+  })
+
+  it('gets lighter as it rises, never darker', () => {
+    const ls = ([0, 1, 2, 3, 4, 5] as const).map((lv) => Lstar(getElevationSurface(base, lv, 'dark')))
+    for (let i = 1; i < ls.length; i++) expect(ls[i]).toBeGreaterThan(ls[i - 1])
+  })
+
+  it('casts NO outward shadow below the floating threshold', () => {
+    // Dark-on-dark drop shadows are inert — they cost a composite layer and
+    // show nothing. Inline hierarchy is the hairline's job.
+    for (const lv of [1, 2, 3] as const) {
+      expect(getElevationShadow(base, lv, 'dark'), `level ${lv}`).toEqual({})
+    }
+  })
+
+  it('does cast one at and above the floating threshold', () => {
+    for (const lv of [FLOATING_ELEVATION_MIN, 5] as const) {
+      expect(Object.keys(getElevationShadow(base, lv, 'dark')).length, `level ${lv}`).toBeGreaterThan(0)
+    }
+  })
+
+  it('keeps the recess on inset levels — a well is not a cast shadow', () => {
+    for (const lv of [-1, -2] as const) {
+      expect(Object.keys(getElevationShadow(base, lv, 'dark')).length, `level ${lv}`).toBeGreaterThan(0)
+    }
+  })
+})

package/src/theme/elevation.ts

@@ -22,7 +22,7 @@
  */
 
 import { Platform, type ViewStyle } from 'react-native'
-import { lighten, darken, hexToRgb, rgbToHsv, hsvToRgb, rgbToHex } from './shadows'
+import { lighten, darken, hexToRgb, rgbToHsv, hsvToRgb, rgbToHex } from './color-utils'
 import { semanticColorsLight, semanticColorsDark } from './tokens/semantic'
 
 export type ElevationLevel = -2 | -1 | 0 | 1 | 2 | 3 | 4 | 5
@@ -71,7 +71,13 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
   // Level 1: Subtle elevation (outline cards, subtle containers)
   [1]: {
     name: 'subtle',
-    colorAdjustment: 0.01,
+    // The whole ladder was re-spaced in TD-07.16. It used to run
+    // 0.01/0.02/0.04/0.06/0.08, where the first step was ~2 RGB values — under
+    // the perceptual floor, so level 1 existed in the type system and nowhere on
+    // screen. With drop-shadow now gated off below FLOATING_ELEVATION_MIN, TONE
+    // is the only thing separating 0-3, so every step has to actually land.
+    // Even 0.025 spacing, verified in elevation.test.ts as ΔL* > 1 per step.
+    colorAdjustment: 0.025,
     shadowIntensity: 'subtle',
     shadowStyle: 'raised',
     description: 'Subtle elevation (outline cards, subtle containers)',
@@ -80,7 +86,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
   // Level 2: Standard elevation (default cards, buttons)
   [2]: {
     name: 'standard',
-    colorAdjustment: 0.02,
+    colorAdjustment: 0.05,
     shadowIntensity: 'medium',
     shadowStyle: 'raised',
     description: 'Standard elevation (default cards, raised buttons)',
@@ -89,7 +95,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
   // Level 3: Prominent elevation (important cards, modals)
   [3]: {
     name: 'prominent',
-    colorAdjustment: 0.04,
+    colorAdjustment: 0.075,
     shadowIntensity: 'strong',
     shadowStyle: 'raised',
     description: 'Prominent elevation (important cards, modals, dropdowns)',
@@ -98,7 +104,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
   // Level 4: High elevation (overlays, popovers)
   [4]: {
     name: 'high',
-    colorAdjustment: 0.06,
+    colorAdjustment: 0.10,
     shadowIntensity: 'strong',
     shadowStyle: 'raised',
     description: 'High elevation (overlays, popovers, tooltips)',
@@ -107,7 +113,7 @@ export const elevationSystem: Record<ElevationLevel, ElevationConfig> = {
   // Level 5: Floating (toasts, floating action buttons)
   [5]: {
     name: 'floating',
-    colorAdjustment: 0.08,
+    colorAdjustment: 0.13,
     shadowIntensity: 'strong',
     shadowStyle: 'raised',
     description: 'Floating elevation (toasts, floating action buttons, highest z-index)',
@@ -425,6 +431,21 @@ function calculateElevationShadow(
  * @param isHovered - Whether element is hovered
  * @returns ViewStyle with shadow properties
  */
+/**
+ * The lowest elevation that still casts an outward shadow.
+ *
+ * On a near-black surface a drop-shadow is inert: at levels 1-3 the shadow is
+ * dark-on-dark and contributes nothing a viewer can see, while still costing a
+ * composite layer. Material dropped shadow-as-hierarchy for the same reason.
+ * Inline hierarchy is the hairline's job (`hairline-*`), which composites by a
+ * constant amount over any plane.
+ *
+ * At 4+ the element is genuinely FLOATING over a backdrop — menu, popover,
+ * toast — where a large soft shadow describes separation from the page rather
+ * than a rank in a stack. Those should also carry a hairline ring.
+ */
+export const FLOATING_ELEVATION_MIN: ElevationLevel = 4
+
 export function getElevationShadow(
   baseColor: string,
   level: ElevationLevel,
@@ -438,8 +459,13 @@ export function getElevationShadow(
     return elevationShadowCache.get(cacheKey)!
   }
 
-  // Calculate shadow
-  const result = calculateElevationShadow(baseColor, level, theme, isHovered)
+  // Calculate shadow. Outward drop-shadow is gated to FLOATING levels only —
+  // see FLOATING_ELEVATION_MIN. Inset levels keep theirs; a recess reads from
+  // the inner shadow, which is a different mechanism from a cast shadow.
+  const result =
+    level > 0 && level < FLOATING_ELEVATION_MIN
+      ? {}
+      : calculateElevationShadow(baseColor, level, theme, isHovered)
 
   // Cache result
   if (elevationShadowCache.size >= MAX_SHADOW_CACHE_SIZE) {