@titan-design/react-ui 0.9.3 → 0.11.0

package/dist/theme/index.d.mts

@@ -93,9 +93,11 @@ declare const semanticColorsLight: {
     readonly 'surface-raised': "#F3F4F6";
     readonly 'surface-overlay': "#FFFFFF";
     readonly 'surface-input': "#FAFAFA";
+    readonly 'surface-inset': "#D1D5DB";
     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";
@@ -105,6 +107,9 @@ declare const semanticColorsLight: {
     readonly 'border-input-hover': "#9CA3AF";
     readonly 'border-input-focus': "#5048E5";
     readonly 'border-input-error': "#D14343";
+    readonly 'hairline-subtle': "rgba(0, 0, 0, 0.06)";
+    readonly 'hairline-default': "rgba(0, 0, 0, 0.09)";
+    readonly 'hairline-strong': "rgba(0, 0, 0, 0.14)";
     readonly 'interactive-hover': "rgba(55, 65, 81, 0.04)";
     readonly 'interactive-focus': "rgba(55, 65, 81, 0.12)";
     readonly 'interactive-active': "rgba(55, 65, 81, 0.16)";
@@ -185,14 +190,16 @@ declare const semanticColorsDark: {
     readonly 'text-inverse': "#111827";
     readonly 'text-link': "#828DF8";
     readonly 'text-link-hover': "#60A5FA";
-    readonly 'surface-base': "#161616";
-    readonly 'surface-elevated': "#191919";
-    readonly 'surface-raised': "#1C1C1C";
-    readonly 'surface-overlay': "#191919";
-    readonly 'surface-input': "#191919";
-    readonly 'background-base': "#101010";
-    readonly 'background-default': "#161616";
-    readonly 'background-subtle': "#1C1C1C";
+    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";
@@ -202,6 +209,9 @@ declare const semanticColorsDark: {
     readonly 'border-input-hover': "#6B7280";
     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 '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)";
@@ -387,9 +397,11 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'surface-raised': "#F3F4F6";
     readonly 'surface-overlay': "#FFFFFF";
     readonly 'surface-input': "#FAFAFA";
+    readonly 'surface-inset': "#D1D5DB";
     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";
@@ -399,6 +411,9 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'border-input-hover': "#9CA3AF";
     readonly 'border-input-focus': "#5048E5";
     readonly 'border-input-error': "#D14343";
+    readonly 'hairline-subtle': "rgba(0, 0, 0, 0.06)";
+    readonly 'hairline-default': "rgba(0, 0, 0, 0.09)";
+    readonly 'hairline-strong': "rgba(0, 0, 0, 0.14)";
     readonly 'interactive-hover': "rgba(55, 65, 81, 0.04)";
     readonly 'interactive-focus': "rgba(55, 65, 81, 0.12)";
     readonly 'interactive-active': "rgba(55, 65, 81, 0.16)";
@@ -478,14 +493,16 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'text-inverse': "#111827";
     readonly 'text-link': "#828DF8";
     readonly 'text-link-hover': "#60A5FA";
-    readonly 'surface-base': "#161616";
-    readonly 'surface-elevated': "#191919";
-    readonly 'surface-raised': "#1C1C1C";
-    readonly 'surface-overlay': "#191919";
-    readonly 'surface-input': "#191919";
-    readonly 'background-base': "#101010";
-    readonly 'background-default': "#161616";
-    readonly 'background-subtle': "#1C1C1C";
+    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";
@@ -495,6 +512,9 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'border-input-hover': "#6B7280";
     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 '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)";
@@ -568,6 +588,23 @@ declare function getElevationSurface(baseColor: string, level: ElevationLevel, t
  * @returns ViewStyle with shadow properties
  */
 declare function getElevationShadow(baseColor: string, level: ElevationLevel, theme: 'light' | 'dark', isHovered?: boolean): ViewStyle;
+/**
+ * Elevation level backing a `<Surface pressed>` recess: the shallow `inset`
+ * (-1) step. Pressed exposes ONE level of depth — pressed-2 is intentionally
+ * not surfaced (the deeper `-2` deep-inset stays available to `elevation`).
+ */
+declare const PRESSED_ELEVATION_LEVEL: ElevationLevel;
+/**
+ * Inner-shadow recess for a pressed (sunken) surface, tuned to the well's own
+ * fill colour so the rim/shadow tints track the darker fill. Composes WITH the
+ * darker pressed fill: on web it adds an inset boxShadow; on the native path
+ * (no inset-shadow support) it's a no-op and the recess reads via the fill
+ * alone — so a pressed surface stays legibly sunken with or without the shadow.
+ *
+ * @param fillColor - The pressed surface's own fill (one ramp step down).
+ * @param theme - Current theme ('light' or 'dark').
+ */
+declare function getPressedRecessShadow(fillColor: string, theme: 'light' | 'dark'): ViewStyle;
 /**
  * Get base surface color from theme.
  * This is the foundation color that all elevations are calculated from.
@@ -579,7 +616,7 @@ declare function getElevationShadow(baseColor: string, level: ElevationLevel, th
  *   - This allows raised elevations to be lighter (closer to white)
  *
  * **Dark Mode**: Need lighter base to allow sufficient lightening
- *   - Use `#191919` (charcoal[600]) - allows lightening to `#2A2A2A` at max elevation
+ *   - Use `surface-elevated` (#2A2827, TD-surface-tokens ramp) - allows further lightening
  *
  * Can be overridden to use custom base colors for special cases.
  */
@@ -702,6 +739,44 @@ declare const primitiveColors: {
     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.
+ */
+declare const surfaceRampDark: {
+    readonly inset: "#13100D";
+    readonly background: "#1C1916";
+    readonly base: "#252321";
+    readonly elevated: "#2C2A28";
+    readonly raised: "#31302F";
+    readonly overlay: "#373635";
+};
+/**
+ * Frame/bezel primitive — dark mode (TD-surface-tokens, S-3)
+ *
+ * The chrome that "exits the content ramp" entirely: the top bar + side nav
+ * shell. Sits ONE STEP BELOW `surfaceRampDark.background` (L*9), darker even
+ * than `surfaceRampDark.inset` (L*4.5) — it isn't a plane IN the ramp, it's
+ * the bezel the ramp sits inside. Literal, not `deriveSurfaceRamp()` output.
+ */
+declare const backgroundFrameDark = "#100D0A";
 /**
  * Derived tonal ramps (TD-05.09 color foundations)
  *
@@ -1058,9 +1133,11 @@ declare const lightThemeCSSVars: {
     readonly '--color-surface-base': "#FFFFFF";
     readonly '--color-surface-elevated': "#FAFAFA";
     readonly '--color-surface-raised': "#F3F4F6";
+    readonly '--color-surface-inset': "#D1D5DB";
     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";
@@ -1117,6 +1194,9 @@ declare const lightThemeCSSVars: {
     readonly '--color-border-input-hover': "#9CA3AF";
     readonly '--color-border-input-focus': "#5048E5";
     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-text': "#FFFFFF";
@@ -1170,12 +1250,14 @@ declare const darkThemeCSSVars: {
     readonly '--color-text-disabled': "rgba(255, 255, 255, 0.38)";
     readonly '--color-text-inverse': "#111827";
     readonly '--color-text-link': "#828DF8";
-    readonly '--color-surface-base': "#161616";
-    readonly '--color-surface-elevated': "#191919";
-    readonly '--color-surface-raised': "#1C1C1C";
-    readonly '--color-background-base': "#101010";
-    readonly '--color-background-default': "#161616";
-    readonly '--color-background-subtle': "#1C1C1C";
+    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";
@@ -1226,12 +1308,15 @@ declare const darkThemeCSSVars: {
     readonly '--color-data-9': "#CAACCB";
     readonly '--color-data-10': "#EE8026";
     readonly '--color-text-link-hover': "#60A5FA";
-    readonly '--color-surface-overlay': "#191919";
-    readonly '--color-surface-input': "#191919";
+    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-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-interactive-disabled-text': "rgba(255, 255, 255, 0.26)";
     readonly '--color-avatar-background': "#4B5563";
     readonly '--color-avatar-text': "#FFFFFF";
@@ -1288,9 +1373,11 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-surface-base': "#FFFFFF";
     readonly '--color-surface-elevated': "#FAFAFA";
     readonly '--color-surface-raised': "#F3F4F6";
+    readonly '--color-surface-inset': "#D1D5DB";
     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";
@@ -1347,6 +1434,9 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-border-input-hover': "#9CA3AF";
     readonly '--color-border-input-focus': "#5048E5";
     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-text': "#FFFFFF";
@@ -1399,12 +1489,14 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-text-disabled': "rgba(255, 255, 255, 0.38)";
     readonly '--color-text-inverse': "#111827";
     readonly '--color-text-link': "#828DF8";
-    readonly '--color-surface-base': "#161616";
-    readonly '--color-surface-elevated': "#191919";
-    readonly '--color-surface-raised': "#1C1C1C";
-    readonly '--color-background-base': "#101010";
-    readonly '--color-background-default': "#161616";
-    readonly '--color-background-subtle': "#1C1C1C";
+    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";
@@ -1455,12 +1547,15 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-data-9': "#CAACCB";
     readonly '--color-data-10': "#EE8026";
     readonly '--color-text-link-hover': "#60A5FA";
-    readonly '--color-surface-overlay': "#191919";
-    readonly '--color-surface-input': "#191919";
+    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-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-interactive-disabled-text': "rgba(255, 255, 255, 0.26)";
     readonly '--color-avatar-background': "#4B5563";
     readonly '--color-avatar-text': "#FFFFFF";
@@ -1927,4 +2022,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, 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, bestTextColor, buttonSizes, categoricalPalette, componentElevationRanges, createFlatShadow, createPressedHoverShadow, createPressedShadow, createRaisedHoverShadow, createRaisedShadow, darkThemeCSSVars, darken, defaultPreset, discreteRainbow, divergingScale, elevationSystem, getBaseSurfaceColor, getCategoricalColor, getDiscreteRainbowColor, getElevationConfig, getElevationShadow, getElevationSurface, getGlowShadow, getHoverColors, 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, validateCssPropertyManifest };
+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 };

package/dist/theme/index.d.ts

@@ -93,9 +93,11 @@ declare const semanticColorsLight: {
     readonly 'surface-raised': "#F3F4F6";
     readonly 'surface-overlay': "#FFFFFF";
     readonly 'surface-input': "#FAFAFA";
+    readonly 'surface-inset': "#D1D5DB";
     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";
@@ -105,6 +107,9 @@ declare const semanticColorsLight: {
     readonly 'border-input-hover': "#9CA3AF";
     readonly 'border-input-focus': "#5048E5";
     readonly 'border-input-error': "#D14343";
+    readonly 'hairline-subtle': "rgba(0, 0, 0, 0.06)";
+    readonly 'hairline-default': "rgba(0, 0, 0, 0.09)";
+    readonly 'hairline-strong': "rgba(0, 0, 0, 0.14)";
     readonly 'interactive-hover': "rgba(55, 65, 81, 0.04)";
     readonly 'interactive-focus': "rgba(55, 65, 81, 0.12)";
     readonly 'interactive-active': "rgba(55, 65, 81, 0.16)";
@@ -185,14 +190,16 @@ declare const semanticColorsDark: {
     readonly 'text-inverse': "#111827";
     readonly 'text-link': "#828DF8";
     readonly 'text-link-hover': "#60A5FA";
-    readonly 'surface-base': "#161616";
-    readonly 'surface-elevated': "#191919";
-    readonly 'surface-raised': "#1C1C1C";
-    readonly 'surface-overlay': "#191919";
-    readonly 'surface-input': "#191919";
-    readonly 'background-base': "#101010";
-    readonly 'background-default': "#161616";
-    readonly 'background-subtle': "#1C1C1C";
+    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";
@@ -202,6 +209,9 @@ declare const semanticColorsDark: {
     readonly 'border-input-hover': "#6B7280";
     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 '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)";
@@ -387,9 +397,11 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'surface-raised': "#F3F4F6";
     readonly 'surface-overlay': "#FFFFFF";
     readonly 'surface-input': "#FAFAFA";
+    readonly 'surface-inset': "#D1D5DB";
     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";
@@ -399,6 +411,9 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'border-input-hover': "#9CA3AF";
     readonly 'border-input-focus': "#5048E5";
     readonly 'border-input-error': "#D14343";
+    readonly 'hairline-subtle': "rgba(0, 0, 0, 0.06)";
+    readonly 'hairline-default': "rgba(0, 0, 0, 0.09)";
+    readonly 'hairline-strong': "rgba(0, 0, 0, 0.14)";
     readonly 'interactive-hover': "rgba(55, 65, 81, 0.04)";
     readonly 'interactive-focus': "rgba(55, 65, 81, 0.12)";
     readonly 'interactive-active': "rgba(55, 65, 81, 0.16)";
@@ -478,14 +493,16 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'text-inverse': "#111827";
     readonly 'text-link': "#828DF8";
     readonly 'text-link-hover': "#60A5FA";
-    readonly 'surface-base': "#161616";
-    readonly 'surface-elevated': "#191919";
-    readonly 'surface-raised': "#1C1C1C";
-    readonly 'surface-overlay': "#191919";
-    readonly 'surface-input': "#191919";
-    readonly 'background-base': "#101010";
-    readonly 'background-default': "#161616";
-    readonly 'background-subtle': "#1C1C1C";
+    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";
@@ -495,6 +512,9 @@ declare function getSemanticColors(mode: ThemeMode): {
     readonly 'border-input-hover': "#6B7280";
     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 '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)";
@@ -568,6 +588,23 @@ declare function getElevationSurface(baseColor: string, level: ElevationLevel, t
  * @returns ViewStyle with shadow properties
  */
 declare function getElevationShadow(baseColor: string, level: ElevationLevel, theme: 'light' | 'dark', isHovered?: boolean): ViewStyle;
+/**
+ * Elevation level backing a `<Surface pressed>` recess: the shallow `inset`
+ * (-1) step. Pressed exposes ONE level of depth — pressed-2 is intentionally
+ * not surfaced (the deeper `-2` deep-inset stays available to `elevation`).
+ */
+declare const PRESSED_ELEVATION_LEVEL: ElevationLevel;
+/**
+ * Inner-shadow recess for a pressed (sunken) surface, tuned to the well's own
+ * fill colour so the rim/shadow tints track the darker fill. Composes WITH the
+ * darker pressed fill: on web it adds an inset boxShadow; on the native path
+ * (no inset-shadow support) it's a no-op and the recess reads via the fill
+ * alone — so a pressed surface stays legibly sunken with or without the shadow.
+ *
+ * @param fillColor - The pressed surface's own fill (one ramp step down).
+ * @param theme - Current theme ('light' or 'dark').
+ */
+declare function getPressedRecessShadow(fillColor: string, theme: 'light' | 'dark'): ViewStyle;
 /**
  * Get base surface color from theme.
  * This is the foundation color that all elevations are calculated from.
@@ -579,7 +616,7 @@ declare function getElevationShadow(baseColor: string, level: ElevationLevel, th
  *   - This allows raised elevations to be lighter (closer to white)
  *
  * **Dark Mode**: Need lighter base to allow sufficient lightening
- *   - Use `#191919` (charcoal[600]) - allows lightening to `#2A2A2A` at max elevation
+ *   - Use `surface-elevated` (#2A2827, TD-surface-tokens ramp) - allows further lightening
  *
  * Can be overridden to use custom base colors for special cases.
  */
@@ -702,6 +739,44 @@ declare const primitiveColors: {
     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.
+ */
+declare const surfaceRampDark: {
+    readonly inset: "#13100D";
+    readonly background: "#1C1916";
+    readonly base: "#252321";
+    readonly elevated: "#2C2A28";
+    readonly raised: "#31302F";
+    readonly overlay: "#373635";
+};
+/**
+ * Frame/bezel primitive — dark mode (TD-surface-tokens, S-3)
+ *
+ * The chrome that "exits the content ramp" entirely: the top bar + side nav
+ * shell. Sits ONE STEP BELOW `surfaceRampDark.background` (L*9), darker even
+ * than `surfaceRampDark.inset` (L*4.5) — it isn't a plane IN the ramp, it's
+ * the bezel the ramp sits inside. Literal, not `deriveSurfaceRamp()` output.
+ */
+declare const backgroundFrameDark = "#100D0A";
 /**
  * Derived tonal ramps (TD-05.09 color foundations)
  *
@@ -1058,9 +1133,11 @@ declare const lightThemeCSSVars: {
     readonly '--color-surface-base': "#FFFFFF";
     readonly '--color-surface-elevated': "#FAFAFA";
     readonly '--color-surface-raised': "#F3F4F6";
+    readonly '--color-surface-inset': "#D1D5DB";
     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";
@@ -1117,6 +1194,9 @@ declare const lightThemeCSSVars: {
     readonly '--color-border-input-hover': "#9CA3AF";
     readonly '--color-border-input-focus': "#5048E5";
     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-text': "#FFFFFF";
@@ -1170,12 +1250,14 @@ declare const darkThemeCSSVars: {
     readonly '--color-text-disabled': "rgba(255, 255, 255, 0.38)";
     readonly '--color-text-inverse': "#111827";
     readonly '--color-text-link': "#828DF8";
-    readonly '--color-surface-base': "#161616";
-    readonly '--color-surface-elevated': "#191919";
-    readonly '--color-surface-raised': "#1C1C1C";
-    readonly '--color-background-base': "#101010";
-    readonly '--color-background-default': "#161616";
-    readonly '--color-background-subtle': "#1C1C1C";
+    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";
@@ -1226,12 +1308,15 @@ declare const darkThemeCSSVars: {
     readonly '--color-data-9': "#CAACCB";
     readonly '--color-data-10': "#EE8026";
     readonly '--color-text-link-hover': "#60A5FA";
-    readonly '--color-surface-overlay': "#191919";
-    readonly '--color-surface-input': "#191919";
+    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-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-interactive-disabled-text': "rgba(255, 255, 255, 0.26)";
     readonly '--color-avatar-background': "#4B5563";
     readonly '--color-avatar-text': "#FFFFFF";
@@ -1288,9 +1373,11 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-surface-base': "#FFFFFF";
     readonly '--color-surface-elevated': "#FAFAFA";
     readonly '--color-surface-raised': "#F3F4F6";
+    readonly '--color-surface-inset': "#D1D5DB";
     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";
@@ -1347,6 +1434,9 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-border-input-hover': "#9CA3AF";
     readonly '--color-border-input-focus': "#5048E5";
     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-text': "#FFFFFF";
@@ -1399,12 +1489,14 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-text-disabled': "rgba(255, 255, 255, 0.38)";
     readonly '--color-text-inverse': "#111827";
     readonly '--color-text-link': "#828DF8";
-    readonly '--color-surface-base': "#161616";
-    readonly '--color-surface-elevated': "#191919";
-    readonly '--color-surface-raised': "#1C1C1C";
-    readonly '--color-background-base': "#101010";
-    readonly '--color-background-default': "#161616";
-    readonly '--color-background-subtle': "#1C1C1C";
+    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";
@@ -1455,12 +1547,15 @@ declare function getThemeCSSVars(mode: ThemeMode): {
     readonly '--color-data-9': "#CAACCB";
     readonly '--color-data-10': "#EE8026";
     readonly '--color-text-link-hover': "#60A5FA";
-    readonly '--color-surface-overlay': "#191919";
-    readonly '--color-surface-input': "#191919";
+    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-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-interactive-disabled-text': "rgba(255, 255, 255, 0.26)";
     readonly '--color-avatar-background': "#4B5563";
     readonly '--color-avatar-text': "#FFFFFF";
@@ -1927,4 +2022,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, 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, bestTextColor, buttonSizes, categoricalPalette, componentElevationRanges, createFlatShadow, createPressedHoverShadow, createPressedShadow, createRaisedHoverShadow, createRaisedShadow, darkThemeCSSVars, darken, defaultPreset, discreteRainbow, divergingScale, elevationSystem, getBaseSurfaceColor, getCategoricalColor, getDiscreteRainbowColor, getElevationConfig, getElevationShadow, getElevationSurface, getGlowShadow, getHoverColors, 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, validateCssPropertyManifest };
+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 };