@titan-design/react-ui 0.10.0 → 0.12.0

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

package/src/theme/global.css

@@ -41,12 +41,12 @@
     --color-status-error-light: #E05254;
     --color-status-error-dark: #A4221C;
     --color-status-error-subtle: rgba(209, 67, 67, 0.12);
-    --color-status-error-vivid: #FF4757;
-    --color-status-error-vivid-light: #FF6070;
-    --color-status-error-vivid-dark: #C42539;
+    --color-status-error-vivid: #D14343;
+    --color-status-error-vivid-light: #E05254;
+    --color-status-error-vivid-dark: #A4221C;
     --color-status-error-vivid-subtle: rgba(255, 71, 87, 0.12);
     --color-status-error-vivid-rgb: 255, 71, 87;
-    --color-border-prominent: #3C3C3C;
+    --color-border-prominent: #424140;
     --color-status-warning: #F9B415;
     --color-status-warning-light: #FFD352;
     --color-status-warning-dark: #C27400;
@@ -69,7 +69,7 @@
     --color-result-degrade-dark: #b30000;
     --color-result-inconclusive: #9E9A97;
     --color-result-inconclusive-light: rgba(158, 154, 151, 0.16);
-    --color-result-neutral: #9CA3AF;
+    --color-result-neutral: #A29F9D;
 
     --color-on-result-improve: #FFFFFF;
     --color-on-result-degrade: #FFFFFF;
@@ -86,25 +86,24 @@
     --color-data-9: #CAACCB;
     --color-data-10: #EE8026;
 
-    --color-text-primary: #F3F4F6;
-    --color-text-secondary: #9CA3AF;
-    --color-text-tertiary: #6B7280;
+    --color-text-primary: #F9F6F3;
+    --color-text-secondary: #A29F9D;
+    --color-text-tertiary: #888684;
     --color-text-disabled: rgba(255, 255, 255, 0.38);
-    --color-text-inverse: #111827;
+    --color-text-inverse: #1C1916;
     --color-text-link: #828DF8;
-    --color-text-link-hover: #60A5FA;
+    --color-text-link-hover: #3CA8FF;
 
     /* 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). */
+       tokens/primitives.ts. The ramp's floor is background-frame; the old
+       surface-inset plane was retired in TD-07.14 (delta-E 1.10 from frame). */
     --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;
@@ -114,19 +113,20 @@
        in tokens/primitives.ts. */
     --color-background-frame: #100D0A;
 
-    --color-border-default: #1F1F1F;
-    --color-border-subtle: #1C1C1C;
-    --color-border-strong: #2C2C2C;
     --color-border-focus: #828DF8;
-    --color-border-input: #4B5563;
-    --color-border-input-hover: #6B7280;
+    --color-border-input: #5A5958;
+    --color-border-input-hover: #72716F;
     --color-border-input-focus: #828DF8;
-    --color-border-input-error: #EF4444;
+    --color-border-input-error: #E05254;
 
-    /* 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);
+    /* Alpha hairline separators — self-normalizing on any plane (§4/S-2).
+       Retuned on the wall (VW-99): each tier steps onto the previous tier's
+       measured-good value, then +.01 across the family on run 2 for comfort.
+       Two decimals only — RNW quantises alpha to 8 bits.
+       Dark only; the light family below is unverified. */
+    --color-hairline-subtle: rgba(255, 255, 255, 0.10);
+    --color-hairline-default: rgba(255, 255, 255, 0.15);
+    --color-hairline-strong: rgba(255, 255, 255, 0.22);
 
     --color-interactive-hover: rgba(255, 255, 255, 0.04);
     --color-interactive-focus: rgba(255, 255, 255, 0.12);
@@ -135,9 +135,9 @@
     --color-interactive-disabled: rgba(255, 255, 255, 0.12);
     --color-interactive-disabled-text: rgba(255, 255, 255, 0.26);
 
-    --color-divider: #1F1F1F;
+    --color-divider: rgba(255, 255, 255, 0.09);
 
-    --color-avatar-background: #4B5563;
+    --color-avatar-background: #5A5958;
     --color-avatar-text: #FFFFFF;
 
     /* RGB decomposed values for glow shadows */
@@ -193,12 +193,12 @@
     --color-status-error-light: #E05254;
     --color-status-error-dark: #A4221C;
     --color-status-error-subtle: #FFF4F4;
-    --color-status-error-vivid: #FF4757;
-    --color-status-error-vivid-light: #FF6070;
-    --color-status-error-vivid-dark: #C42539;
+    --color-status-error-vivid: #D14343;
+    --color-status-error-vivid-light: #E05254;
+    --color-status-error-vivid-dark: #A4221C;
     --color-status-error-vivid-subtle: rgba(255, 71, 87, 0.12);
     --color-status-error-vivid-rgb: 255, 71, 87;
-    --color-border-prominent: #9CA3AF;
+    --color-border-prominent: #A29F9D;
     --color-status-warning: #F9B415;
     --color-status-warning-light: #FFD352;
     --color-status-warning-dark: #C27400;
@@ -221,7 +221,7 @@
     --color-result-degrade-dark: #b30000;
     --color-result-inconclusive: #9E9A97;
     --color-result-inconclusive-light: rgba(158, 154, 151, 0.12);
-    --color-result-neutral: #6B7280;
+    --color-result-neutral: #72716F;
 
     --color-on-result-improve: #FFFFFF;
     --color-on-result-degrade: #FFFFFF;
@@ -240,34 +240,28 @@
 
     --color-text-primary: #121828;
     --color-text-secondary: #65748B;
-    --color-text-tertiary: #9CA3AF;
+    --color-text-tertiary: #A29F9D;
     --color-text-disabled: rgba(55, 65, 81, 0.48);
     --color-text-inverse: #FFFFFF;
-    --color-text-link: #5048E5;
-    --color-text-link-hover: #3832A0;
+    --color-text-link: #1072CB;
+    --color-text-link-hover: #135AA8;
 
     --color-surface-base: #FFFFFF;
-    --color-surface-elevated: #FAFAFA;
-    --color-surface-raised: #F3F4F6;
+    --color-surface-elevated: #F9F6F3;
+    --color-surface-raised: #EDEAE7;
     --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-surface-input: #F9F6F3;
 
     --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;
-    --color-border-strong: #D1D5DB;
-    --color-border-focus: #5048E5;
-    --color-border-input: #D1D5DB;
-    --color-border-input-hover: #9CA3AF;
-    --color-border-input-focus: #5048E5;
+    --color-background-subtle: #F9F6F3;
+    /* Placeholder pairing — light mode is deferred. */
+    --color-background-frame: #A29F9D;
+
+    --color-border-focus: #1072CB;
+    --color-border-input: #D4D1CE;
+    --color-border-input-hover: #A29F9D;
+    --color-border-input-focus: #1072CB;
     --color-border-input-error: #D14343;
 
     /* Alpha hairline separators — mirrors the dark-mode white-alpha family,
@@ -285,7 +279,7 @@
 
     --color-divider: #E8E9EB;
 
-    --color-avatar-background: #6B7280;
+    --color-avatar-background: #72716F;
     --color-avatar-text: #FFFFFF;
 
     /* RGB decomposed values for glow shadows */
@@ -349,7 +343,7 @@
   }
 
   .scrollbar-styled::-webkit-scrollbar-thumb {
-    background: var(--color-border-strong);
+    background: var(--color-hairline-strong);
     border-radius: 4px;
   }
 
@@ -368,7 +362,7 @@
   }
 
   .scrollbar-thin::-webkit-scrollbar-thumb {
-    background: var(--color-border-strong);
+    background: var(--color-hairline-strong);
     border-radius: 2px;
   }
 

package/src/theme/grey-ramp.test.ts

@@ -0,0 +1,166 @@
+/**
+ * TD-07.14 / TD-07.15 — the warm grey ramp, and the gate it had to clear.
+ *
+ * This ramp was lost and re-derived four times before it was committed, so these
+ * tests exist to make the properties that were argued about EXPENSIVE to break,
+ * rather than leaving them in a document nobody reads. Each block corresponds to
+ * a decision someone had to make twice.
+ */
+import { describe, it, expect } from 'vitest'
+import { execFileSync } from 'node:child_process'
+import { join } from 'node:path'
+import { greyRamp, SURFACE_PLANE_STEPS, primitiveRamps } from './tokens/primitives'
+
+
+// ── colour math (CIELAB D65 + WCAG relative luminance) ──────────────────────
+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 f = (t: number) => (t > 216 / 24389 ? Math.cbrt(t) : (841 / 108) * t + 4 / 29)
+function lab(hex: string): [number, number, number] {
+  const [r, g, b] = hex2rgb(hex).map(srgb2lin)
+  const X = (0.4124564 * r + 0.3575761 * g + 0.1804375 * b) / 0.95047
+  const Y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b
+  const Z = (0.0193339 * r + 0.119192 * g + 0.9503041 * b) / 1.08883
+  const [fx, fy, fz] = [f(X), f(Y), f(Z)]
+  return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)]
+}
+const dE76 = (a: string, b: string) => {
+  const [p, q] = [lab(a), lab(b)]
+  return Math.hypot(p[0] - q[0], p[1] - q[1], p[2] - q[2])
+}
+const Lstar = (hex: string) => lab(hex)[0]
+const warmth = (hex: string) => {
+  const [r, , b] = hex2rgb(hex)
+  return r - b
+}
+
+/** Machado-2009 dichromacy, severity 1.0. */
+const CVD = {
+  deuteranopia: [0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.01182, 0.04294, 0.968881],
+  protanopia: [0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998],
+  tritanopia: [1.255528, -0.076749, -0.178779, -0.078411, 0.930809, 0.147602, 0.004733, 0.691367, 0.3039],
+} as const
+function simulateCvd(m: readonly number[], hex: string): string {
+  const [r, g, b] = hex2rgb(hex)
+  const out = [
+    m[0] * r + m[1] * g + m[2] * b,
+    m[3] * r + m[4] * g + m[5] * b,
+    m[6] * r + m[7] * g + m[8] * b,
+  ]
+  return (
+    '#' +
+    out
+      .map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, '0'))
+      .join('')
+      .toUpperCase()
+  )
+}
+
+const STEPS = Object.keys(greyRamp).map(Number).sort((a, b) => a - b)
+const hexAt = (step: number) => greyRamp[step as keyof typeof greyRamp]
+
+describe('greyRamp — shape', () => {
+  it('is monotonically darker as the step number rises', () => {
+    const ls = STEPS.map((s) => Lstar(hexAt(s)))
+    for (let i = 1; i < ls.length; i++) {
+      expect(ls[i], `step ${STEPS[i]} is not darker than ${STEPS[i - 1]}`).toBeLessThan(ls[i - 1])
+    }
+  })
+
+  it('reads warm at every step — R−B never drops below the +2 the generator guards', () => {
+    for (const s of STEPS) {
+      expect(warmth(hexAt(s)), `step ${s} (${hexAt(s)}) is not warm`).toBeGreaterThanOrEqual(2)
+    }
+  })
+
+  it('has no two steps a reader could not tell apart', () => {
+    for (let i = 1; i < STEPS.length; i++) {
+      const d = dE76(hexAt(STEPS[i - 1]), hexAt(STEPS[i]))
+      expect(d, `steps ${STEPS[i - 1]}/${STEPS[i]} collapse at ΔE ${d.toFixed(2)}`).toBeGreaterThan(1.5)
+    }
+  })
+
+  /**
+   * The reason `975` exists at all. If a chromatic ramp is ever re-tuned so its
+   * darkest step drops below the bezel, the justification for the extra step
+   * evaporates and this ramp should be renumbered rather than left as folklore.
+   */
+  it('extends below the chromatic grid — which is why 975 is not 950', () => {
+    const floor = [...Object.values(primitiveRamps)]
+      .map((r) => Lstar(r[950 as keyof typeof r] as string))
+      .sort((a, b) => a - b)
+    const median = floor[Math.floor(floor.length / 2)]
+    expect(Lstar(greyRamp[975])).toBeLessThan(median)
+    expect(median).toBeCloseTo(10.3, 0)
+  })
+})
+
+describe('greyRamp — anchors are load-bearing', () => {
+  /**
+   * These six are byte-identical to the values that shipped in v0.10.0 as
+   * `surfaceRampDark` + `backgroundFrameDark`. That is what makes TD-07.14 a
+   * rename rather than a restyle: every surface keeps its exact pixel value.
+   * Changing one here silently restyles every surface in the system.
+   */
+  const ANCHORS: Array<[keyof typeof greyRamp, string, string]> = [
+    [850, '#373635', 'surface overlay'],
+    [875, '#31302F', 'surface raised'],
+    [900, '#2C2A28', 'surface elevated'],
+    [925, '#252321', 'surface base'],
+    [950, '#1C1916', 'background base'],
+    [975, '#100D0A', 'background frame / bezel'],
+  ]
+
+  it.each(ANCHORS)('step %s is %s (%s) — unchanged from v0.10.0', (step, hex) => {
+    expect(greyRamp[step]).toBe(hex)
+  })
+
+  it('maps every surface plane to a real step, darkest first', () => {
+    const steps = Object.values(SURFACE_PLANE_STEPS)
+    for (const s of steps) expect(greyRamp[s]).toBeDefined()
+    expect([...steps].sort((a, b) => b - a)).toEqual(steps)
+  })
+
+  it('has no `inset` — it was retired for being imperceptible from the frame', () => {
+    // The reason, kept as an assertion so nobody reintroduces it: the old inset
+    // #13100D sat ΔE 1.10 from the bezel, well under the ~2.3 JND.
+    expect(dE76('#13100D', greyRamp[975])).toBeLessThan(2.3)
+    expect(Object.keys(greyRamp)).not.toContain('inset')
+  })
+})
+
+describe('greyRamp — accessibility gate (TD-07.15)', () => {
+  // NOTE: the on-surface TEXT-pairing gate lives in `semantic-contrast.test.ts`,
+  // added with the token repoint. It cannot pass until the text tokens actually
+  // move onto this ramp — on the shipped cool `neutral` scale, text-tertiary
+  // fails WCAG outright on the three lightest planes (2.96 / 2.72 / 2.49).
+
+  it('stays legible under all three dichromacies', () => {
+    for (const [mode, matrix] of Object.entries(CVD)) {
+      for (const s of STEPS) {
+        const shift = dE76(hexAt(s), simulateCvd(matrix, hexAt(s)))
+        expect(shift, `${mode} shifts grey-${s} by ΔE ${shift.toFixed(2)}`).toBeLessThan(3)
+      }
+      // Adjacent steps must stay separable AFTER simulation, or the depth
+      // ordering of the surface stack stops reading for those viewers.
+      for (let i = 1; i < STEPS.length; i++) {
+        const d = dE76(simulateCvd(matrix, hexAt(STEPS[i - 1])), simulateCvd(matrix, hexAt(STEPS[i])))
+        expect(d, `${mode}: grey-${STEPS[i - 1]}/${STEPS[i]} merge`).toBeGreaterThan(1.5)
+      }
+    }
+  })
+})
+
+describe('greyRamp — provenance', () => {
+  it('still matches the generator that derived it', () => {
+    const script = join(__dirname, '../../scripts/generate-grey-ramp.mjs')
+    // Throws (non-zero exit) if primitives.ts has drifted from the derivation.
+    expect(() => execFileSync('node', [script, '--check'], { encoding: 'utf8' })).not.toThrow()
+  })
+})

package/src/theme/materials.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Surface materials — the properties that make paper read as ONE material.
+ *
+ * These treatments are subtle by design (grain is a whisper at dark tones, the
+ * rim is one pixel), which makes them exactly the kind of thing that can be
+ * broken without anyone noticing until it looks wrong on the wall. So the
+ * numbers that define them are asserted rather than left as comments.
+ *
+ * The `tonal fill` and `dither` blocks that used to lead this file went with
+ * `tonalFill` and `ditherTile` in VW-99: the wall found the ΔL* 3 gradient
+ * indiscernible, and then found that this render path does not band at all, so
+ * the anti-banding layer was mitigating nothing. See the materials.ts header.
+ */
+import { describe, it, expect } from 'vitest'
+import { grainOpacityForTone, grainForTone, paperSheet, insetWell, barPaper } from './materials'
+import { greyRamp } from './tokens/primitives'
+
+const styleOf = (s: Record<string, unknown>) => s as { backgroundImage?: string; boxShadow?: string; backgroundColor?: string }
+
+describe('grain', () => {
+  it('scales opacity with the tone it sits on', () => {
+    // A fixed opacity reads hot on a dark plane and vanishes on a bright one.
+    const dark = grainOpacityForTone(greyRamp[975])
+    const mid = grainOpacityForTone(greyRamp[500])
+    const light = grainOpacityForTone(greyRamp[200])
+    expect(dark).toBeLessThan(mid)
+    expect(mid).toBeLessThan(light)
+  })
+
+  it('stays inside the band where grain reads matte rather than dirty', () => {
+    for (const step of Object.keys(greyRamp).map(Number)) {
+      const op = grainOpacityForTone(greyRamp[step as keyof typeof greyRamp])
+      expect(op, `grey-${step}`).toBeGreaterThanOrEqual(0.04)
+      expect(op, `grey-${step}`).toBeLessThanOrEqual(0.24)
+    }
+  })
+
+  it('survives malformed input instead of emitting NaN into a style', () => {
+    expect(grainOpacityForTone('not-a-colour')).toBeGreaterThan(0)
+    expect(grainForTone('not-a-colour')).not.toContain('NaN')
+  })
+})
+
+describe('paperSheet', () => {
+  it('carries grain ALONE — no dither, no gradient', () => {
+    const bg = styleOf(paperSheet(greyRamp[875])).backgroundImage!
+    // Count data URIs, not 'url(' — each SVG tile contains a `filter='url(#n)'`
+    // internally, so counting the token double-reports.
+    //
+    // Both of the layers this used to have were measured off the sheet in VW-99:
+    // the tonal fill was indiscernible from flat, and the dither was mitigating
+    // a banding artefact that a hand-drawn reference proved this render path
+    // does not produce. Asserted rather than merely deleted, so putting either
+    // back is a deliberate act with a wall run behind it, not a quiet revert.
+    expect(bg.split('data:image/svg+xml').length - 1, 'grain only, no dither tile').toBe(1)
+    expect(bg, 'the tonal fill was removed in VW-99').not.toContain('linear-gradient')
+  })
+
+  it('keeps a solid backgroundColor so native does not fall through', () => {
+    // backgroundImage and multi-layer boxShadow are web-only. Without a real
+    // fill underneath, a paper surface renders as nothing on native.
+    expect(styleOf(paperSheet(greyRamp[875])).backgroundColor).toBe(greyRamp[875])
+  })
+
+  it('carries a top rim and one soft contact shadow', () => {
+    const shadow = styleOf(paperSheet()).boxShadow!
+    expect(shadow).toContain('inset 0 1px 0')
+    expect(shadow.split(',').filter((s) => s.includes('px')).length).toBeGreaterThan(1)
+  })
+})
+
+describe('insetWell', () => {
+  it('cuts in from the top AND lights the floor', () => {
+    // The floor rim is the load-bearing half — a dark inset alone just reads as
+    // a darker rectangle. It is the light on the floor that says "below".
+    const shadow = styleOf(insetWell(greyRamp[950])).boxShadow!
+    expect(shadow).toContain('inset 0 2px')
+    expect(shadow, 'missing the bottom floor rim').toContain('inset 0 -1px 0 rgba(255,255,255,0.12)')
+  })
+
+  it('is entirely inset — a well must not cast outward', () => {
+    const shadow = styleOf(insetWell()).boxShadow!
+    for (const layer of shadow.split(/,(?![^(]*\))/)) {
+      expect(layer.trim().startsWith('inset'), `outward layer: ${layer.trim()}`).toBe(true)
+    }
+  })
+})
+
+describe('barPaper', () => {
+  it('drops the rim light when mirrored', () => {
+    // Mirrored, a top rim would land on the shared axis of a diverging chart.
+    expect(styleOf(barPaper('#D14343', true)).boxShadow).not.toContain('inset')
+    expect(styleOf(barPaper('#D14343', false)).boxShadow).toContain('inset')
+  })
+
+  it('throws its contact shadow away from the axis when mirrored', () => {
+    expect(styleOf(barPaper('#D14343', true)).boxShadow).toContain('0 -6px')
+    expect(styleOf(barPaper('#D14343', false)).boxShadow).toContain('0 6px')
+  })
+
+  it('shares the one grain curve with paperSheet', () => {
+    // Same material, proportional texture — that is what makes a card and a bar
+    // look like they belong to the same system.
+    expect(styleOf(barPaper(greyRamp[500])).backgroundImage).toBe(grainForTone(greyRamp[500]))
+  })
+})