@titan-design/react-ui 0.11.0 → 0.12.1

package/src/theme/materials.ts

@@ -0,0 +1,211 @@
+/**
+ * Surface MATERIALS — the treatments layered on top of the flat grey ramp.
+ *
+ * The ramp says how deep a plane sits. This says what it is made of. Two
+ * materials, deliberately: a matte PAPER sheet for hero surfaces, and a recessed
+ * INSET WELL for grouped or awaiting-data regions.
+ *
+ * SCOPE, and it is a hard rule rather than a preference: paper goes on hero
+ * surfaces only — the live card, the LOAD/verdict chip, the rest hero. The
+ * "everything is a paper card" look is explicitly NOT the model; it was an
+ * over-application built to find the ceiling. There are no LEVELS of paper. One
+ * treatment, used sparingly, or the texture stops meaning anything.
+ *
+ * Second hard rule: paper fills take DEEP/MUTED tones only (a ramp step, or a
+ * categorical `dark` variant). Vivid and neon colours are ink ON paper — never
+ * the paper itself.
+ *
+ * PLATFORM: `backgroundImage` and multi-layer `boxShadow` are web/RNW only. On
+ * native these are ignored and the surface falls back to its flat fill, which is
+ * why every material here keeps `backgroundColor` load-bearing on its own. A
+ * material must never be the only thing carrying meaning.
+ *
+ * ── THE TONAL FILL IS GONE (VW-99, S-6 wall calibration) ───────────────────
+ *
+ * `paperSheet` used to carry a vertical ΔL* 3 gradient, sized "just under seen
+ * as a gradient". On the wall panel at ~3 m it could not be told from a flat
+ * sheet of the same tone, and the full material still read as — the operator's
+ * words — "a flat digital rectangle". It failed its own stated purpose, which
+ * was precisely to stop that.
+ *
+ * Raising it was not available. The design ceiling is ~ΔL* 4 (past that it reads
+ * decorative, which the exploration rejected), and the same run showed why the
+ * headroom would not have helped: the 0.025 ELEVATION step — a comparable ΔL*
+ * — was called instantly, because it sits at a hard edge between two flat
+ * fields. The fill spread the same amount smoothly over ~300 px, where vision is
+ * genuinely poor. It is a spatial-frequency problem, not an amplitude one, so
+ * the band between "invisible" and "decorative" may simply not exist here.
+ *
+ * ── AND THE DITHER WENT WITH IT (VW-99 run 2) ──────────────────────────────
+ *
+ * `ditherTile` was held back one run on the grounds that "probably dead weight"
+ * is not a measurement. Run 1 could not measure it: with the fill invisible
+ * there was no gradient to band, so the panel returned a guaranteed clean sheet.
+ *
+ * Run 2 settled it by adding a hand-quantised REFERENCE beside the smooth
+ * control — the same tone span drawn as five hard-edged 1-level steps, which is
+ * what the artefact looks like when it happens. The reference banded plainly and
+ * the smooth gradient did not. So the panel can resolve banding; this render
+ * path simply does not produce it. A mitigation for an artefact that does not
+ * occur is cost with no benefit, and it is gone.
+ *
+ * That is a claim about THIS display, which is the one the product ships on and
+ * the reason `paperSheet` is hero-surface-only. A phone is a separate question.
+ *
+ * Kept: grain, rim-light, contact shadow.
+ *
+ * See sources/design/surface-system-north-star.md §4 and
+ * sources/runbooks/VW-99-depth-wall-calibration.md.
+ */
+import type { ViewStyle } from 'react-native'
+import { getSemanticColors } from './tokens/semantic'
+
+const c = getSemanticColors('dark')
+
+// ── colour math ─────────────────────────────────────────────────────────────
+
+function parseHex(hex: string): [number, number, number] | null {
+  const h = hex.replace('#', '')
+  const full = h.length === 3 ? h.split('').map((ch) => ch + ch).join('') : h
+  const rgb: [number, number, number] = [
+    parseInt(full.slice(0, 2), 16),
+    parseInt(full.slice(2, 4), 16),
+    parseInt(full.slice(4, 6), 16),
+  ]
+  return rgb.some(Number.isNaN) ? null : rgb
+}
+
+/** sRGB perceived luminance (0 dark … 1 bright), Rec.601 weights. */
+function perceivedLuminance(hex: string): number {
+  const rgb = parseHex(hex)
+  if (!rgb) return 0.5
+  const [r, g, b] = rgb
+  return (0.299 * r + 0.587 * g + 0.114 * b) / 255
+}
+
+// The CIELAB conversion chain (srgb2lin/lin2srgb/fLab/fInv, hexToLab/labToHex,
+// shiftL) lived here so the tonal fill could be specified in ΔL*. It had no
+// other caller, so it went with the fill — see the module header.
+
+// ── grain ───────────────────────────────────────────────────────────────────
+
+/**
+ * Grain opacity for a tone, scaled by perceived brightness.
+ *
+ * A fixed opacity reads hot on a dark plane and vanishes on a bright one, so
+ * darker tones get a whisper and brighter tones keep full texture. Anchored so a
+ * dark chip (lum ≈ 0.13) lands ≈ 0.06 and a bright bar (lum ≈ 0.58) lands ≈ 0.20.
+ * Above roughly 0.05α on a mid tone it starts reading as "dirty" rather than
+ * matte, which is what the clamp is protecting.
+ *
+ * This is the ONE curve all grain goes through — a card and a bar carry
+ * proportional, not identical, texture. That is what makes them read as the same
+ * material.
+ */
+export function grainOpacityForTone(baseColor: string): number {
+  return Math.min(0.24, Math.max(0.04, 0.02 + 0.31 * perceivedLuminance(baseColor)))
+}
+
+/**
+ * The matte grain tile as a `backgroundImage` url — one shared `feTurbulence`
+ * fractal-noise tile, painted once, NEVER animated. Pair with
+ * `backgroundColor: baseColor`.
+ */
+export function grainForTone(baseColor: string): string {
+  const op = grainOpacityForTone(baseColor).toFixed(3)
+  return (
+    `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='120'%3E` +
+    `%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2' stitchTiles='stitch'/%3E%3C/filter%3E` +
+    `%3Crect width='120' height='120' filter='url(%23n)' opacity='${op}'/%3E%3C/svg%3E")`
+  )
+}
+
+// `tonalFill` and `ditherTile` both lived here until VW-99 measured them on the
+// wall. Deleted rather than left exported-but-unused; the reasoning is in the
+// module header, which is the part worth keeping.
+
+// ── the materials ───────────────────────────────────────────────────────────
+
+/**
+ * A matte PAPER hero sheet: brightness-scaled grain + a crisp top rim-light +
+ * one soft contact shadow.
+ *
+ * The contact shadow is the ONE place a drop-shadow is still correct on a dark
+ * surface: it is large, soft, and describes a sheet lying on a plane rather than
+ * trying to encode hierarchy. Inline depth is the hairline's job.
+ *
+ * Defaults to `surface-raised` so a same-toned card laid inside reads as one
+ * continuous sheet rather than a seam.
+ *
+ * THE RIM-LIGHT IS A HAIRLINE. Run 2 of VW-99 called it "weak at distance" on
+ * both the card and the hero sheet, and the reason is visible in the number: it
+ * was `rgba(255,255,255,0.10)`, a 1px white line on a dark plane — physically
+ * the same cue as `hairline-*`, but set BELOW `hairline-default`, which the same
+ * run had just had to raise twice. It is not a subtler species of edge, it was
+ * simply mistuned. Raised to `0.20`, between `hairline-default` and
+ * `hairline-strong`: this edge defines a hero surface, so it earns more than the
+ * default separator, and unlike a separator there is no fallback behind it.
+ *
+ * Deliberately NOT wired to the token, though the values now agree in spirit: a
+ * box-shadow rim and a border hairline are retuned by different evidence, and
+ * coupling them means a hairline run silently restyles every hero sheet.
+ *
+ * HERO SURFACES ONLY, MUTED TONES ONLY — see the module header.
+ */
+export function paperSheet(tone: string = c['surface-raised']): ViewStyle {
+  return {
+    backgroundColor: tone,
+    // Grain alone. The dither went with the gradient it protected — see header.
+    backgroundImage: grainForTone(tone),
+    boxShadow: 'inset 0 1px 0 rgba(255,255,255,0.20), 0 8px 22px rgba(0,0,0,0.50)',
+  } as unknown as ViewStyle
+}
+
+/**
+ * A recessed INSET WELL: a tone pressed BELOW the surrounding plane, cut in by an
+ * inner top shadow with a faint light line on the floor.
+ *
+ * The bottom rim is the load-bearing half. A dark inset alone just reads as a
+ * darker rectangle; it is the light catching the floor that says "this is below
+ * the surface" — which is why the treatment survives at 16px where a full paper
+ * treatment does not.
+ *
+ * The floor light was `0.04` and is now `0.12`, chosen on the wall in VW-99 run
+ * 2 against a `.04`-vs-`.12`-vs-none forced choice. Worth recording that `.04`
+ * was NOT invisible — the no-line decoy was correctly rejected and both real
+ * values were seen, so this is a preference between two working values, not a
+ * rescue. The rim-light next door was a genuine miss; this one was only thin.
+ *
+ * Note this is a MATERIAL, and independent of the surface LEVEL named `inset`
+ * that was retired in TD-07.14. A well is something you apply; a level is
+ * somewhere you sit.
+ */
+export function insetWell(tone: string = c['surface-input']): ViewStyle {
+  return {
+    backgroundColor: tone,
+    boxShadow: 'inset 0 2px 6px rgba(0,0,0,0.55), inset 0 -1px 0 rgba(255,255,255,0.12)',
+  } as unknown as ViewStyle
+}
+
+/**
+ * Paper for a COLORED BAR — the same material as {@link paperSheet}, tuned for a
+ * small saturated element: grain + top rim-light + a contact shadow cast past the
+ * bar's leading edge, so a filled bar reads as a physical block that has travelled.
+ *
+ * No tonal fill or dither here: a bar is too narrow for a ΔL* 3 gradient to read,
+ * and too narrow to band.
+ *
+ * `flip` = a vertically mirrored (`scaleY(-1)`) plot, i.e. the `down` wing of a
+ * diverging chart. The contact shadow's y-offset is pre-inverted so the mirror
+ * lands it pointing AWAY from the shared axis rather than up across it, and the
+ * top rim-light is DROPPED — mirrored it would sit on the axis edge and read
+ * wrong, so grain and shadow carry the material alone.
+ */
+export function barPaper(color: string, flip = false): ViewStyle {
+  return {
+    backgroundImage: grainForTone(color),
+    boxShadow: flip
+      ? '0 -6px 16px rgba(0,0,0,0.45)'
+      : 'inset 0 1.5px 0 rgba(255,255,255,0.22), 0 6px 16px rgba(0,0,0,0.45)',
+  } as unknown as ViewStyle
+}

package/src/theme/presets/audiobook.ts

@@ -49,7 +49,7 @@ export const audiobookPreset: ThemePreset = {
       'text-secondary': '#b5b3af',
       'text-tertiary': '#7a7875',
 
-      // Surfaces: warm charcoals (not pure gray)
+      // Surfaces: warm greys (not pure gray)
       'surface-base': '#101114',
       'surface-elevated': '#15171c',
       'surface-raised': '#1a1d24',
@@ -62,9 +62,9 @@ export const audiobookPreset: ThemePreset = {
       'background-subtle': '#1a1d24',
 
       // Borders
-      'border-default': 'rgba(255, 255, 255, 0.06)',
-      'border-subtle': 'rgba(255, 255, 255, 0.03)',
-      'border-strong': '#2d323d',
+      'hairline-default': 'rgba(255, 255, 255, 0.06)',
+      'hairline-subtle': 'rgba(255, 255, 255, 0.03)',
+      'hairline-strong': '#2d323d',
       'border-focus': '#d4782a',
       'border-input': '#2d323d',
       'border-input-hover': '#454c5c',

package/src/theme/presets/types.ts

@@ -28,9 +28,9 @@ export interface ThemePresetColors {
   'background-base'?: string
   'background-default'?: string
   'background-subtle'?: string
-  'border-default'?: string
-  'border-subtle'?: string
-  'border-strong'?: string
+  'hairline-default'?: string
+  'hairline-subtle'?: string
+  'hairline-strong'?: string
   'border-focus'?: string
   'divider'?: string
   [key: `${string}`]: string | undefined

package/src/theme/semantic-contrast.test.ts

@@ -0,0 +1,83 @@
+/**
+ * TD-07.15 — on-surface text contrast, as a gate rather than a document.
+ *
+ * The warm grey migration was validated for ΔE, L* and warmth long before it
+ * was validated for CONTRAST, and the contrast check is the one that found a
+ * real defect: `text-tertiary` was failing WCAG large-text on three of the six
+ * dark planes and had been for as long as the surface ramp had existed. Nobody
+ * had run the numbers because the greys "looked fine".
+ *
+ * So the numbers run in CI now. If a text token is retuned into a failure, this
+ * fails first.
+ */
+import { describe, it, expect } from 'vitest'
+import { greyRamp } from './tokens/primitives'
+import { semanticColorsDark } from './tokens/semantic'
+
+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 relLum = (hex: string) => {
+  const [r, g, b] = hex2rgb(hex).map(srgb2lin)
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+const contrast = (a: string, b: string) => {
+  const [hi, lo] = [relLum(a), relLum(b)].sort((x, y) => y - x)
+  return (hi + 0.05) / (lo + 0.05)
+}
+
+/** Every plane text can land on, darkest first. */
+const PLANES = [975, 950, 925, 900, 875, 850] as const
+
+/**
+ * Floors per role, not one blanket 4.5. `text-tertiary` is by definition the
+ * de-emphasised role — captions, units, disabled labels — so WCAG's large-text
+ * 3:1 is the honest bar for it. Holding it to 4.5 would either be a lie we
+ * suppress or a change that erases the distinction between the three roles.
+ */
+const TEXT_ROLES = [
+  { role: 'text-primary', min: 7, note: 'body copy — AAA' },
+  { role: 'text-secondary', min: 4.5, note: 'supporting copy — AA' },
+  { role: 'text-tertiary', min: 3, note: 'de-emphasised — AA large' },
+] as const
+
+describe('semantic text on the surface planes (dark)', () => {
+  for (const { role, min, note } of TEXT_ROLES) {
+    describe(`${role} (${note})`, () => {
+      it.each(PLANES)(`clears ${min}:1 on grey-%s`, (plane) => {
+        const fg = semanticColorsDark[role as keyof typeof semanticColorsDark] as string
+        const ratio = contrast(fg, greyRamp[plane])
+        expect(
+          ratio,
+          `${role} ${fg} on grey-${plane} ${greyRamp[plane]} is ${ratio.toFixed(2)}:1, needs ${min}`,
+        ).toBeGreaterThanOrEqual(min)
+      })
+    })
+  }
+
+  /**
+   * The roles must stay ORDERED as well as legible. A migration that lifted
+   * tertiary until it out-contrasted secondary would pass every check above
+   * while destroying the hierarchy the three roles exist to express.
+   */
+  it('keeps primary > secondary > tertiary in contrast on every plane', () => {
+    for (const plane of PLANES) {
+      const [pri, sec, ter] = TEXT_ROLES.map(({ role }) =>
+        contrast(semanticColorsDark[role as keyof typeof semanticColorsDark] as string, greyRamp[plane]),
+      )
+      expect(pri, `on grey-${plane}: primary ${pri.toFixed(2)} vs secondary ${sec.toFixed(2)}`).toBeGreaterThan(sec)
+      expect(sec, `on grey-${plane}: secondary ${sec.toFixed(2)} vs tertiary ${ter.toFixed(2)}`).toBeGreaterThan(ter)
+    }
+  })
+
+  // Border visibility is NOT checked here. The separators are alpha now, and a
+  // WCAG ratio needs two opaque colours — feeding `rgba(…)` to a hex parser
+  // silently yields black, so such a check passes without measuring anything.
+  // Alpha separators are validated by compositing them over each plane in
+  // `surface.contract.test.ts` (R3 for the hairlines, R4 for border-prominent).
+})

package/src/theme/token-export-guard.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Token-export guard (TP-16).
+ *
+ * `@titan-design/react-ui/theme/tokens` is the token-only subpath for consumers
+ * that are NOT react-native apps — plain web builds that want `getSemanticColors`
+ * and the primitive/semantic token maps and nothing else.
+ *
+ * The bug this guards: before TP-16 the only subpath carrying `getSemanticColors`
+ * was `./theme`, whose entry re-exports the `ThemeProvider` VALUE. That drags in
+ * nativewind -> react-native-css-interop, which ships raw JSX in a `.js` file that
+ * neither plain Node ESM nor a Vite/rollup build can parse — a web consumer just
+ * got a build failure at `react-native-css-interop/dist/doctor.js`. A type-check
+ * would never catch it, so this guard is static and structural instead.
+ *
+ * It walks the SOURCE import graph rooted at the subpath entry and asserts nothing
+ * reachable imports react, react-native, nativewind, or gluestack. Source-level
+ * (not dist-level) so it runs in the fast project with no build step.
+ */
+
+const themeDir = path.dirname(fileURLToPath(import.meta.url))
+const uiRoot = path.resolve(themeDir, '..', '..')
+
+const TOKEN_ENTRY = path.join(themeDir, 'tokens', 'index.ts')
+const FORBIDDEN = ['react', 'react-dom', 'react-native', 'react-native-web', 'nativewind']
+
+function resolveRelative(fromFile: string, specifier: string): string | null {
+  const base = path.resolve(path.dirname(fromFile), specifier)
+  for (const candidate of [`${base}.ts`, `${base}.tsx`, path.join(base, 'index.ts')]) {
+    if (fs.existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+/** Every `from '...'` specifier in a module, ignoring type-only imports (erased at build). */
+function importSpecifiers(source: string): string[] {
+  const stripped = source.replace(/^\s*(import|export)\s+type\s[^;]*;?$/gm, '')
+  const matches = stripped.matchAll(/(?:import|export)[^'"]*?from\s*['"]([^'"]+)['"]/g)
+  return [...matches].map((m) => m[1])
+}
+
+/** Walk the source import graph from `entry`, returning every reachable file + bare specifier. */
+function collectGraph(entry: string): { files: string[]; bare: string[] } {
+  const seen = new Set<string>()
+  const bare = new Set<string>()
+  const queue = [entry]
+  while (queue.length > 0) {
+    const file = queue.pop()!
+    if (seen.has(file)) continue
+    seen.add(file)
+    for (const specifier of importSpecifiers(fs.readFileSync(file, 'utf8'))) {
+      if (!specifier.startsWith('.')) {
+        bare.add(specifier)
+        continue
+      }
+      const resolved = resolveRelative(file, specifier)
+      if (resolved) queue.push(resolved)
+    }
+  }
+  return { files: [...seen], bare: [...bare] }
+}
+
+describe('token-only subpath export (TP-16)', () => {
+  it('is declared in the package exports map', () => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(uiRoot, 'package.json'), 'utf8'))
+    expect(pkg.exports['./theme/tokens']).toEqual({
+      'react-native': './src/theme/tokens/index.ts',
+      types: './dist/theme/tokens.d.ts',
+      import: './dist/theme/tokens.mjs',
+      require: './dist/theme/tokens.js',
+    })
+  })
+
+  it('has a matching tsup build entry so the dist files actually exist', () => {
+    const tsupConfig = fs.readFileSync(path.join(uiRoot, 'tsup.config.ts'), 'utf8')
+    expect(tsupConfig).toContain(`'theme/tokens': 'src/theme/tokens/index.ts'`)
+  })
+
+  it('reaches no react / react-native / nativewind module in its import graph', () => {
+    const { bare } = collectGraph(TOKEN_ENTRY)
+    const leaked = bare.filter((s) =>
+      FORBIDDEN.some((f) => s === f || s.startsWith(`${f}/`)),
+    )
+    expect(leaked).toEqual([])
+  })
+
+  it('reaches no gluestack module in its import graph', () => {
+    const { bare } = collectGraph(TOKEN_ENTRY)
+    expect(bare.filter((s) => s.includes('gluestack'))).toEqual([])
+  })
+
+  it('exports getSemanticColors returning real token values in both modes', async () => {
+    const tokens = await import('./tokens/index')
+    for (const mode of ['dark', 'light'] as const) {
+      const colors = tokens.getSemanticColors(mode)
+      expect(Object.keys(colors).length).toBeGreaterThan(0)
+      expect(colors['brand-primary']).toMatch(/^#|^rgba?\(/)
+    }
+  })
+})

package/src/theme/tokens/primitives.ts

@@ -5,124 +5,82 @@
  * and should rarely be used directly in components. Use semantic tokens instead.
  */
 
+/**
+ * Absolute colour keywords.
+ *
+ * This used to hold five scales — `blue`, `red`, `redVivid`, `neutral` and
+ * `charcoal`. All five are gone (TD-07.14): the greys folded into `greyRamp`
+ * below and the chromatics into the OKLCH `primitiveRamps`. What is left has no
+ * scale because these three are not colours you tune, they are keywords.
+ */
 export const primitiveColors = {
-  // Blue scale
-  blue: {
-    50: '#EFF6FF',
-    100: '#DBEAFE',
-    200: '#BFDBFE',
-    300: '#93C5FD',
-    400: '#60A5FA',
-    500: '#3B82F6',
-    600: '#5048E5',
-    700: '#3832A0',
-    800: '#1E40AF',
-    900: '#1E3A8A',
-  },
-
-  // Red scale
-  red: {
-    50: '#FEF2F2',
-    100: '#FEE2E2',
-    200: '#FECACA',
-    300: '#FCA5A5',
-    400: '#DA6868',
-    500: '#EF4444',
-    600: '#D14343',
-    700: '#922E2E',
-    800: '#991B1B',
-    900: '#7F1D1D',
-  },
-
-  // Vivid red scale
-  redVivid: {
-    50: '#FFECEE',
-    100: '#FFD6DB',
-    200: '#FFB3BC',
-    300: '#FF8593',
-    400: '#FF6070',
-    500: '#FF4757',
-    600: '#E63548',
-    700: '#C42539',
-    800: '#9E1C2C',
-    900: '#7A1520',
-  },
-
-  // Neutral/Gray scale
-  neutral: {
-    50: '#FAFAFA',
-    100: '#F3F4F6',
-    200: '#E5E7EB',
-    300: '#D1D5DB',
-    400: '#9CA3AF',
-    500: '#6B7280',
-    600: '#4B5563',
-    700: '#374151',
-    800: '#1F2937',
-    900: '#111827',
-    950: '#030712',
-  },
-
-  // Charcoal scale (dark backgrounds)
-  charcoal: {
-    0: '#6E6E6E',
-    50: '#5D5D5D',
-    100: '#4C4C4C',
-    200: '#3C3C3C',
-    300: '#2C2C2C',
-    400: '#1F1F1F',
-    500: '#1C1C1C',
-    600: '#191919',
-    700: '#161616',
-    800: '#131313',
-    900: '#101010',
-  },
-
-  // Pure colors
   white: '#FFFFFF',
   black: '#000000',
   transparent: 'transparent',
 } as const
 
 /**
- * Surface ramp — dark mode (TD-surface-tokens, S-1, re-spaced S-3)
+ * Unified warm-neutral grey ramp (TD-07.14)
+ *
+ * The ONE achromatic scale. Regenerate with `scripts/generate-grey-ramp.mjs` —
+ * preserve the generator, not just the hexes.
+ *
+ * The surface planes ARE steps here rather than a parallel object: `850` is
+ * overlay, `975` is the bezel. That is the whole point of the ramp. `grey`,
+ * `neutral`, `surfaceRampDark` and `backgroundFrameDark` all resolve into it,
+ * which is why every plane step below is byte-identical to the value that
+ * shipped in v0.10.0 — the surfaces do not move, only their names.
+ *
+ * TWO THINGS ABOUT THE NUMBERING, both deliberate and both previously re-derived
+ * from scratch more than once because they were never written down:
  *
- * 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.
+ * 1. `975` sits BELOW the standard grid. `canonL` — the median L* of the seven
+ *    chromatic `primitiveRamps` at each step — ends at L*10.3, which is step
+ *    `950`. The bezel is L*3.8, darker than the grid's last rung, so there is
+ *    simply no step number left for it and `975` extends past the end.
+ * 2. `850`/`875` are quarter-steps because overlay/raised/elevated are only
+ *    ~2.7 L* apart and all three collide on `900` at normal resolution. `800`
+ *    is a generated bridge between `700` (L*37.9) and overlay (L*22.7) so the
+ *    spacing stays even across the join.
+ *
+ * There is no `inset`. It was retired, not renamed: at ΔE 1.10 from `975` it was
+ * an imperceptible duplicate of the frame, which is exactly why `<Surface pressed>`
+ * (surface − 1) kept collapsing into it. `975` is the floor.
+ *
+ * Spec, generator and the rejected v1/v2 cuts:
+ * sources/design/foundations/warm-grey-ramp/
  */
-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
+export const greyRamp = {
+  50: '#F9F6F3', //  L*97.0  W6
+  100: '#EDEAE7', // L*92.8  W6
+  200: '#D4D1CE', // L*84.0  W6  — warm silver
+  300: '#BDBAB7', // L*75.7  W6
+  400: '#A29F9D', // L*65.7  W5
+  500: '#888684', // L*56.0  W4
+  600: '#72716F', // L*47.7  W3
+  700: '#5A5958', // L*37.9  W2
+  800: '#424140', // L*27.6  W2  — generated bridge
+  850: '#373635', // L*22.7  W2  — surface overlay
+  875: '#31302F', // L*19.9  W2  — surface raised
+  900: '#2C2A28', // L*17.2  W4  — surface elevated
+  925: '#252321', // L*13.9  W4  — surface base
+  950: '#1C1916', // L*9.0   W6  — background base / shell
+  975: '#100D0A', // L*3.8   W6  — background frame / bezel
 } as const
 
 /**
- * Frame/bezel primitive — dark mode (TD-surface-tokens, S-3)
+ * The surface planes, as ramp steps — the mapping `<Surface level>` resolves through.
  *
- * 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.
+ * Ordered darkest -> lightest, which is the order `pressedLevel()` walks.
  */
-export const backgroundFrameDark = '#100D0A' // L*3.79
+export const SURFACE_PLANE_STEPS = {
+  frame: 975,
+  background: 950,
+  base: 925,
+  elevated: 900,
+  raised: 875,
+  overlay: 850,
+} as const
 
 /**
  * Derived tonal ramps (TD-05.09 color foundations)
@@ -132,7 +90,7 @@ export const backgroundFrameDark = '#100D0A' // L*3.79
  * hexes. `pin` marks the step each ramp flows through its anchor.
  * This is the single source of truth for chromatic hexes — the categorical palette
  * below references these steps rather than duplicating values.
- * See coordination/design-explorations/foundations.
+ * See sources/design/foundations.
  */
 export const primitiveRamps = {
   red: {
@@ -507,17 +465,6 @@ export const primitiveBorderRadius = {
   full: '9999px',
 } as const
 
-export const primitiveShadows = {
-  none: 'none',
-  sm: '0px 1px 2px rgba(100, 116, 139, 0.12)',
-  DEFAULT: '0px 1px 3px rgba(100, 116, 139, 0.12), 0px 1px 2px rgba(100, 116, 139, 0.24)',
-  md: '0px 4px 6px rgba(100, 116, 139, 0.12)',
-  lg: '0px 10px 15px rgba(100, 116, 139, 0.12)',
-  xl: '0px 20px 25px rgba(100, 116, 139, 0.12)',
-  '2xl': '0px 25px 50px rgba(100, 116, 139, 0.25)',
-  inner: 'inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)',
-} as const
-
 export const primitiveBreakpoints = {
   xs: 0,
   sm: 600,