@titan-design/react-ui 0.10.0 → 0.12.0

package/dist/theme/index.d.ts

@@ -18,6 +18,32 @@ import { ViewStyle, ViewProps } from 'react-native';
  * - border-* : Border colors
  * - interactive-* : Hover/focus/active/disabled states
  */
+/**
+ * GREY MAPPING (TD-07.14) — how the old cool scales resolved onto `greyRamp`.
+ *
+ * Every grey below came off `grey` (pure R=G=B) or `neutral` (cool, R−B
+ * down to −26). They were snapped by NEAREST L*, not by matching step numbers,
+ * because the two old scales were numbered incompatibly: `grey` ran
+ * INVERTED and compressed (0 = #6E6E6E lightest, 900 = #101010 darkest), so
+ * `grey[400]` and `greyRamp[400]` have nothing to do with each other.
+ *
+ *   grey 200→800  300→900  400→925  500→950
+ *   neutral   50→50   100→100  300→200  400→400  500→600  600→700  900→950
+ *
+ * Surfaces move ΔE 1.9–4.8 — at or near imperceptible. The TEXT roles move
+ * further (8.6–12.8), and that is the intended part of the change: they are
+ * picking up the warmth the surfaces already had.
+ *
+ * Light gets its own column because strict L*-nearest collapsed `neutral[50]`
+ * and `[100]` onto one step, flattening surface-elevated into surface-raised.
+ * Light is still deferred as a design question — there is no `surfaceRampLight`.
+ *
+ * `border-default`, `-subtle` and `-strong` are GONE, replaced by `hairline-*`.
+ * Once the planes became ramp steps, every value dark enough to read as a
+ * border was also a plane's fill. Alpha composites instead of colliding.
+ *
+ * `text-tertiary` on dark is the one role that ignores L*-nearest; see it.
+ */
 declare const semanticColorsLight: {
     readonly 'brand-primary': "#FF7900";
     readonly 'brand-primary-light': "#FFA063";
@@ -43,9 +69,9 @@ declare const semanticColorsLight: {
     readonly 'status-error-light': "#E05254";
     readonly 'status-error-dark': "#A4221C";
     readonly 'status-error-subtle': "#FFF4F4";
-    readonly 'status-error-vivid': "#FF4757";
-    readonly 'status-error-vivid-light': "#FF6070";
-    readonly 'status-error-vivid-dark': "#C42539";
+    readonly 'status-error-vivid': "#D14343";
+    readonly 'status-error-vivid-light': "#E05254";
+    readonly 'status-error-vivid-dark': "#A4221C";
     readonly 'status-error-vivid-subtle': "rgba(255, 71, 87, 0.12)";
     readonly 'status-warning': "#F9B415";
     readonly 'status-warning-light': "#FFD352";
@@ -67,7 +93,7 @@ declare const semanticColorsLight: {
     readonly 'result-degrade-dark': "#b30000";
     readonly 'result-inconclusive': "#9E9A97";
     readonly 'result-inconclusive-light': "rgba(158, 154, 151, 0.12)";
-    readonly 'result-neutral': "#6B7280";
+    readonly 'result-neutral': "#72716F";
     readonly 'on-result-improve': "#FFFFFF";
     readonly 'on-result-degrade': "#FFFFFF";
     readonly 'on-result-inconclusive': "#FFFFFF";
@@ -83,29 +109,25 @@ declare const semanticColorsLight: {
     readonly 'data-10': "#EE8026";
     readonly 'text-primary': "#121828";
     readonly 'text-secondary': "#65748B";
-    readonly 'text-tertiary': "#9CA3AF";
+    readonly 'text-tertiary': "#A29F9D";
     readonly 'text-disabled': "rgba(55, 65, 81, 0.48)";
     readonly 'text-inverse': "#FFFFFF";
-    readonly 'text-link': "#5048E5";
-    readonly 'text-link-hover': "#3832A0";
+    readonly 'text-link': "#1072CB";
+    readonly 'text-link-hover': "#135AA8";
     readonly 'surface-base': "#FFFFFF";
-    readonly 'surface-elevated': "#FAFAFA";
-    readonly 'surface-raised': "#F3F4F6";
+    readonly 'surface-elevated': "#F9F6F3";
+    readonly 'surface-raised': "#EDEAE7";
     readonly 'surface-overlay': "#FFFFFF";
-    readonly 'surface-input': "#FAFAFA";
-    readonly 'surface-inset': "#D1D5DB";
+    readonly 'surface-input': "#F9F6F3";
     readonly 'background-base': "#EBEBEB";
     readonly 'background-default': "#FFFFFF";
-    readonly 'background-subtle': "#FAFAFA";
-    readonly 'background-frame': "#9CA3AF";
-    readonly 'border-default': "#E8E9EB";
-    readonly 'border-subtle': "#F3F4F6";
-    readonly 'border-strong': "#D1D5DB";
-    readonly 'border-prominent': "#9CA3AF";
-    readonly 'border-focus': "#5048E5";
-    readonly 'border-input': "#D1D5DB";
-    readonly 'border-input-hover': "#9CA3AF";
-    readonly 'border-input-focus': "#5048E5";
+    readonly 'background-subtle': "#F9F6F3";
+    readonly 'background-frame': "#A29F9D";
+    readonly 'border-prominent': "#A29F9D";
+    readonly 'border-focus': "#1072CB";
+    readonly 'border-input': "#D4D1CE";
+    readonly 'border-input-hover': "#A29F9D";
+    readonly 'border-input-focus': "#1072CB";
     readonly 'border-input-error': "#D14343";
     readonly 'hairline-subtle': "rgba(0, 0, 0, 0.06)";
     readonly 'hairline-default': "rgba(0, 0, 0, 0.09)";
@@ -117,7 +139,7 @@ declare const semanticColorsLight: {
     readonly 'interactive-disabled': "rgba(55, 65, 81, 0.12)";
     readonly 'interactive-disabled-text': "rgba(55, 65, 81, 0.26)";
     readonly divider: "#E8E9EB";
-    readonly 'avatar-background': "#6B7280";
+    readonly 'avatar-background': "#72716F";
     readonly 'avatar-text': "#FFFFFF";
 };
 declare const semanticColorsDark: {
@@ -145,9 +167,9 @@ declare const semanticColorsDark: {
     readonly 'status-error-light': "#E05254";
     readonly 'status-error-dark': "#A4221C";
     readonly 'status-error-subtle': "rgba(209, 67, 67, 0.12)";
-    readonly 'status-error-vivid': "#FF4757";
-    readonly 'status-error-vivid-light': "#FF6070";
-    readonly 'status-error-vivid-dark': "#C42539";
+    readonly 'status-error-vivid': "#D14343";
+    readonly 'status-error-vivid-light': "#E05254";
+    readonly 'status-error-vivid-dark': "#A4221C";
     readonly 'status-error-vivid-subtle': "rgba(255, 71, 87, 0.12)";
     readonly 'status-warning': "#F9B415";
     readonly 'status-warning-light': "#FFD352";
@@ -169,7 +191,7 @@ declare const semanticColorsDark: {
     readonly 'result-degrade-dark': "#b30000";
     readonly 'result-inconclusive': "#9E9A97";
     readonly 'result-inconclusive-light': "rgba(158, 154, 151, 0.16)";
-    readonly 'result-neutral': "#9CA3AF";
+    readonly 'result-neutral': "#A29F9D";
     readonly 'on-result-improve': "#FFFFFF";
     readonly 'on-result-degrade': "#FFFFFF";
     readonly 'on-result-inconclusive': "#FFFFFF";
@@ -183,43 +205,39 @@ declare const semanticColorsDark: {
     readonly 'data-8': "#90C987";
     readonly 'data-9': "#CAACCB";
     readonly 'data-10': "#EE8026";
-    readonly 'text-primary': "#F3F4F6";
-    readonly 'text-secondary': "#9CA3AF";
-    readonly 'text-tertiary': "#6B7280";
+    readonly 'text-primary': "#F9F6F3";
+    readonly 'text-secondary': "#A29F9D";
+    readonly 'text-tertiary': "#888684";
     readonly 'text-disabled': "rgba(255, 255, 255, 0.38)";
-    readonly 'text-inverse': "#111827";
+    readonly 'text-inverse': "#1C1916";
     readonly 'text-link': "#828DF8";
-    readonly 'text-link-hover': "#60A5FA";
+    readonly 'text-link-hover': "#3CA8FF";
     readonly 'surface-base': "#252321";
     readonly 'surface-elevated': "#2C2A28";
     readonly 'surface-raised': "#31302F";
     readonly 'surface-overlay': "#373635";
     readonly 'surface-input': "#2C2A28";
-    readonly 'surface-inset': "#13100D";
     readonly 'background-base': "#1C1916";
     readonly 'background-default': "#252321";
     readonly 'background-subtle': "#2C2A28";
     readonly 'background-frame': "#100D0A";
-    readonly 'border-default': "#1F1F1F";
-    readonly 'border-subtle': "#1C1C1C";
-    readonly 'border-strong': "#2C2C2C";
-    readonly 'border-prominent': "#3C3C3C";
+    readonly 'border-prominent': "#424140";
     readonly 'border-focus': "#828DF8";
-    readonly 'border-input': "#4B5563";
-    readonly 'border-input-hover': "#6B7280";
+    readonly 'border-input': "#5A5958";
+    readonly 'border-input-hover': "#72716F";
     readonly 'border-input-focus': "#828DF8";
-    readonly 'border-input-error': "#EF4444";
-    readonly 'hairline-subtle': "rgba(255, 255, 255, 0.06)";
-    readonly 'hairline-default': "rgba(255, 255, 255, 0.09)";
-    readonly 'hairline-strong': "rgba(255, 255, 255, 0.14)";
+    readonly 'border-input-error': "#E05254";
+    readonly 'hairline-subtle': "rgba(255, 255, 255, 0.10)";
+    readonly 'hairline-default': "rgba(255, 255, 255, 0.15)";
+    readonly 'hairline-strong': "rgba(255, 255, 255, 0.22)";
     readonly 'interactive-hover': "rgba(255, 255, 255, 0.04)";
     readonly 'interactive-focus': "rgba(255, 255, 255, 0.12)";
     readonly 'interactive-active': "rgba(255, 255, 255, 0.16)";
     readonly 'interactive-selected': "rgba(255, 255, 255, 0.08)";
     readonly 'interactive-disabled': "rgba(255, 255, 255, 0.12)";
     readonly 'interactive-disabled-text': "rgba(255, 255, 255, 0.26)";
-    readonly divider: "#1F1F1F";
-    readonly 'avatar-background': "#4B5563";
+    readonly divider: "rgba(255, 255, 255, 0.09)";
+    readonly 'avatar-background': "#5A5958";
     readonly 'avatar-text': "#FFFFFF";
 };
 declare const semanticTypography: {
@@ -347,9 +365,9 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'status-error-light': "#E05254";
     readonly 'status-error-dark': "#A4221C";
     readonly 'status-error-subtle': "#FFF4F4";
-    readonly 'status-error-vivid': "#FF4757";
-    readonly 'status-error-vivid-light': "#FF6070";
-    readonly 'status-error-vivid-dark': "#C42539";
+    readonly 'status-error-vivid': "#D14343";
+    readonly 'status-error-vivid-light': "#E05254";
+    readonly 'status-error-vivid-dark': "#A4221C";
     readonly 'status-error-vivid-subtle': "rgba(255, 71, 87, 0.12)";
     readonly 'status-warning': "#F9B415";
     readonly 'status-warning-light': "#FFD352";
@@ -371,7 +389,7 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'result-degrade-dark': "#b30000";
     readonly 'result-inconclusive': "#9E9A97";
     readonly 'result-inconclusive-light': "rgba(158, 154, 151, 0.12)";
-    readonly 'result-neutral': "#6B7280";
+    readonly 'result-neutral': "#72716F";
     readonly 'on-result-improve': "#FFFFFF";
     readonly 'on-result-degrade': "#FFFFFF";
     readonly 'on-result-inconclusive': "#FFFFFF";
@@ -387,29 +405,25 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'data-10': "#EE8026";
     readonly 'text-primary': "#121828";
     readonly 'text-secondary': "#65748B";
-    readonly 'text-tertiary': "#9CA3AF";
+    readonly 'text-tertiary': "#A29F9D";
     readonly 'text-disabled': "rgba(55, 65, 81, 0.48)";
     readonly 'text-inverse': "#FFFFFF";
-    readonly 'text-link': "#5048E5";
-    readonly 'text-link-hover': "#3832A0";
+    readonly 'text-link': "#1072CB";
+    readonly 'text-link-hover': "#135AA8";
     readonly 'surface-base': "#FFFFFF";
-    readonly 'surface-elevated': "#FAFAFA";
-    readonly 'surface-raised': "#F3F4F6";
+    readonly 'surface-elevated': "#F9F6F3";
+    readonly 'surface-raised': "#EDEAE7";
     readonly 'surface-overlay': "#FFFFFF";
-    readonly 'surface-input': "#FAFAFA";
-    readonly 'surface-inset': "#D1D5DB";
+    readonly 'surface-input': "#F9F6F3";
     readonly 'background-base': "#EBEBEB";
     readonly 'background-default': "#FFFFFF";
-    readonly 'background-subtle': "#FAFAFA";
-    readonly 'background-frame': "#9CA3AF";
-    readonly 'border-default': "#E8E9EB";
-    readonly 'border-subtle': "#F3F4F6";
-    readonly 'border-strong': "#D1D5DB";
-    readonly 'border-prominent': "#9CA3AF";
-    readonly 'border-focus': "#5048E5";
-    readonly 'border-input': "#D1D5DB";
-    readonly 'border-input-hover': "#9CA3AF";
-    readonly 'border-input-focus': "#5048E5";
+    readonly 'background-subtle': "#F9F6F3";
+    readonly 'background-frame': "#A29F9D";
+    readonly 'border-prominent': "#A29F9D";
+    readonly 'border-focus': "#1072CB";
+    readonly 'border-input': "#D4D1CE";
+    readonly 'border-input-hover': "#A29F9D";
+    readonly 'border-input-focus': "#1072CB";
     readonly 'border-input-error': "#D14343";
     readonly 'hairline-subtle': "rgba(0, 0, 0, 0.06)";
     readonly 'hairline-default': "rgba(0, 0, 0, 0.09)";
@@ -421,7 +435,7 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'interactive-disabled': "rgba(55, 65, 81, 0.12)";
     readonly 'interactive-disabled-text': "rgba(55, 65, 81, 0.26)";
     readonly divider: "#E8E9EB";
-    readonly 'avatar-background': "#6B7280";
+    readonly 'avatar-background': "#72716F";
     readonly 'avatar-text': "#FFFFFF";
 } | {
     readonly 'brand-primary': "#FF7900";
@@ -448,9 +462,9 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'status-error-light': "#E05254";
     readonly 'status-error-dark': "#A4221C";
     readonly 'status-error-subtle': "rgba(209, 67, 67, 0.12)";
-    readonly 'status-error-vivid': "#FF4757";
-    readonly 'status-error-vivid-light': "#FF6070";
-    readonly 'status-error-vivid-dark': "#C42539";
+    readonly 'status-error-vivid': "#D14343";
+    readonly 'status-error-vivid-light': "#E05254";
+    readonly 'status-error-vivid-dark': "#A4221C";
     readonly 'status-error-vivid-subtle': "rgba(255, 71, 87, 0.12)";
     readonly 'status-warning': "#F9B415";
     readonly 'status-warning-light': "#FFD352";
@@ -472,7 +486,7 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'result-degrade-dark': "#b30000";
     readonly 'result-inconclusive': "#9E9A97";
     readonly 'result-inconclusive-light': "rgba(158, 154, 151, 0.16)";
-    readonly 'result-neutral': "#9CA3AF";
+    readonly 'result-neutral': "#A29F9D";
     readonly 'on-result-improve': "#FFFFFF";
     readonly 'on-result-degrade': "#FFFFFF";
     readonly 'on-result-inconclusive': "#FFFFFF";
@@ -486,43 +500,39 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'data-8': "#90C987";
     readonly 'data-9': "#CAACCB";
     readonly 'data-10': "#EE8026";
-    readonly 'text-primary': "#F3F4F6";
-    readonly 'text-secondary': "#9CA3AF";
-    readonly 'text-tertiary': "#6B7280";
+    readonly 'text-primary': "#F9F6F3";
+    readonly 'text-secondary': "#A29F9D";
+    readonly 'text-tertiary': "#888684";
     readonly 'text-disabled': "rgba(255, 255, 255, 0.38)";
-    readonly 'text-inverse': "#111827";
+    readonly 'text-inverse': "#1C1916";
     readonly 'text-link': "#828DF8";
-    readonly 'text-link-hover': "#60A5FA";
+    readonly 'text-link-hover': "#3CA8FF";
     readonly 'surface-base': "#252321";
     readonly 'surface-elevated': "#2C2A28";
     readonly 'surface-raised': "#31302F";
     readonly 'surface-overlay': "#373635";
     readonly 'surface-input': "#2C2A28";
-    readonly 'surface-inset': "#13100D";
     readonly 'background-base': "#1C1916";
     readonly 'background-default': "#252321";
     readonly 'background-subtle': "#2C2A28";
     readonly 'background-frame': "#100D0A";
-    readonly 'border-default': "#1F1F1F";
-    readonly 'border-subtle': "#1C1C1C";
-    readonly 'border-strong': "#2C2C2C";
-    readonly 'border-prominent': "#3C3C3C";
+    readonly 'border-prominent': "#424140";
     readonly 'border-focus': "#828DF8";
-    readonly 'border-input': "#4B5563";
-    readonly 'border-input-hover': "#6B7280";
+    readonly 'border-input': "#5A5958";
+    readonly 'border-input-hover': "#72716F";
     readonly 'border-input-focus': "#828DF8";
-    readonly 'border-input-error': "#EF4444";
-    readonly 'hairline-subtle': "rgba(255, 255, 255, 0.06)";
-    readonly 'hairline-default': "rgba(255, 255, 255, 0.09)";
-    readonly 'hairline-strong': "rgba(255, 255, 255, 0.14)";
+    readonly 'border-input-error': "#E05254";
+    readonly 'hairline-subtle': "rgba(255, 255, 255, 0.10)";
+    readonly 'hairline-default': "rgba(255, 255, 255, 0.15)";
+    readonly 'hairline-strong': "rgba(255, 255, 255, 0.22)";
     readonly 'interactive-hover': "rgba(255, 255, 255, 0.04)";
     readonly 'interactive-focus': "rgba(255, 255, 255, 0.12)";
     readonly 'interactive-active': "rgba(255, 255, 255, 0.16)";
     readonly 'interactive-selected': "rgba(255, 255, 255, 0.08)";
     readonly 'interactive-disabled': "rgba(255, 255, 255, 0.12)";
     readonly 'interactive-disabled-text': "rgba(255, 255, 255, 0.26)";
-    readonly divider: "#1F1F1F";
-    readonly 'avatar-background': "#4B5563";
+    readonly divider: "rgba(255, 255, 255, 0.09)";
+    readonly 'avatar-background': "#5A5958";
     readonly 'avatar-text': "#FFFFFF";
 };
 
@@ -587,6 +597,20 @@ declare function getElevationSurface(baseColor: string, level: ElevationLevel, t
  * @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.
+ */
+declare const FLOATING_ELEVATION_MIN: ElevationLevel;
 declare function getElevationShadow(baseColor: string, level: ElevationLevel, theme: 'light' | 'dark', isHovered?: boolean): ViewStyle;
 /**
  * Elevation level backing a `<Surface pressed>` recess: the shallow `inset`
@@ -672,111 +696,80 @@ declare function getGlowShadow(color: string, intensity?: GlowIntensity): ViewSt
  * Raw values with no semantic meaning. These are the foundation of the design system
  * 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.
+ */
 declare const primitiveColors: {
-    readonly blue: {
-        readonly 50: "#EFF6FF";
-        readonly 100: "#DBEAFE";
-        readonly 200: "#BFDBFE";
-        readonly 300: "#93C5FD";
-        readonly 400: "#60A5FA";
-        readonly 500: "#3B82F6";
-        readonly 600: "#5048E5";
-        readonly 700: "#3832A0";
-        readonly 800: "#1E40AF";
-        readonly 900: "#1E3A8A";
-    };
-    readonly red: {
-        readonly 50: "#FEF2F2";
-        readonly 100: "#FEE2E2";
-        readonly 200: "#FECACA";
-        readonly 300: "#FCA5A5";
-        readonly 400: "#DA6868";
-        readonly 500: "#EF4444";
-        readonly 600: "#D14343";
-        readonly 700: "#922E2E";
-        readonly 800: "#991B1B";
-        readonly 900: "#7F1D1D";
-    };
-    readonly redVivid: {
-        readonly 50: "#FFECEE";
-        readonly 100: "#FFD6DB";
-        readonly 200: "#FFB3BC";
-        readonly 300: "#FF8593";
-        readonly 400: "#FF6070";
-        readonly 500: "#FF4757";
-        readonly 600: "#E63548";
-        readonly 700: "#C42539";
-        readonly 800: "#9E1C2C";
-        readonly 900: "#7A1520";
-    };
-    readonly neutral: {
-        readonly 50: "#FAFAFA";
-        readonly 100: "#F3F4F6";
-        readonly 200: "#E5E7EB";
-        readonly 300: "#D1D5DB";
-        readonly 400: "#9CA3AF";
-        readonly 500: "#6B7280";
-        readonly 600: "#4B5563";
-        readonly 700: "#374151";
-        readonly 800: "#1F2937";
-        readonly 900: "#111827";
-        readonly 950: "#030712";
-    };
-    readonly charcoal: {
-        readonly 0: "#6E6E6E";
-        readonly 50: "#5D5D5D";
-        readonly 100: "#4C4C4C";
-        readonly 200: "#3C3C3C";
-        readonly 300: "#2C2C2C";
-        readonly 400: "#1F1F1F";
-        readonly 500: "#1C1C1C";
-        readonly 600: "#191919";
-        readonly 700: "#161616";
-        readonly 800: "#131313";
-        readonly 900: "#101010";
-    };
     readonly white: "#FFFFFF";
     readonly black: "#000000";
     readonly transparent: "transparent";
 };
 /**
- * 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.
+ * 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:
+ *
+ * 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:
+ * coordination/design-explorations/foundations/warm-grey-ramp/
  */
-declare const surfaceRampDark: {
-    readonly inset: "#13100D";
-    readonly background: "#1C1916";
-    readonly base: "#252321";
-    readonly elevated: "#2C2A28";
-    readonly raised: "#31302F";
-    readonly overlay: "#373635";
+declare const greyRamp: {
+    readonly 50: "#F9F6F3";
+    readonly 100: "#EDEAE7";
+    readonly 200: "#D4D1CE";
+    readonly 300: "#BDBAB7";
+    readonly 400: "#A29F9D";
+    readonly 500: "#888684";
+    readonly 600: "#72716F";
+    readonly 700: "#5A5958";
+    readonly 800: "#424140";
+    readonly 850: "#373635";
+    readonly 875: "#31302F";
+    readonly 900: "#2C2A28";
+    readonly 925: "#252321";
+    readonly 950: "#1C1916";
+    readonly 975: "#100D0A";
 };
 /**
- * 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.
  */
-declare const backgroundFrameDark = "#100D0A";
+declare const SURFACE_PLANE_STEPS: {
+    readonly frame: 975;
+    readonly background: 950;
+    readonly base: 925;
+    readonly elevated: 900;
+    readonly raised: 875;
+    readonly overlay: 850;
+};
 /**
  * Derived tonal ramps (TD-05.09 color foundations)
  *
@@ -1039,16 +1032,6 @@ declare const primitiveBorderRadius: {
     readonly '2xl': "24px";
     readonly full: "9999px";
 };
-declare const primitiveShadows: {
-    readonly none: "none";
-    readonly sm: "0px 1px 2px rgba(100, 116, 139, 0.12)";
-    readonly DEFAULT: "0px 1px 3px rgba(100, 116, 139, 0.12), 0px 1px 2px rgba(100, 116, 139, 0.24)";
-    readonly md: "0px 4px 6px rgba(100, 116, 139, 0.12)";
-    readonly lg: "0px 10px 15px rgba(100, 116, 139, 0.12)";
-    readonly xl: "0px 20px 25px rgba(100, 116, 139, 0.12)";
-    readonly '2xl': "0px 25px 50px rgba(100, 116, 139, 0.25)";
-    readonly inner: "inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)";
-};
 declare const primitiveBreakpoints: {
     readonly xs: 0;
     readonly sm: 600;
@@ -1120,29 +1103,25 @@ declare const lightThemeCSSVars: {
     readonly '--color-status-warning-subtle': "#FFF7DD";
     readonly '--color-status-info': "#2196F3";
     readonly '--color-status-info-subtle': "#EFF8FF";
-    readonly '--color-status-error-vivid': "#FF4757";
-    readonly '--color-status-error-vivid-light': "#FF6070";
-    readonly '--color-status-error-vivid-dark': "#C42539";
+    readonly '--color-status-error-vivid': "#D14343";
+    readonly '--color-status-error-vivid-light': "#E05254";
+    readonly '--color-status-error-vivid-dark': "#A4221C";
     readonly '--color-status-error-vivid-subtle': "rgba(255, 71, 87, 0.12)";
     readonly '--color-text-primary': "#121828";
     readonly '--color-text-secondary': "#65748B";
-    readonly '--color-text-tertiary': "#9CA3AF";
+    readonly '--color-text-tertiary': "#A29F9D";
     readonly '--color-text-disabled': "rgba(55, 65, 81, 0.48)";
     readonly '--color-text-inverse': "#FFFFFF";
-    readonly '--color-text-link': "#5048E5";
+    readonly '--color-text-link': "#1072CB";
     readonly '--color-surface-base': "#FFFFFF";
-    readonly '--color-surface-elevated': "#FAFAFA";
-    readonly '--color-surface-raised': "#F3F4F6";
-    readonly '--color-surface-inset': "#D1D5DB";
+    readonly '--color-surface-elevated': "#F9F6F3";
+    readonly '--color-surface-raised': "#EDEAE7";
     readonly '--color-background-base': "#EBEBEB";
     readonly '--color-background-default': "#FFFFFF";
-    readonly '--color-background-subtle': "#FAFAFA";
-    readonly '--color-background-frame': "#9CA3AF";
-    readonly '--color-border-default': "#E8E9EB";
-    readonly '--color-border-subtle': "#F3F4F6";
-    readonly '--color-border-strong': "#D1D5DB";
-    readonly '--color-border-prominent': "#9CA3AF";
-    readonly '--color-border-focus': "#5048E5";
+    readonly '--color-background-subtle': "#F9F6F3";
+    readonly '--color-background-frame': "#A29F9D";
+    readonly '--color-border-prominent': "#A29F9D";
+    readonly '--color-border-focus': "#1072CB";
     readonly '--color-interactive-hover': "rgba(55, 65, 81, 0.04)";
     readonly '--color-interactive-focus': "rgba(55, 65, 81, 0.12)";
     readonly '--color-interactive-active': "rgba(55, 65, 81, 0.16)";
@@ -1173,7 +1152,7 @@ declare const lightThemeCSSVars: {
     readonly '--color-result-degrade-dark': "#b30000";
     readonly '--color-result-inconclusive': "#9E9A97";
     readonly '--color-result-inconclusive-light': "rgba(158, 154, 151, 0.12)";
-    readonly '--color-result-neutral': "#6B7280";
+    readonly '--color-result-neutral': "#72716F";
     readonly '--color-on-result-improve': "#FFFFFF";
     readonly '--color-on-result-degrade': "#FFFFFF";
     readonly '--color-on-result-inconclusive': "#FFFFFF";
@@ -1187,18 +1166,18 @@ declare const lightThemeCSSVars: {
     readonly '--color-data-8': "#90C987";
     readonly '--color-data-9': "#CAACCB";
     readonly '--color-data-10': "#EE8026";
-    readonly '--color-text-link-hover': "#3832A0";
+    readonly '--color-text-link-hover': "#135AA8";
     readonly '--color-surface-overlay': "#FFFFFF";
-    readonly '--color-surface-input': "#FAFAFA";
-    readonly '--color-border-input': "#D1D5DB";
-    readonly '--color-border-input-hover': "#9CA3AF";
-    readonly '--color-border-input-focus': "#5048E5";
+    readonly '--color-surface-input': "#F9F6F3";
+    readonly '--color-border-input': "#D4D1CE";
+    readonly '--color-border-input-hover': "#A29F9D";
+    readonly '--color-border-input-focus': "#1072CB";
     readonly '--color-border-input-error': "#D14343";
     readonly '--color-hairline-subtle': "rgba(0, 0, 0, 0.06)";
     readonly '--color-hairline-default': "rgba(0, 0, 0, 0.09)";
     readonly '--color-hairline-strong': "rgba(0, 0, 0, 0.14)";
     readonly '--color-interactive-disabled-text': "rgba(55, 65, 81, 0.26)";
-    readonly '--color-avatar-background': "#6B7280";
+    readonly '--color-avatar-background': "#72716F";
     readonly '--color-avatar-text': "#FFFFFF";
 };
 declare const darkThemeCSSVars: {
@@ -1240,35 +1219,31 @@ declare const darkThemeCSSVars: {
     readonly '--color-status-warning-subtle': "rgba(249, 180, 21, 0.12)";
     readonly '--color-status-info': "#2196F3";
     readonly '--color-status-info-subtle': "rgba(33, 150, 243, 0.12)";
-    readonly '--color-status-error-vivid': "#FF4757";
-    readonly '--color-status-error-vivid-light': "#FF6070";
-    readonly '--color-status-error-vivid-dark': "#C42539";
+    readonly '--color-status-error-vivid': "#D14343";
+    readonly '--color-status-error-vivid-light': "#E05254";
+    readonly '--color-status-error-vivid-dark': "#A4221C";
     readonly '--color-status-error-vivid-subtle': "rgba(255, 71, 87, 0.12)";
-    readonly '--color-text-primary': "#F3F4F6";
-    readonly '--color-text-secondary': "#9CA3AF";
-    readonly '--color-text-tertiary': "#6B7280";
+    readonly '--color-text-primary': "#F9F6F3";
+    readonly '--color-text-secondary': "#A29F9D";
+    readonly '--color-text-tertiary': "#888684";
     readonly '--color-text-disabled': "rgba(255, 255, 255, 0.38)";
-    readonly '--color-text-inverse': "#111827";
+    readonly '--color-text-inverse': "#1C1916";
     readonly '--color-text-link': "#828DF8";
     readonly '--color-surface-base': "#252321";
     readonly '--color-surface-elevated': "#2C2A28";
     readonly '--color-surface-raised': "#31302F";
-    readonly '--color-surface-inset': "#13100D";
     readonly '--color-background-base': "#1C1916";
     readonly '--color-background-default': "#252321";
     readonly '--color-background-subtle': "#2C2A28";
     readonly '--color-background-frame': "#100D0A";
-    readonly '--color-border-default': "#1F1F1F";
-    readonly '--color-border-subtle': "#1C1C1C";
-    readonly '--color-border-strong': "#2C2C2C";
-    readonly '--color-border-prominent': "#3C3C3C";
+    readonly '--color-border-prominent': "#424140";
     readonly '--color-border-focus': "#828DF8";
     readonly '--color-interactive-hover': "rgba(255, 255, 255, 0.04)";
     readonly '--color-interactive-focus': "rgba(255, 255, 255, 0.12)";
     readonly '--color-interactive-active': "rgba(255, 255, 255, 0.16)";
     readonly '--color-interactive-selected': "rgba(255, 255, 255, 0.08)";
     readonly '--color-interactive-disabled': "rgba(255, 255, 255, 0.12)";
-    readonly '--color-divider': "#1F1F1F";
+    readonly '--color-divider': "rgba(255, 255, 255, 0.09)";
     readonly '--color-brand-primary-hover': "#FFA063";
     readonly '--color-brand-primary-active': "#FFC7A2";
     readonly '--color-brand-secondary-hover': "#2697B7";
@@ -1293,7 +1268,7 @@ declare const darkThemeCSSVars: {
     readonly '--color-result-degrade-dark': "#b30000";
     readonly '--color-result-inconclusive': "#9E9A97";
     readonly '--color-result-inconclusive-light': "rgba(158, 154, 151, 0.16)";
-    readonly '--color-result-neutral': "#9CA3AF";
+    readonly '--color-result-neutral': "#A29F9D";
     readonly '--color-on-result-improve': "#FFFFFF";
     readonly '--color-on-result-degrade': "#FFFFFF";
     readonly '--color-on-result-inconclusive': "#FFFFFF";
@@ -1307,18 +1282,18 @@ declare const darkThemeCSSVars: {
     readonly '--color-data-8': "#90C987";
     readonly '--color-data-9': "#CAACCB";
     readonly '--color-data-10': "#EE8026";
-    readonly '--color-text-link-hover': "#60A5FA";
+    readonly '--color-text-link-hover': "#3CA8FF";
     readonly '--color-surface-overlay': "#373635";
     readonly '--color-surface-input': "#2C2A28";
-    readonly '--color-border-input': "#4B5563";
-    readonly '--color-border-input-hover': "#6B7280";
+    readonly '--color-border-input': "#5A5958";
+    readonly '--color-border-input-hover': "#72716F";
     readonly '--color-border-input-focus': "#828DF8";
-    readonly '--color-border-input-error': "#EF4444";
-    readonly '--color-hairline-subtle': "rgba(255, 255, 255, 0.06)";
-    readonly '--color-hairline-default': "rgba(255, 255, 255, 0.09)";
-    readonly '--color-hairline-strong': "rgba(255, 255, 255, 0.14)";
+    readonly '--color-border-input-error': "#E05254";
+    readonly '--color-hairline-subtle': "rgba(255, 255, 255, 0.10)";
+    readonly '--color-hairline-default': "rgba(255, 255, 255, 0.15)";
+    readonly '--color-hairline-strong': "rgba(255, 255, 255, 0.22)";
     readonly '--color-interactive-disabled-text': "rgba(255, 255, 255, 0.26)";
-    readonly '--color-avatar-background': "#4B5563";
+    readonly '--color-avatar-background': "#5A5958";
     readonly '--color-avatar-text': "#FFFFFF";
 };
 declare function getThemeCSSVars(mode: ThemeMode): {
@@ -1360,29 +1335,25 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-status-warning-subtle': "#FFF7DD";
     readonly '--color-status-info': "#2196F3";
     readonly '--color-status-info-subtle': "#EFF8FF";
-    readonly '--color-status-error-vivid': "#FF4757";
-    readonly '--color-status-error-vivid-light': "#FF6070";
-    readonly '--color-status-error-vivid-dark': "#C42539";
+    readonly '--color-status-error-vivid': "#D14343";
+    readonly '--color-status-error-vivid-light': "#E05254";
+    readonly '--color-status-error-vivid-dark': "#A4221C";
     readonly '--color-status-error-vivid-subtle': "rgba(255, 71, 87, 0.12)";
     readonly '--color-text-primary': "#121828";
     readonly '--color-text-secondary': "#65748B";
-    readonly '--color-text-tertiary': "#9CA3AF";
+    readonly '--color-text-tertiary': "#A29F9D";
     readonly '--color-text-disabled': "rgba(55, 65, 81, 0.48)";
     readonly '--color-text-inverse': "#FFFFFF";
-    readonly '--color-text-link': "#5048E5";
+    readonly '--color-text-link': "#1072CB";
     readonly '--color-surface-base': "#FFFFFF";
-    readonly '--color-surface-elevated': "#FAFAFA";
-    readonly '--color-surface-raised': "#F3F4F6";
-    readonly '--color-surface-inset': "#D1D5DB";
+    readonly '--color-surface-elevated': "#F9F6F3";
+    readonly '--color-surface-raised': "#EDEAE7";
     readonly '--color-background-base': "#EBEBEB";
     readonly '--color-background-default': "#FFFFFF";
-    readonly '--color-background-subtle': "#FAFAFA";
-    readonly '--color-background-frame': "#9CA3AF";
-    readonly '--color-border-default': "#E8E9EB";
-    readonly '--color-border-subtle': "#F3F4F6";
-    readonly '--color-border-strong': "#D1D5DB";
-    readonly '--color-border-prominent': "#9CA3AF";
-    readonly '--color-border-focus': "#5048E5";
+    readonly '--color-background-subtle': "#F9F6F3";
+    readonly '--color-background-frame': "#A29F9D";
+    readonly '--color-border-prominent': "#A29F9D";
+    readonly '--color-border-focus': "#1072CB";
     readonly '--color-interactive-hover': "rgba(55, 65, 81, 0.04)";
     readonly '--color-interactive-focus': "rgba(55, 65, 81, 0.12)";
     readonly '--color-interactive-active': "rgba(55, 65, 81, 0.16)";
@@ -1413,7 +1384,7 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-result-degrade-dark': "#b30000";
     readonly '--color-result-inconclusive': "#9E9A97";
     readonly '--color-result-inconclusive-light': "rgba(158, 154, 151, 0.12)";
-    readonly '--color-result-neutral': "#6B7280";
+    readonly '--color-result-neutral': "#72716F";
     readonly '--color-on-result-improve': "#FFFFFF";
     readonly '--color-on-result-degrade': "#FFFFFF";
     readonly '--color-on-result-inconclusive': "#FFFFFF";
@@ -1427,18 +1398,18 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-data-8': "#90C987";
     readonly '--color-data-9': "#CAACCB";
     readonly '--color-data-10': "#EE8026";
-    readonly '--color-text-link-hover': "#3832A0";
+    readonly '--color-text-link-hover': "#135AA8";
     readonly '--color-surface-overlay': "#FFFFFF";
-    readonly '--color-surface-input': "#FAFAFA";
-    readonly '--color-border-input': "#D1D5DB";
-    readonly '--color-border-input-hover': "#9CA3AF";
-    readonly '--color-border-input-focus': "#5048E5";
+    readonly '--color-surface-input': "#F9F6F3";
+    readonly '--color-border-input': "#D4D1CE";
+    readonly '--color-border-input-hover': "#A29F9D";
+    readonly '--color-border-input-focus': "#1072CB";
     readonly '--color-border-input-error': "#D14343";
     readonly '--color-hairline-subtle': "rgba(0, 0, 0, 0.06)";
     readonly '--color-hairline-default': "rgba(0, 0, 0, 0.09)";
     readonly '--color-hairline-strong': "rgba(0, 0, 0, 0.14)";
     readonly '--color-interactive-disabled-text': "rgba(55, 65, 81, 0.26)";
-    readonly '--color-avatar-background': "#6B7280";
+    readonly '--color-avatar-background': "#72716F";
     readonly '--color-avatar-text': "#FFFFFF";
 } | {
     readonly '--color-brand-primary-rgb': "255, 121, 0";
@@ -1479,35 +1450,31 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-status-warning-subtle': "rgba(249, 180, 21, 0.12)";
     readonly '--color-status-info': "#2196F3";
     readonly '--color-status-info-subtle': "rgba(33, 150, 243, 0.12)";
-    readonly '--color-status-error-vivid': "#FF4757";
-    readonly '--color-status-error-vivid-light': "#FF6070";
-    readonly '--color-status-error-vivid-dark': "#C42539";
+    readonly '--color-status-error-vivid': "#D14343";
+    readonly '--color-status-error-vivid-light': "#E05254";
+    readonly '--color-status-error-vivid-dark': "#A4221C";
     readonly '--color-status-error-vivid-subtle': "rgba(255, 71, 87, 0.12)";
-    readonly '--color-text-primary': "#F3F4F6";
-    readonly '--color-text-secondary': "#9CA3AF";
-    readonly '--color-text-tertiary': "#6B7280";
+    readonly '--color-text-primary': "#F9F6F3";
+    readonly '--color-text-secondary': "#A29F9D";
+    readonly '--color-text-tertiary': "#888684";
     readonly '--color-text-disabled': "rgba(255, 255, 255, 0.38)";
-    readonly '--color-text-inverse': "#111827";
+    readonly '--color-text-inverse': "#1C1916";
     readonly '--color-text-link': "#828DF8";
     readonly '--color-surface-base': "#252321";
     readonly '--color-surface-elevated': "#2C2A28";
     readonly '--color-surface-raised': "#31302F";
-    readonly '--color-surface-inset': "#13100D";
     readonly '--color-background-base': "#1C1916";
     readonly '--color-background-default': "#252321";
     readonly '--color-background-subtle': "#2C2A28";
     readonly '--color-background-frame': "#100D0A";
-    readonly '--color-border-default': "#1F1F1F";
-    readonly '--color-border-subtle': "#1C1C1C";
-    readonly '--color-border-strong': "#2C2C2C";
-    readonly '--color-border-prominent': "#3C3C3C";
+    readonly '--color-border-prominent': "#424140";
     readonly '--color-border-focus': "#828DF8";
     readonly '--color-interactive-hover': "rgba(255, 255, 255, 0.04)";
     readonly '--color-interactive-focus': "rgba(255, 255, 255, 0.12)";
     readonly '--color-interactive-active': "rgba(255, 255, 255, 0.16)";
     readonly '--color-interactive-selected': "rgba(255, 255, 255, 0.08)";
     readonly '--color-interactive-disabled': "rgba(255, 255, 255, 0.12)";
-    readonly '--color-divider': "#1F1F1F";
+    readonly '--color-divider': "rgba(255, 255, 255, 0.09)";
     readonly '--color-brand-primary-hover': "#FFA063";
     readonly '--color-brand-primary-active': "#FFC7A2";
     readonly '--color-brand-secondary-hover': "#2697B7";
@@ -1532,7 +1499,7 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-result-degrade-dark': "#b30000";
     readonly '--color-result-inconclusive': "#9E9A97";
     readonly '--color-result-inconclusive-light': "rgba(158, 154, 151, 0.16)";
-    readonly '--color-result-neutral': "#9CA3AF";
+    readonly '--color-result-neutral': "#A29F9D";
     readonly '--color-on-result-improve': "#FFFFFF";
     readonly '--color-on-result-degrade': "#FFFFFF";
     readonly '--color-on-result-inconclusive': "#FFFFFF";
@@ -1546,18 +1513,18 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-data-8': "#90C987";
     readonly '--color-data-9': "#CAACCB";
     readonly '--color-data-10': "#EE8026";
-    readonly '--color-text-link-hover': "#60A5FA";
+    readonly '--color-text-link-hover': "#3CA8FF";
     readonly '--color-surface-overlay': "#373635";
     readonly '--color-surface-input': "#2C2A28";
-    readonly '--color-border-input': "#4B5563";
-    readonly '--color-border-input-hover': "#6B7280";
+    readonly '--color-border-input': "#5A5958";
+    readonly '--color-border-input-hover': "#72716F";
     readonly '--color-border-input-focus': "#828DF8";
-    readonly '--color-border-input-error': "#EF4444";
-    readonly '--color-hairline-subtle': "rgba(255, 255, 255, 0.06)";
-    readonly '--color-hairline-default': "rgba(255, 255, 255, 0.09)";
-    readonly '--color-hairline-strong': "rgba(255, 255, 255, 0.14)";
+    readonly '--color-border-input-error': "#E05254";
+    readonly '--color-hairline-subtle': "rgba(255, 255, 255, 0.10)";
+    readonly '--color-hairline-default': "rgba(255, 255, 255, 0.15)";
+    readonly '--color-hairline-strong': "rgba(255, 255, 255, 0.22)";
     readonly '--color-interactive-disabled-text': "rgba(255, 255, 255, 0.26)";
-    readonly '--color-avatar-background': "#4B5563";
+    readonly '--color-avatar-background': "#5A5958";
     readonly '--color-avatar-text': "#FFFFFF";
 };
 declare const gluestackConfig: {
@@ -1630,14 +1597,165 @@ declare const gluestackConfig: {
 type ThemeConfig = typeof gluestackConfig;
 
 /**
- * Neumorphic Shadow Utilities
+ * 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 coordination/design-explorations/surface-system-north-star.md §4 and
+ * coordination/validation-runbooks/VW-99-depth-wall-calibration.md.
+ */
+
+/**
+ * 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.
+ */
+declare function grainOpacityForTone(baseColor: string): number;
+/**
+ * The matte grain tile as a `backgroundImage` url — one shared `feTurbulence`
+ * fractal-noise tile, painted once, NEVER animated. Pair with
+ * `backgroundColor: baseColor`.
+ */
+declare function grainForTone(baseColor: string): string;
+/**
+ * A matte PAPER hero sheet: brightness-scaled grain + a crisp top rim-light +
+ * one soft contact shadow.
  *
- * Neumorphism creates soft, extruded UI using dual opposing shadows.
- * - Light source assumed from top-left
- * - Raised elements: dark shadow bottom-right, light highlight top-left
- * - Pressed elements: inverted with `inset` shadows
+ * 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.
+ */
+declare function paperSheet(tone?: string): 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.
  */
+declare function insetWell(tone?: string): 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.
+ */
+declare function barPaper(color: string, flip?: boolean): ViewStyle;
 
+/**
+ * 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.
+ */
 /**
  * Parse a hex color to RGB values (0-255).
  * Supports both #RGB and #RRGGBB formats.
@@ -1698,134 +1816,10 @@ declare function getHoverColors(bgColor: string, intensity?: 'subtle' | 'medium'
  */
 declare function isDark(hex: string): boolean;
 /**
- * Shadow configuration for different surface colors.
- * Each surface needs calibrated light/dark shadow colors.
- *
- * - dark: soft shadow for depth (bottom-right)
- * - light: sharp rim highlight (top-left) - higher opacity for crisp edge
- * - darker: deeper shadow for pressed/inset states
+ * Shadow strength tiers. Retained because `elevation.ts` keys its level table on
+ * them; the neumorphic shadow BUILDERS that used to live here are gone.
  */
-declare const shadowColors: {
-    charcoal: {
-        dark: string;
-        light: string;
-        darker: string;
-    };
-    neutralDark: {
-        dark: string;
-        light: string;
-        darker: string;
-    };
-    neutralLight: {
-        dark: string;
-        light: string;
-        darker: string;
-    };
-};
 type ShadowIntensity = 'subtle' | 'medium' | 'strong';
-type ShadowSurface = keyof typeof shadowColors;
-/**
- * Creates a raised (elevated) neumorphic shadow.
- * Element appears to float above the surface.
- *
- * Uses a soft dark shadow (bottom-right) and a sharp rim light (top-left).
- */
-declare function createRaisedShadow(surface?: ShadowSurface, intensity?: ShadowIntensity): ViewStyle;
-/**
- * Creates a pressed (inset) neumorphic shadow.
- * Element appears pushed into the surface.
- *
- * Uses a soft dark inset shadow (top-left) and a thin sharp rim light (bottom-right).
- */
-declare function createPressedShadow(surface?: ShadowSurface, intensity?: ShadowIntensity): ViewStyle;
-/**
- * Creates a flat (no shadow) style for hover states.
- */
-declare function createFlatShadow(): ViewStyle;
-/**
- * Creates a hover shadow for raised elements.
- * Reduces shadow depth but keeps a subtle rim light to maintain visual boundary.
- */
-declare function createRaisedHoverShadow(surface?: ShadowSurface, intensity?: ShadowIntensity): ViewStyle;
-/**
- * Creates a hover shadow for pressed elements.
- * Reduces shadow depth but keeps a subtle rim light to maintain visual boundary.
- */
-declare function createPressedHoverShadow(surface?: ShadowSurface, intensity?: ShadowIntensity): ViewStyle;
-/**
- * Pre-built shadow presets for common use cases.
- */
-declare const neumorphicShadows: {
-    charcoal: {
-        raised: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        raisedHover: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        pressed: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        pressedHover: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        flat: ViewStyle;
-    };
-    neutralDark: {
-        raised: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        raisedHover: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        pressed: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        pressedHover: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        flat: ViewStyle;
-    };
-    neutralLight: {
-        raised: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        raisedHover: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        pressed: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        pressedHover: {
-            subtle: ViewStyle;
-            medium: ViewStyle;
-            strong: ViewStyle;
-        };
-        flat: ViewStyle;
-    };
-};
 
 /**
  * TypeScript mirror of css-property-manifest.schema.json.
@@ -1967,9 +1961,9 @@ 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;
@@ -2022,4 +2016,4 @@ declare const defaultPreset: ThemePreset;
  */
 declare const audiobookPreset: ThemePreset;
 
-export { CATEGORICAL_CVD_SAFE_MAX, type CategoricalVariant, type ComponentType, type CssPropertyEntry, type CssPropertyManifest, type ElevationConfig, type ElevationLevel, type GlowIntensity, type GradientStyle, type ManifestValidationResult, PRESSED_ELEVATION_LEVEL, type ShadowIntensity, type ShadowSurface, type ThemeConfig, type ThemeMode, type ThemePreset, type ThemePresetColors, type ThemePresetFonts, type ThemePresetRadii, type ThemePresetShadows, ThemeProvider, type ThemeProviderMode, type ThemeProviderProps, type VariantAxes, type VariantOverride, applyThemePreset, audiobookPreset, backgroundFrameDark, bestTextColor, buttonSizes, categoricalPalette, componentElevationRanges, createFlatShadow, createPressedHoverShadow, createPressedShadow, createRaisedHoverShadow, createRaisedShadow, darkThemeCSSVars, darken, defaultPreset, discreteRainbow, divergingScale, elevationSystem, getBaseSurfaceColor, getCategoricalColor, getDiscreteRainbowColor, getElevationConfig, getElevationShadow, getElevationSurface, getGlowShadow, getHoverColors, getPressedRecessShadow, getSemanticColors, getThemeCSSVars, getValidatedElevation, gluestackConfig, hexToRgb, hsvToRgb, isCssPropertyManifest, isDark, lightThemeCSSVars, lighten, linearGradient, neumorphicShadows, primitiveBorderRadius, primitiveBreakpoints, primitiveColors, primitiveRamps, primitiveShadows, primitiveSpacing, primitiveTypography, primitiveZIndex, resolveColor, rgbToHex, rgbToHsv, semanticColorsDark, semanticColorsLight, semanticTypography, sequentialEffort, shadowColors, surfaceGradient, surfaceRampDark, validateCssPropertyManifest };
+export { CATEGORICAL_CVD_SAFE_MAX, type CategoricalVariant, type ComponentType, type CssPropertyEntry, type CssPropertyManifest, type ElevationConfig, type ElevationLevel, FLOATING_ELEVATION_MIN, type GlowIntensity, type GradientStyle, type ManifestValidationResult, PRESSED_ELEVATION_LEVEL, SURFACE_PLANE_STEPS, type ShadowIntensity, type ThemeConfig, type ThemeMode, type ThemePreset, type ThemePresetColors, type ThemePresetFonts, type ThemePresetRadii, type ThemePresetShadows, ThemeProvider, type ThemeProviderMode, type ThemeProviderProps, type VariantAxes, type VariantOverride, applyThemePreset, audiobookPreset, barPaper, bestTextColor, buttonSizes, categoricalPalette, componentElevationRanges, darkThemeCSSVars, darken, defaultPreset, discreteRainbow, divergingScale, elevationSystem, getBaseSurfaceColor, getCategoricalColor, getDiscreteRainbowColor, getElevationConfig, getElevationShadow, getElevationSurface, getGlowShadow, getHoverColors, getPressedRecessShadow, getSemanticColors, getThemeCSSVars, getValidatedElevation, gluestackConfig, grainForTone, grainOpacityForTone, greyRamp, hexToRgb, hsvToRgb, insetWell, isCssPropertyManifest, isDark, lightThemeCSSVars, lighten, linearGradient, paperSheet, primitiveBorderRadius, primitiveBreakpoints, primitiveColors, primitiveRamps, primitiveSpacing, primitiveTypography, primitiveZIndex, resolveColor, rgbToHex, rgbToHsv, semanticColorsDark, semanticColorsLight, semanticTypography, sequentialEffort, surfaceGradient, validateCssPropertyManifest };