@titan-design/react-ui 0.4.0 → 0.6.0

package/src/theme/Colors.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { View, Text } from 'react-native'
-import { primitiveColors, discreteRainbow } from './tokens/primitives'
+import { primitiveColors, discreteRainbow, primitiveRamps, categoricalPalette } from './tokens/primitives'
 import { semanticColorsLight, semanticColorsDark } from './tokens/semantic'
 
 const meta: Meta = {
@@ -236,6 +236,74 @@ export const DataVisualizationColors: StoryObj = {
   ),
 }
 
+function CategoricalRow({ name, colors }: { name: string; colors: readonly string[] }) {
+  return (
+    <View style={{ marginBottom: 24 }}>
+      <Text className="text-lg font-bold text-text-primary mb-3">
+        {name} <Text className="text-text-secondary text-sm">({colors.length})</Text>
+      </Text>
+      <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 8 }}>
+        {colors.map((color, index) => (
+          <View key={index} style={{ alignItems: 'center' }}>
+            <View
+              style={{
+                width: 56,
+                height: 56,
+                borderRadius: 8,
+                backgroundColor: color,
+                borderWidth: 1,
+                borderColor: '#374151',
+              }}
+            />
+            <Text className="text-text-secondary text-xs mt-1">{color.toUpperCase()}</Text>
+          </View>
+        ))}
+      </View>
+    </View>
+  )
+}
+
+export const TonalRamps: StoryObj = {
+  render: () => (
+    <View style={{ padding: 24 }}>
+      <Text className="text-2xl font-bold text-text-primary mb-6">
+        Tonal Ramps (Foundations)
+      </Text>
+      <Text className="text-text-secondary mb-6">
+        Seven OKLCH-generated hue ramps, 11 perceptual steps each (50 → 950). Built with hue-torsion and a
+        chroma arc; amber absorbs the former yellow (lemon → warm body) and cyan absorbs the former steel.
+      </Text>
+
+      <ColorScale name="Red" colors={primitiveRamps.red} />
+      <ColorScale name="Orange" colors={primitiveRamps.orange} />
+      <ColorScale name="Amber" colors={primitiveRamps.amber} />
+      <ColorScale name="Green" colors={primitiveRamps.green} />
+      <ColorScale name="Cyan" colors={primitiveRamps.cyan} />
+      <ColorScale name="Blue" colors={primitiveRamps.blue} />
+      <ColorScale name="Magenta" colors={primitiveRamps.magenta} />
+    </View>
+  ),
+}
+
+export const CategoricalPalette: StoryObj = {
+  render: () => (
+    <View style={{ padding: 24 }}>
+      <Text className="text-2xl font-bold text-text-primary mb-6">
+        Categorical Palette
+      </Text>
+      <Text className="text-text-secondary mb-6">
+        Ordered, colorblind-safe qualitative series (worst-case deut/protanopia floor 8 through the first
+        six colors; the 7th is extended — pair it with a legend). Series index is stable. Use{' '}
+        <Text className="font-semibold">default</Text> on neutral/light surfaces (also legible under black
+        text) and <Text className="font-semibold">dark</Text> where white text sits on the swatch.
+      </Text>
+
+      <CategoricalRow name="Default" colors={categoricalPalette.default} />
+      <CategoricalRow name="Dark (white text)" colors={categoricalPalette.dark} />
+    </View>
+  ),
+}
+
 export const BorderColors: StoryObj = {
   render: () => (
     <View style={{ padding: 24 }}>

package/src/theme/barrel.ts

@@ -0,0 +1,54 @@
+// Theme surface WITHOUT the ThemeProvider value (dep hygiene, titan 0.5.0).
+//
+// `ThemeProvider` imports `nativewind` (`vars()`). Re-exporting it from the root
+// barrel dragged the whole nativewind import chain into every consumer of
+// `@titan-design/react-ui` — the web SPA paid for a native-only provider. This
+// file is the nativewind-free theme surface: the root barrel re-exports THIS,
+// and the `/theme` subpath (`./index.ts`) layers the `ThemeProvider` value on
+// top for the native consumers that deliberately import it.
+export * from './tokens'
+export * from './config'
+export * from './shadows'
+export * from './elevation'
+export * from './manifest'
+export { resolveColor } from './resolve-color'
+export { linearGradient, surfaceGradient, type GradientStyle } from './gradients'
+
+// ThemeProvider TYPES may stay on the root (erased at build — no nativewind
+// pull). Only the ThemeProvider VALUE moves to the `/theme` subpath.
+export type { ThemeProviderProps, ThemeProviderMode } from './ThemeProvider'
+
+// Re-export commonly used items
+export { getSemanticColors, type ThemeMode } from './tokens/semantic'
+export { getThemeCSSVars, gluestackConfig } from './config'
+export {
+  neumorphicShadows,
+  // Color math utilities (HSV-based)
+  lighten,
+  darken,
+  getHoverColors,
+  isDark,
+  hexToRgb,
+  rgbToHsv,
+  // Shadow creation functions
+  createRaisedShadow,
+  createRaisedHoverShadow,
+  createPressedShadow,
+  createPressedHoverShadow,
+  createFlatShadow,
+  shadowColors,
+  type ShadowIntensity,
+  type ShadowSurface,
+} from './shadows'
+export {
+  getElevationConfig,
+  getElevationSurface,
+  getElevationShadow,
+  getBaseSurfaceColor,
+  getValidatedElevation,
+  componentElevationRanges,
+  type ElevationLevel,
+  type ElevationConfig,
+  type ComponentType,
+} from './elevation'
+export * from './presets'

package/src/theme/config.ts

@@ -14,10 +14,11 @@ import { semanticColorsLight, semanticColorsDark, type ThemeMode } from './token
 const themeIndependentCSSVars = {
   // RGB decomposed values for glow shadows
   '--color-brand-primary-rgb': '255, 121, 0',
-  '--color-brand-secondary-rgb': '64, 109, 135',
-  '--color-status-success-rgb': '20, 184, 166',
+  '--color-brand-secondary-rgb': '48, 123, 155',
+  '--color-status-success-rgb': '46, 213, 115',
   '--color-status-error-rgb': '209, 67, 67',
-  '--color-status-warning-rgb': '255, 176, 32',
+  '--color-status-error-vivid-rgb': '255, 71, 87',
+  '--color-status-warning-rgb': '249, 180, 21',
   '--color-status-info-rgb': '33, 150, 243',
   '--color-background-base-rgb': '16, 16, 16',
 
@@ -59,6 +60,11 @@ export const lightThemeCSSVars = {
   '--color-status-info': semanticColorsLight['status-info'],
   '--color-status-info-subtle': semanticColorsLight['status-info-subtle'],
 
+  '--color-status-error-vivid': semanticColorsLight['status-error-vivid'],
+  '--color-status-error-vivid-light': semanticColorsLight['status-error-vivid-light'],
+  '--color-status-error-vivid-dark': semanticColorsLight['status-error-vivid-dark'],
+  '--color-status-error-vivid-subtle': semanticColorsLight['status-error-vivid-subtle'],
+
   '--color-text-primary': semanticColorsLight['text-primary'],
   '--color-text-secondary': semanticColorsLight['text-secondary'],
   '--color-text-tertiary': semanticColorsLight['text-tertiary'],
@@ -77,6 +83,7 @@ export const lightThemeCSSVars = {
   '--color-border-default': semanticColorsLight['border-default'],
   '--color-border-subtle': semanticColorsLight['border-subtle'],
   '--color-border-strong': semanticColorsLight['border-strong'],
+  '--color-border-prominent': semanticColorsLight['border-prominent'],
   '--color-border-focus': semanticColorsLight['border-focus'],
 
   '--color-interactive-hover': semanticColorsLight['interactive-hover'],
@@ -172,6 +179,11 @@ export const darkThemeCSSVars = {
   '--color-status-info': semanticColorsDark['status-info'],
   '--color-status-info-subtle': semanticColorsDark['status-info-subtle'],
 
+  '--color-status-error-vivid': semanticColorsDark['status-error-vivid'],
+  '--color-status-error-vivid-light': semanticColorsDark['status-error-vivid-light'],
+  '--color-status-error-vivid-dark': semanticColorsDark['status-error-vivid-dark'],
+  '--color-status-error-vivid-subtle': semanticColorsDark['status-error-vivid-subtle'],
+
   '--color-text-primary': semanticColorsDark['text-primary'],
   '--color-text-secondary': semanticColorsDark['text-secondary'],
   '--color-text-tertiary': semanticColorsDark['text-tertiary'],
@@ -190,6 +202,7 @@ export const darkThemeCSSVars = {
   '--color-border-default': semanticColorsDark['border-default'],
   '--color-border-subtle': semanticColorsDark['border-subtle'],
   '--color-border-strong': semanticColorsDark['border-strong'],
+  '--color-border-prominent': semanticColorsDark['border-prominent'],
   '--color-border-focus': semanticColorsDark['border-focus'],
 
   '--color-interactive-hover': semanticColorsDark['interactive-hover'],

package/src/theme/extracted-colors-dataviz.ts

@@ -0,0 +1,21 @@
+/**
+ * Data-viz / status / brand fills, sourced from the color foundations.
+ */
+
+import { categoricalPalette, primitiveRamps as ramp } from './tokens/primitives'
+
+/**
+ * Titan categorical fallback palette shared by Treemap and Scatter — the
+ * canonical {@link categoricalPalette} (ordered, nested-stable, CVD-safe).
+ * Components index into it modulo length, so the 7-color series is sufficient.
+ */
+export const DATAVIZ_CATEGORICAL_PALETTE = categoricalPalette.default
+
+/**
+ * MesoCard / MesoStatusCard 3px top-accent gradient stops (dark → primary →
+ * light), on the orange ramp that brand-primary (orange-400) lives in.
+ */
+export const MESO_ACCENT_GRADIENT_DARK = ramp.orange[500]
+export const MESO_ACCENT_GRADIENT_LIGHT = ramp.orange[300]
+
+export const WORKOUT_PILL_DELOAD = ramp.magenta[600]

package/src/theme/extracted-colors-ui.ts

@@ -0,0 +1,20 @@
+/**
+ * UI-atom fills, sourced from the color foundations.
+ */
+
+import { categoricalPalette, primitiveRamps as ramp } from './tokens/primitives'
+
+/**
+ * Spinner `color="primary"` fill — keeps the spinner a cool, on-palette
+ * loading accent.
+ */
+export const SPINNER_PRIMARY = ramp.cyan[600]
+
+export const SPINNER_SECONDARY = ramp.green[400]
+
+/**
+ * Categorical avatar palette — deterministic per-name fill, the canonical
+ * ordered {@link categoricalPalette} (CVD-safe). Order is preserved for stable
+ * hashing.
+ */
+export const AVATAR_CATEGORICAL_COLORS = categoricalPalette.default

package/src/theme/global.css

@@ -16,36 +16,42 @@
   /* Dark mode (default) */
   :root {
     --color-brand-primary: #FF7900;
-    --color-brand-primary-light: #FF9630;
-    --color-brand-primary-dark: #D0620C;
+    --color-brand-primary-light: #FFA063;
+    --color-brand-primary-dark: #DA5F00;
     --color-brand-primary-subtle: rgba(255, 121, 0, 0.12);
-    --color-brand-secondary: #406D87;
-    --color-brand-secondary-light: #678498;
-    --color-brand-secondary-dark: #32556D;
-    --color-brand-secondary-subtle: rgba(64, 109, 135, 0.12);
-    --color-brand-primary-hover: #FF8500;
-    --color-brand-primary-active: #FF9630;
-    --color-brand-secondary-hover: #557488;
-    --color-brand-secondary-active: #678498;
+    --color-brand-secondary: #307B9B;
+    --color-brand-secondary-light: #2697B7;
+    --color-brand-secondary-dark: #2A617F;
+    --color-brand-secondary-subtle: rgba(48, 123, 155, 0.12);
+    --color-brand-primary-hover: #FFA063;
+    --color-brand-primary-active: #FFC7A2;
+    --color-brand-secondary-hover: #2697B7;
+    --color-brand-secondary-active: #01B5D1;
 
     --color-on-brand-primary: #FFFFFF;
     --color-on-brand-secondary: #FFFFFF;
 
-    --color-status-success: #14B8A6;
-    --color-status-success-light: #43C6B7;
-    --color-status-success-dark: #0E8074;
-    --color-status-success-subtle: rgba(20, 184, 166, 0.12);
+    --color-status-success: #2ED573;
+    --color-status-success-light: #58F69E;
+    --color-status-success-dark: #298732;
+    --color-status-success-subtle: rgba(46, 213, 115, 0.12);
     --color-status-error: #D14343;
-    --color-status-error-light: #DA6868;
-    --color-status-error-dark: #922E2E;
+    --color-status-error-light: #E05254;
+    --color-status-error-dark: #A4221C;
     --color-status-error-subtle: rgba(209, 67, 67, 0.12);
-    --color-status-warning: #FFB020;
-    --color-status-warning-light: #FFBF4C;
-    --color-status-warning-dark: #B27B16;
-    --color-status-warning-subtle: rgba(255, 176, 32, 0.12);
+    --color-status-error-vivid: #FF4757;
+    --color-status-error-vivid-light: #FF6070;
+    --color-status-error-vivid-dark: #C42539;
+    --color-status-error-vivid-subtle: rgba(255, 71, 87, 0.12);
+    --color-status-error-vivid-rgb: 255, 71, 87;
+    --color-border-prominent: #3C3C3C;
+    --color-status-warning: #F9B415;
+    --color-status-warning-light: #FFD352;
+    --color-status-warning-dark: #C27400;
+    --color-status-warning-subtle: rgba(249, 180, 21, 0.12);
     --color-status-info: #2196F3;
-    --color-status-info-light: #64B6F7;
-    --color-status-info-dark: #0B79D0;
+    --color-status-info-light: #78C2FF;
+    --color-status-info-dark: #1072CB;
     --color-status-info-subtle: rgba(33, 150, 243, 0.12);
 
     --color-on-status-success: #FFFFFF;
@@ -119,10 +125,10 @@
 
     /* RGB decomposed values for glow shadows */
     --color-brand-primary-rgb: 255, 121, 0;
-    --color-brand-secondary-rgb: 64, 109, 135;
-    --color-status-success-rgb: 20, 184, 166;
+    --color-brand-secondary-rgb: 48, 123, 155;
+    --color-status-success-rgb: 46, 213, 115;
     --color-status-error-rgb: 209, 67, 67;
-    --color-status-warning-rgb: 255, 176, 32;
+    --color-status-warning-rgb: 249, 180, 21;
     --color-status-info-rgb: 33, 150, 243;
     --color-background-base-rgb: 16, 16, 16;
 
@@ -145,37 +151,43 @@
   .light,
   :root.light {
     --color-brand-primary: #FF7900;
-    --color-brand-primary-light: #FF9630;
-    --color-brand-primary-dark: #D0620C;
+    --color-brand-primary-light: #FFA063;
+    --color-brand-primary-dark: #DA5F00;
     --color-brand-primary-subtle: rgba(255, 121, 0, 0.08);
-    --color-brand-secondary: #406D87;
-    --color-brand-secondary-light: #678498;
-    --color-brand-secondary-dark: #32556D;
-    --color-brand-secondary-subtle: rgba(64, 109, 135, 0.08);
-    --color-brand-primary-hover: #F56C00;
-    --color-brand-primary-active: #E06D10;
-    --color-brand-secondary-hover: #39617A;
-    --color-brand-secondary-active: #32556D;
+    --color-brand-secondary: #307B9B;
+    --color-brand-secondary-light: #2697B7;
+    --color-brand-secondary-dark: #2A617F;
+    --color-brand-secondary-subtle: rgba(48, 123, 155, 0.08);
+    --color-brand-primary-hover: #DA5F00;
+    --color-brand-primary-active: #B94A00;
+    --color-brand-secondary-hover: #2A617F;
+    --color-brand-secondary-active: #22465F;
 
     --color-on-brand-primary: #FFFFFF;
     --color-on-brand-secondary: #FFFFFF;
 
-    --color-status-success: #14B8A6;
-    --color-status-success-light: #43C6B7;
-    --color-status-success-dark: #0E8074;
-    --color-status-success-subtle: #F0FDFA;
+    --color-status-success: #2ED573;
+    --color-status-success-light: #58F69E;
+    --color-status-success-dark: #298732;
+    --color-status-success-subtle: #E3FFEE;
     --color-status-error: #D14343;
-    --color-status-error-light: #DA6868;
-    --color-status-error-dark: #922E2E;
-    --color-status-error-subtle: #FEF2F2;
-    --color-status-warning: #FFB020;
-    --color-status-warning-light: #FFBF4C;
-    --color-status-warning-dark: #B27B16;
-    --color-status-warning-subtle: #FFFBEB;
+    --color-status-error-light: #E05254;
+    --color-status-error-dark: #A4221C;
+    --color-status-error-subtle: #FFF4F4;
+    --color-status-error-vivid: #FF4757;
+    --color-status-error-vivid-light: #FF6070;
+    --color-status-error-vivid-dark: #C42539;
+    --color-status-error-vivid-subtle: rgba(255, 71, 87, 0.12);
+    --color-status-error-vivid-rgb: 255, 71, 87;
+    --color-border-prominent: #9CA3AF;
+    --color-status-warning: #F9B415;
+    --color-status-warning-light: #FFD352;
+    --color-status-warning-dark: #C27400;
+    --color-status-warning-subtle: #FFF7DD;
     --color-status-info: #2196F3;
-    --color-status-info-light: #64B6F7;
-    --color-status-info-dark: #0B79D0;
-    --color-status-info-subtle: #F0F9FF;
+    --color-status-info-light: #78C2FF;
+    --color-status-info-dark: #1072CB;
+    --color-status-info-subtle: #EFF8FF;
 
     --color-on-status-success: #FFFFFF;
     --color-on-status-error: #FFFFFF;
@@ -248,10 +260,10 @@
 
     /* RGB decomposed values for glow shadows */
     --color-brand-primary-rgb: 255, 121, 0;
-    --color-brand-secondary-rgb: 64, 109, 135;
-    --color-status-success-rgb: 20, 184, 166;
+    --color-brand-secondary-rgb: 48, 123, 155;
+    --color-status-success-rgb: 46, 213, 115;
     --color-status-error-rgb: 209, 67, 67;
-    --color-status-warning-rgb: 255, 176, 32;
+    --color-status-warning-rgb: 249, 180, 21;
     --color-status-info-rgb: 33, 150, 243;
     --color-background-base-rgb: 16, 16, 16;
 

package/src/theme/gradients.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest'
+import { linearGradient, surfaceGradient } from './gradients'
+
+describe('gradients', () => {
+  it('builds a linear-gradient backgroundImage from two tokens (web CSS vars)', () => {
+    const style = linearGradient('surface-elevated', 'background-base', 180)
+    expect(style.backgroundImage).toBe(
+      'linear-gradient(180deg, var(--color-surface-elevated), var(--color-background-base))'
+    )
+  })
+
+  it('respects a custom angle', () => {
+    expect(linearGradient('surface-base', 'background-base', 90).backgroundImage).toContain('90deg')
+  })
+
+  it('defaults to a 180deg angle', () => {
+    expect(linearGradient('surface-base', 'background-base').backgroundImage).toContain('180deg')
+  })
+
+  it('surfaceGradient.chrome is the elevated → base chrome wash', () => {
+    expect(surfaceGradient.chrome().backgroundImage).toBe(
+      'linear-gradient(180deg, var(--color-surface-elevated), var(--color-background-base))'
+    )
+  })
+})

package/src/theme/gradients.ts

@@ -0,0 +1,36 @@
+import { resolveColor } from './resolve-color'
+import { getSemanticColors, type ThemeMode } from './tokens/semantic'
+
+type ColorToken = keyof ReturnType<typeof getSemanticColors>
+
+/** A `backgroundImage` style — web-only (RN ignores it); type it loosely for RN style arrays. */
+export type GradientStyle = { backgroundImage: string }
+
+/**
+ * A linear-gradient `backgroundImage` built from two semantic color tokens.
+ *
+ * Themeable + native-safe via {@link resolveColor}: on web the stops are CSS
+ * variables (light/dark switching keeps working); on native it resolves to hex.
+ * `backgroundImage` is a **web-only** paint, so pair this with a solid
+ * `bg-*` className fallback for native (see the shell TopBar).
+ */
+export function linearGradient(
+  from: ColorToken,
+  to: ColorToken,
+  angle = 180,
+  mode: ThemeMode = 'dark'
+): GradientStyle {
+  return {
+    backgroundImage: `linear-gradient(${angle}deg, ${resolveColor(from, mode)}, ${resolveColor(to, mode)})`,
+  }
+}
+
+/**
+ * Named surface gradients — the shared substrate for gradient fills. Replaces
+ * per-component inline `linear-gradient` strings.
+ */
+export const surfaceGradient = {
+  /** Chrome bands (top bar, headers): elevated → base, a subtle dark wash. */
+  chrome: (mode: ThemeMode = 'dark'): GradientStyle =>
+    linearGradient('surface-elevated', 'background-base', 180, mode),
+}

package/src/theme/index.ts

@@ -1,43 +1,8 @@
-// Theme exports
-export * from './tokens'
-export * from './config'
-export * from './shadows'
-export * from './elevation'
-export * from './manifest'
-export { ThemeProvider, type ThemeProviderProps, type ThemeProviderMode } from './ThemeProvider'
-export { resolveColor } from './resolve-color'
-
-// Re-export commonly used items
-export { getSemanticColors, type ThemeMode } from './tokens/semantic'
-export { getThemeCSSVars, gluestackConfig } from './config'
-export {
-  neumorphicShadows,
-  // Color math utilities (HSV-based)
-  lighten,
-  darken,
-  getHoverColors,
-  isDark,
-  hexToRgb,
-  rgbToHsv,
-  // Shadow creation functions
-  createRaisedShadow,
-  createRaisedHoverShadow,
-  createPressedShadow,
-  createPressedHoverShadow,
-  createFlatShadow,
-  shadowColors,
-  type ShadowIntensity,
-  type ShadowSurface,
-} from './shadows'
-export {
-  getElevationConfig,
-  getElevationSurface,
-  getElevationShadow,
-  getBaseSurfaceColor,
-  getValidatedElevation,
-  componentElevationRanges,
-  type ElevationLevel,
-  type ElevationConfig,
-  type ComponentType,
-} from './elevation'
-export * from './presets'
+// Theme subpath entry: @titan-design/react-ui/theme
+//
+// The full theme surface. This is the nativewind-free `./barrel` PLUS the
+// `ThemeProvider` value — which imports `nativewind` and therefore does NOT
+// belong on the root barrel (that split happened in titan 0.5.0). Native
+// consumers wrap their app root in `<ThemeProvider>` and import it from HERE.
+export * from './barrel'
+export { ThemeProvider } from './ThemeProvider'

package/src/theme/native-theming-guard.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { darkThemeCSSVars, lightThemeCSSVars } from './config'
+import { getSemanticColors } from './tokens/semantic'
+
+/**
+ * Native-theming guard (TD-04.11 / VW-20).
+ *
+ * On native, titan resolves colors two ways, and BOTH can silently render black
+ * if a token is undefined:
+ *   1. `className` (e.g. `text-text-secondary`) → tailwind config → a
+ *      `var(--color-*)` custom property that `ThemeProvider` registers at runtime
+ *      via nativewind `vars(darkThemeCSSVars)`. A tailwind color pointing at a var
+ *      the theme maps don't define is unset on native → black text/fill.
+ *   2. `resolveColor(token)` → `getSemanticColors(mode)[token]` hex on native /
+ *      `var(--color-${token})` on web. A token missing a hex value, or whose
+ *      `--color-<token>` var is undefined, renders black (native) or unset (web).
+ *
+ * This is the exact class of bug that shipped in the 09.33a swap and was only
+ * caught on-device. `config.completeness.test.ts` proves the theme maps mirror
+ * global.css (the definition side); this guard covers the USAGE side — every
+ * color token the design system references must resolve to a defined token in
+ * both modes. Static (no render), so it runs in the fast project.
+ */
+
+const require = createRequire(import.meta.url)
+const uiRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const tailwindConfig = require(path.join(uiRoot, 'tailwind.config.js')) as any
+const colorTree = tailwindConfig.theme?.extend?.colors ?? {}
+
+// Flatten the nested tailwind color tree into `class-suffix -> leaf value`.
+// `DEFAULT` collapses onto its parent (tailwind's `brand.primary.DEFAULT` -> the
+// `brand-primary` class).
+function flattenColors(
+  node: Record<string, unknown>,
+  prefix: string[] = [],
+): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(node)) {
+    const nextPrefix = key === 'DEFAULT' ? prefix : [...prefix, key]
+    if (value && typeof value === 'object') {
+      Object.assign(out, flattenColors(value as Record<string, unknown>, nextPrefix))
+    } else if (typeof value === 'string') {
+      out[nextPrefix.join('-')] = value
+    }
+  }
+  return out
+}
+
+const colorLeaves = flattenColors(colorTree)
+const definedDark = new Set(Object.keys(darkThemeCSSVars))
+const definedLight = new Set(Object.keys(lightThemeCSSVars))
+
+function varReference(value: string): string | null {
+  const match = value.match(/var\((--color-[a-z0-9-]+)\)/)
+  return match ? match[1] : null
+}
+
+// Accept hex, rgb/rgba, and hsl/hsla; reject empty/undefined. (No token should be
+// literally "#000"/"black" in these maps, but that's a design choice, not a
+// resolution bug, so we only assert a *valid, present* color here.)
+const VALID_COLOR = /^(#[0-9a-f]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\))$/i
+
+describe('native theming guard (no color token renders black on native)', () => {
+  it('sanity: tailwind colors and theme maps flattened to non-trivial sets', () => {
+    expect(Object.keys(colorLeaves).length).toBeGreaterThan(50)
+    expect(definedDark.size).toBeGreaterThan(90)
+    expect(definedLight.size).toBe(definedDark.size)
+  })
+
+  it('every tailwind color className resolves to a var defined in BOTH native vars maps', () => {
+    const undefinedDark: string[] = []
+    const undefinedLight: string[] = []
+    for (const [suffix, value] of Object.entries(colorLeaves)) {
+      const ref = varReference(value)
+      if (!ref) continue // literal color (nativewind preset default) — always resolves
+      if (!definedDark.has(ref)) undefinedDark.push(`${suffix} -> ${value}`)
+      if (!definedLight.has(ref)) undefinedLight.push(`${suffix} -> ${value}`)
+    }
+    expect(
+      undefinedDark,
+      'tailwind colors point at vars missing from darkThemeCSSVars (className renders black on native dark)',
+    ).toEqual([])
+    expect(
+      undefinedLight,
+      'tailwind colors point at vars missing from lightThemeCSSVars (className renders black on native light)',
+    ).toEqual([])
+  })
+
+  it('every resolveColor/getSemanticColors token has a valid hex AND a matching --color-<token> var', () => {
+    for (const mode of ['dark', 'light'] as const) {
+      const colors = getSemanticColors(mode)
+      const defined = mode === 'dark' ? definedDark : definedLight
+      const invalidValues: string[] = []
+      const missingVars: string[] = []
+      for (const [token, value] of Object.entries(colors)) {
+        if (typeof value !== 'string' || !VALID_COLOR.test(value)) {
+          invalidValues.push(`${token} = ${JSON.stringify(value)}`)
+        }
+        // resolveColor's web path returns `var(--color-${token})`; that var must exist.
+        if (!defined.has(`--color-${token}`)) missingVars.push(token)
+      }
+      expect(
+        invalidValues,
+        `getSemanticColors('${mode}') has tokens with no valid color (renders black/unset on native)`,
+      ).toEqual([])
+      expect(
+        missingVars,
+        `resolveColor tokens missing a --color-<token> in ${mode} vars (renders unset on web)`,
+      ).toEqual([])
+    }
+  })
+})