@titan-design/react-ui 0.12.0 → 0.13.0

package/src/theme/surface-planes.ts

@@ -0,0 +1,68 @@
+/**
+ * The surface planes: the grey-ramp steps a container can sit on, darkest first.
+ *
+ * Every background a `<Surface>` or `<Card>` paints resolves through this list,
+ * so a container can only ever land ON the ramp. Stepping up (a lifted card) or
+ * down (a pressed well) is indexing `PLANE_ORDER`, clamped at both ends.
+ *
+ * `frame` is the bezel the ramp sits inside and the floor a pressed surface
+ * clamps at. It replaced a separate `inset` level in TD-07.14: at ΔE 1.10 from
+ * the frame that level was an imperceptible duplicate.
+ */
+import { getSemanticColors, type ThemeMode } from './tokens/semantic'
+
+type ColorToken = keyof ReturnType<typeof getSemanticColors>
+
+export type SurfaceLevel = 'frame' | 'background' | 'base' | 'elevated' | 'raised' | 'overlay'
+
+// Which semantic token backs each plane. Values live in `semantic.ts` and stay
+// in sync with the grey ramp; this map never carries literal hexes.
+export const SURFACE_LEVEL_TOKEN = {
+  frame: 'background-frame',
+  background: 'background-base',
+  base: 'surface-base',
+  elevated: 'surface-elevated',
+  raised: 'surface-raised',
+  overlay: 'surface-overlay',
+} as const satisfies Record<SurfaceLevel, ColorToken>
+
+/** Darkest → lightest. Kept in lockstep with the grey ramp and surface.contract.test. */
+export const PLANE_ORDER = [
+  'frame',
+  'background',
+  'base',
+  'elevated',
+  'raised',
+  'overlay',
+] as const satisfies readonly SurfaceLevel[]
+
+/** The background hex for a plane under a theme mode (literal hex, never a var()). */
+export function surfaceBackground(level: SurfaceLevel, mode: ThemeMode): string {
+  return getSemanticColors(mode)[SURFACE_LEVEL_TOKEN[level]]
+}
+
+function stepPlane(from: SurfaceLevel, delta: number): SurfaceLevel {
+  const index = PLANE_ORDER.indexOf(from)
+  const clamped = Math.min(PLANE_ORDER.length - 1, Math.max(0, index + delta))
+  return PLANE_ORDER[clamped]
+}
+
+/**
+ * The plane a `<Surface pressed>` resolves to: its parent's plane stepped one
+ * index DOWN the ramp, clamped at the `frame` floor.
+ *   overlay→raised, raised→elevated, elevated→base, base→background,
+ *   background→frame, frame→frame (clamped).
+ */
+export function pressedLevel(parent: SurfaceLevel): SurfaceLevel {
+  return stepPlane(parent, -1)
+}
+
+/**
+ * The plane a lifted surface resolves to: its parent's plane stepped `steps`
+ * UP the ramp, clamped at `overlay`. The clamp is what makes raised-on-raised
+ * unrepresentable: a card inside an overlay stays on the overlay and relies on
+ * its lift treatment, never on a lighter grey that is not on the ramp.
+ */
+export function raisedLevel(parent: SurfaceLevel, steps: number): SurfaceLevel {
+  return stepPlane(parent, Math.max(0, steps))
+}

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

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

package/src/theme/tokens/primitives.test.ts

@@ -34,15 +34,17 @@ const mul = (M: number[], v: number[]) => [
 // Machado-2009 dichromacy simulation matrices, severity 1.0. The palette solver
 // optimizes worst-case deuteranopia/protanopia (red-green is the binding case) —
 // match that 2-way metric here, not a stricter 3-way including tritan.
-const DEUT = [0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.01182, 0.04294, 0.968881]
-const PROT = [0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998]
+const DEUT = [
+  0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.01182, 0.04294, 0.968881,
+]
+const PROT = [
+  0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998,
+]
 const dist = (a: number[], b: number[]) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]) * 100
 // worst-case perceived ΔE across deuteranopia and protanopia
 const cvdDelta = (x: string, y: string) => {
   const sim = (M: number[], hex: string) => toOklab(mul(M, hexToRgb(hex).map(lin)))
-  return Math.min(
-    ...[DEUT, PROT].map((M) => dist(sim(M, x), sim(M, y))),
-  )
+  return Math.min(...[DEUT, PROT].map((M) => dist(sim(M, x), sim(M, y))))
 }
 
 const HEX6 = /^#[0-9A-F]{6}$/
@@ -115,7 +117,10 @@ describe('categoricalPalette', () => {
           worst = Math.min(worst, cvdDelta(colors[i], colors[j]))
         }
       }
-      expect(worst, `${variant} min CVD deltaE (first ${CATEGORICAL_CVD_SAFE_MAX})`).toBeGreaterThanOrEqual(8)
+      expect(
+        worst,
+        `${variant} min CVD deltaE (first ${CATEGORICAL_CVD_SAFE_MAX})`
+      ).toBeGreaterThanOrEqual(8)
     }
   })
 
@@ -212,7 +217,10 @@ describe('sequentialEffort', () => {
 
   it('keeps adjacent stops distinguishable', () => {
     for (let i = 0; i < sequentialEffort.length - 1; i++) {
-      expect(cvdDelta(sequentialEffort[i], sequentialEffort[i + 1]), `stop ${i}->${i + 1}`).toBeGreaterThanOrEqual(4.5)
+      expect(
+        cvdDelta(sequentialEffort[i], sequentialEffort[i + 1]),
+        `stop ${i}->${i + 1}`
+      ).toBeGreaterThanOrEqual(4.5)
     }
   })
 

package/src/theme/tokens/primitives.ts

@@ -19,6 +19,18 @@ export const primitiveColors = {
   transparent: 'transparent',
 } as const
 
+/**
+ * The vivid alert red: the one chromatic anchor outside the OKLCH ramps.
+ *
+ * It survived the TD-07.14 fold of the old `redVivid` scale only as the
+ * `-rgb`, `-subtle` and glow encodings of `status-error-vivid`, while the token
+ * itself was pinned to `red[600]` and collapsed onto `status-error`. Owning it
+ * here means the semantic layer references a primitive instead of carrying a
+ * literal. The red ramp has no step this saturated, and adding one means
+ * regenerating the ramp, so it stays a pin.
+ */
+export const alertRedVivid = '#FF4757' as const
+
 /**
  * Unified warm-neutral grey ramp (TD-07.14)
  *
@@ -48,7 +60,7 @@ export const primitiveColors = {
  * (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/
+ * sources/design/foundations/warm-grey-ramp/
  */
 export const greyRamp = {
   50: '#F9F6F3', //  L*97.0  W6
@@ -90,7 +102,7 @@ export const SURFACE_PLANE_STEPS = {
  * hexes. `pin` marks the step each ramp flows through its anchor.
  * This is the single source of truth for chromatic hexes — the categorical palette
  * below references these steps rather than duplicating values.
- * See coordination/design-explorations/foundations.
+ * See sources/design/foundations.
  */
 export const primitiveRamps = {
   red: {
@@ -244,7 +256,10 @@ export type CategoricalVariant = keyof typeof categoricalPalette
  * @param variant - `default` (black-text / light surfaces) or `dark` (white text)
  * @returns The hex color string
  */
-export function getCategoricalColor(index: number, variant: CategoricalVariant = 'default'): string {
+export function getCategoricalColor(
+  index: number,
+  variant: CategoricalVariant = 'default'
+): string {
   const palette = categoricalPalette[variant]
   index = Math.max(0, Math.floor(index))
   return palette[index % palette.length]
@@ -387,21 +402,38 @@ export function getDiscreteRainbowColor(index: number, size: number): string {
 
 export const primitiveTypography = {
   fontFamilies: {
-    sans: ['Inter', '-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'Helvetica', 'Arial', 'sans-serif'],
+    sans: [
+      'Inter',
+      '-apple-system',
+      'BlinkMacSystemFont',
+      'Segoe UI',
+      'Helvetica',
+      'Arial',
+      'sans-serif',
+    ],
     body: ['Nunito Sans', 'sans-serif'],
     heading: ['Space Grotesk', 'sans-serif'],
-    mono: ['SF Mono', 'Monaco', 'Inconsolata', 'Fira Mono', 'Droid Sans Mono', 'Source Code Pro', 'monospace'],
+    mono: [
+      'SF Mono',
+      'Monaco',
+      'Inconsolata',
+      'Fira Mono',
+      'Droid Sans Mono',
+      'Source Code Pro',
+      'monospace',
+    ],
   },
   fontSizes: {
-    xs: '0.75rem',    // 12px
-    sm: '0.875rem',   // 14px
-    base: '1rem',     // 16px
-    lg: '1.125rem',   // 18px
-    xl: '1.5rem',     // 24px
-    '2xl': '2rem',    // 32px
+    '2xs': '0.625rem', // 10px
+    xs: '0.75rem', // 12px
+    sm: '0.875rem', // 14px
+    base: '1rem', // 16px
+    lg: '1.125rem', // 18px
+    xl: '1.5rem', // 24px
+    '2xl': '2rem', // 32px
     '3xl': '2.25rem', // 36px
-    '4xl': '3rem',    // 48px
-    '5xl': '3.5rem',  // 56px
+    '4xl': '3rem', // 48px
+    '5xl': '3.5rem', // 56px
   },
   fontWeights: {
     normal: 400,
@@ -430,28 +462,28 @@ export const primitiveTypography = {
 export const primitiveSpacing = {
   0: '0',
   px: '1px',
-  0.5: '0.125rem',  // 2px
-  1: '0.25rem',     // 4px
-  1.5: '0.375rem',  // 6px
-  2: '0.5rem',      // 8px
-  2.5: '0.625rem',  // 10px
-  3: '0.75rem',     // 12px
-  3.5: '0.875rem',  // 14px
-  4: '1rem',        // 16px
-  5: '1.25rem',     // 20px
-  6: '1.5rem',      // 24px
-  7: '1.75rem',     // 28px
-  8: '2rem',        // 32px
-  9: '2.25rem',     // 36px
-  10: '2.5rem',     // 40px
-  11: '2.75rem',    // 44px
-  12: '3rem',       // 48px
-  14: '3.5rem',     // 56px
-  16: '4rem',       // 64px
-  20: '5rem',       // 80px
-  24: '6rem',       // 96px
-  28: '7rem',       // 112px
-  32: '8rem',       // 128px
+  0.5: '0.125rem', // 2px
+  1: '0.25rem', // 4px
+  1.5: '0.375rem', // 6px
+  2: '0.5rem', // 8px
+  2.5: '0.625rem', // 10px
+  3: '0.75rem', // 12px
+  3.5: '0.875rem', // 14px
+  4: '1rem', // 16px
+  5: '1.25rem', // 20px
+  6: '1.5rem', // 24px
+  7: '1.75rem', // 28px
+  8: '2rem', // 32px
+  9: '2.25rem', // 36px
+  10: '2.5rem', // 40px
+  11: '2.75rem', // 44px
+  12: '3rem', // 48px
+  14: '3.5rem', // 56px
+  16: '4rem', // 64px
+  20: '5rem', // 80px
+  24: '6rem', // 96px
+  28: '7rem', // 112px
+  32: '8rem', // 128px
 } as const
 
 export const primitiveBorderRadius = {

package/src/theme/tokens/semantic.ts

@@ -17,7 +17,13 @@
  * - interactive-* : Hover/focus/active/disabled states
  */
 
-import { primitiveColors as p, primitiveRamps as ramp, greyRamp, discreteRainbow } from './primitives'
+import {
+  primitiveColors as p,
+  primitiveRamps as ramp,
+  greyRamp,
+  discreteRainbow,
+  alertRedVivid,
+} from './primitives'
 
 /**
  * GREY MAPPING (TD-07.14) — how the old cool scales resolved onto `greyRamp`.
@@ -53,6 +59,8 @@ export const semanticColorsLight = {
   'brand-primary-light': ramp.orange[300],
   'brand-primary-dark': ramp.orange[500],
   'brand-primary-subtle': 'rgba(255, 121, 0, 0.08)',
+  'brand-primary-muted': 'rgba(255, 121, 0, 0.30)',
+  'brand-primary-strong': 'rgba(255, 121, 0, 0.50)',
   'brand-primary-hover': ramp.orange[500],
   'brand-primary-active': ramp.orange[600],
 
@@ -60,6 +68,8 @@ export const semanticColorsLight = {
   'brand-secondary-light': ramp.cyan[500],
   'brand-secondary-dark': ramp.cyan[700],
   'brand-secondary-subtle': 'rgba(48, 123, 155, 0.08)',
+  'brand-secondary-muted': 'rgba(48, 123, 155, 0.30)',
+  'brand-secondary-strong': 'rgba(48, 123, 155, 0.50)',
   'brand-secondary-hover': ramp.cyan[700],
   'brand-secondary-active': ramp.cyan[800],
 
@@ -72,6 +82,8 @@ export const semanticColorsLight = {
   'status-success-light': ramp.green[200],
   'status-success-dark': ramp.green[600],
   'status-success-subtle': ramp.green[50],
+  'status-success-muted': 'rgba(46, 213, 115, 0.30)',
+  'status-success-strong': 'rgba(46, 213, 115, 0.50)',
 
   // Live-session accent — its OWN role, decoupled from success so the two can diverge
   'status-live': ramp.green[300],
@@ -81,21 +93,29 @@ export const semanticColorsLight = {
   'status-error-light': ramp.red[500],
   'status-error-dark': ramp.red[700],
   'status-error-subtle': ramp.red[50],
+  'status-error-muted': 'rgba(209, 67, 67, 0.30)',
+  'status-error-strong': 'rgba(209, 67, 67, 0.50)',
 
-  'status-error-vivid': ramp.red[600],     // vivid alert red
+  'status-error-vivid': alertRedVivid, // NOT red[600], that is status-error
   'status-error-vivid-light': ramp.red[500],
   'status-error-vivid-dark': ramp.red[700],
   'status-error-vivid-subtle': 'rgba(255, 71, 87, 0.12)',
+  'status-error-vivid-muted': 'rgba(255, 71, 87, 0.30)',
+  'status-error-vivid-strong': 'rgba(255, 71, 87, 0.50)',
 
   'status-warning': ramp.amber[300],
   'status-warning-light': ramp.amber[200],
   'status-warning-dark': ramp.amber[500],
   'status-warning-subtle': ramp.amber[50],
+  'status-warning-muted': 'rgba(249, 180, 21, 0.30)',
+  'status-warning-strong': 'rgba(249, 180, 21, 0.50)',
 
   'status-info': ramp.blue[500],
   'status-info-light': ramp.blue[300],
   'status-info-dark': ramp.blue[600],
   'status-info-subtle': ramp.blue[50],
+  'status-info-muted': 'rgba(33, 150, 243, 0.30)',
+  'status-info-strong': 'rgba(33, 150, 243, 0.50)',
 
   // Text on status backgrounds (on-status-*)
   'on-status-success': p.white,
@@ -104,15 +124,15 @@ export const semanticColorsLight = {
   'on-status-info': p.white,
 
   // Result/outcome indicators (result-*)
-  'result-improve': '#4caf50',                // Green - positive outcome
+  'result-improve': '#4caf50', // Green - positive outcome
   'result-improve-light': 'rgba(76, 175, 80, 0.12)',
   'result-improve-dark': '#248a24',
-  'result-degrade': '#ef5350',                // Red - negative outcome
+  'result-degrade': '#ef5350', // Red - negative outcome
   'result-degrade-light': 'rgba(239, 83, 80, 0.12)',
   'result-degrade-dark': '#b30000',
-  'result-inconclusive': '#9E9A97',           // Gray - no clear result
+  'result-inconclusive': '#9E9A97', // Gray - no clear result
   'result-inconclusive-light': 'rgba(158, 154, 151, 0.12)',
-  'result-neutral': greyRamp[600],           // Neutral baseline
+  'result-neutral': greyRamp[600], // Neutral baseline
 
   // Text on result backgrounds (on-result-*)
   'on-result-improve': p.white,
@@ -121,16 +141,16 @@ export const semanticColorsLight = {
 
   // Data visualization colors (data-*)
   // First 10 colors from discrete rainbow optimized for charts
-  'data-1': discreteRainbow[9],               // Blue
-  'data-2': discreteRainbow[14],              // Green
-  'data-3': discreteRainbow[17],              // Yellow
-  'data-4': discreteRainbow[25],              // Red
-  'data-5': discreteRainbow[8],               // Purple
-  'data-6': discreteRainbow[20],              // Orange
-  'data-7': discreteRainbow[13],              // Light Blue
-  'data-8': discreteRainbow[15],              // Light Green
-  'data-9': discreteRainbow[3],               // Lavender
-  'data-10': discreteRainbow[22],             // Dark Orange
+  'data-1': discreteRainbow[9], // Blue
+  'data-2': discreteRainbow[14], // Green
+  'data-3': discreteRainbow[17], // Yellow
+  'data-4': discreteRainbow[25], // Red
+  'data-5': discreteRainbow[8], // Purple
+  'data-6': discreteRainbow[20], // Orange
+  'data-7': discreteRainbow[13], // Light Blue
+  'data-8': discreteRainbow[15], // Light Green
+  'data-9': discreteRainbow[3], // Lavender
+  'data-10': discreteRainbow[22], // Dark Orange
 
   // Text colors (text-*)
   'text-primary': '#121828',
@@ -143,10 +163,10 @@ export const semanticColorsLight = {
 
   // Surface colors (surface-*) - for elevated containers
   'surface-base': p.white,
-  'surface-elevated': greyRamp[50],          // slightly off-white for elevated cards
-  'surface-raised': greyRamp[100],           // light gray for raised cards
+  'surface-elevated': greyRamp[50], // slightly off-white for elevated cards
+  'surface-raised': greyRamp[100], // light gray for raised cards
   'surface-overlay': p.white,
-  'surface-input': greyRamp[50],             // Input field background (filled variant)
+  'surface-input': greyRamp[50], // Input field background (filled variant)
 
   // Background colors (background-*)
   'background-base': '#EBEBEB',
@@ -157,12 +177,12 @@ export const semanticColorsLight = {
   'background-frame': greyRamp[400],
 
   // Border colors (border-*)
-  'border-prominent': greyRamp[400],        // high-visibility divider
+  'border-prominent': greyRamp[400], // high-visibility divider
   'border-focus': ramp.blue[600],
-  'border-input': greyRamp[200],             // Input field border
-  'border-input-hover': greyRamp[400],       // Input field border on hover
-  'border-input-focus': ramp.blue[600],          // Input field border on focus
-  'border-input-error': ramp.red[600],           // Input field border on error
+  'border-input': greyRamp[200], // Input field border
+  'border-input-hover': greyRamp[400], // Input field border on hover
+  'border-input-focus': ramp.blue[600], // Input field border on focus
+  'border-input-error': ramp.red[600], // Input field border on error
 
   // Alpha hairline separators (surface-independent — composite toward black on
   // light surfaces, mirroring the dark-mode white-alpha family). See §4/S-2.
@@ -179,7 +199,7 @@ export const semanticColorsLight = {
   'interactive-disabled-text': 'rgba(55, 65, 81, 0.26)',
 
   // Divider
-  'divider': '#E8E9EB',
+  divider: '#E8E9EB',
 
   // Avatar default
   'avatar-background': greyRamp[600],
@@ -193,6 +213,8 @@ export const semanticColorsDark = {
   'brand-primary-light': ramp.orange[300],
   'brand-primary-dark': ramp.orange[500],
   'brand-primary-subtle': 'rgba(255, 121, 0, 0.12)',
+  'brand-primary-muted': 'rgba(255, 121, 0, 0.30)',
+  'brand-primary-strong': 'rgba(255, 121, 0, 0.50)',
   'brand-primary-hover': ramp.orange[300],
   'brand-primary-active': ramp.orange[200],
 
@@ -200,6 +222,8 @@ export const semanticColorsDark = {
   'brand-secondary-light': ramp.cyan[500],
   'brand-secondary-dark': ramp.cyan[700],
   'brand-secondary-subtle': 'rgba(48, 123, 155, 0.12)',
+  'brand-secondary-muted': 'rgba(48, 123, 155, 0.30)',
+  'brand-secondary-strong': 'rgba(48, 123, 155, 0.50)',
   'brand-secondary-hover': ramp.cyan[500],
   'brand-secondary-active': ramp.cyan[400],
 
@@ -212,6 +236,8 @@ export const semanticColorsDark = {
   'status-success-light': ramp.green[200],
   'status-success-dark': ramp.green[600],
   'status-success-subtle': 'rgba(46, 213, 115, 0.12)',
+  'status-success-muted': 'rgba(46, 213, 115, 0.30)',
+  'status-success-strong': 'rgba(46, 213, 115, 0.50)',
 
   // Live-session accent — its OWN role, decoupled from success so the two can diverge
   'status-live': ramp.green[300],
@@ -221,21 +247,29 @@ export const semanticColorsDark = {
   'status-error-light': ramp.red[500],
   'status-error-dark': ramp.red[700],
   'status-error-subtle': 'rgba(209, 67, 67, 0.12)',
+  'status-error-muted': 'rgba(209, 67, 67, 0.30)',
+  'status-error-strong': 'rgba(209, 67, 67, 0.50)',
 
-  'status-error-vivid': ramp.red[600],
+  'status-error-vivid': alertRedVivid,
   'status-error-vivid-light': ramp.red[500],
   'status-error-vivid-dark': ramp.red[700],
   'status-error-vivid-subtle': 'rgba(255, 71, 87, 0.12)',
+  'status-error-vivid-muted': 'rgba(255, 71, 87, 0.30)',
+  'status-error-vivid-strong': 'rgba(255, 71, 87, 0.50)',
 
   'status-warning': ramp.amber[300],
   'status-warning-light': ramp.amber[200],
   'status-warning-dark': ramp.amber[500],
   'status-warning-subtle': 'rgba(249, 180, 21, 0.12)',
+  'status-warning-muted': 'rgba(249, 180, 21, 0.30)',
+  'status-warning-strong': 'rgba(249, 180, 21, 0.50)',
 
   'status-info': ramp.blue[500],
   'status-info-light': ramp.blue[300],
   'status-info-dark': ramp.blue[600],
   'status-info-subtle': 'rgba(33, 150, 243, 0.12)',
+  'status-info-muted': 'rgba(33, 150, 243, 0.30)',
+  'status-info-strong': 'rgba(33, 150, 243, 0.50)',
 
   // Text on status backgrounds
   'on-status-success': p.white,
@@ -295,20 +329,20 @@ export const semanticColorsDark = {
   // `background-base` backs `Surface level="background"` (SurfaceContext.SURFACE_LEVEL_TOKEN),
   // so it takes the ramp's shell role. The deepest plane is `background-frame`,
   // which is also the `SurfaceLevel` floor a pressed surface clamps at.
-  'surface-base': greyRamp[925],           // main surface        (#252321, L*13.9)
-  'surface-elevated': greyRamp[900],       // elevated surface     (#2C2A28, L*17.2 — nav/rail)
-  'surface-raised': greyRamp[875],         // raised surface       (#31302F, L*19.9 — cards)
-  'surface-overlay': greyRamp[850],        // overlay surface      (#373635, L*22.7 — hero/popover)
-  'surface-input': greyRamp[900],          // input surface        (#2C2A28 — one plane above base)
+  'surface-base': greyRamp[925], // main surface        (#252321, L*13.9)
+  'surface-elevated': greyRamp[900], // elevated surface     (#2C2A28, L*17.2 — nav/rail)
+  'surface-raised': greyRamp[875], // raised surface       (#31302F, L*19.9 — cards)
+  'surface-overlay': greyRamp[850], // overlay surface      (#373635, L*22.7 — hero/popover)
+  'surface-input': greyRamp[900], // input surface        (#2C2A28 — one plane above base)
 
   // Background colors — same ramp, the frame/shell end of it.
-  'background-base': greyRamp[950],        // shell                (#1C1916, L*9   — Surface level="background")
-  'background-default': greyRamp[925],     // main background      (#252321, L*13.9 — matches surface-base)
-  'background-subtle': greyRamp[900],      // subtle background    (#2C2A28, L*17.2 — matches surface-elevated)
+  'background-base': greyRamp[950], // shell                (#1C1916, L*9   — Surface level="background")
+  'background-default': greyRamp[925], // main background      (#252321, L*13.9 — matches surface-base)
+  'background-subtle': greyRamp[900], // subtle background    (#2C2A28, L*17.2 — matches surface-elevated)
   // Frame/bezel chrome — the top bar + side nav shell, one step BELOW
   // `background-base`. It used to be described as sitting OUTSIDE the ramp; it
   // is simply the ramp's last step now, and the floor `<Surface pressed>` clamps at.
-  'background-frame': greyRamp[975],       // frame / bezel        (#100D0A, L*3.8)
+  'background-frame': greyRamp[975], // frame / bezel        (#100D0A, L*3.8)
 
   // Border colors — solid dark borders are RETIRED (TD-07.14). Not a preference — a structural
   // consequence of one ramp. Every step from 850 to 975 is now a surface plane,
@@ -326,7 +360,7 @@ export const semanticColorsDark = {
   // `border-prominent` stays SOLID: it is the one border meant to be seen
   // outright (4 call sites, high-visibility dividers), and grey-800 is not a
   // plane, so it keeps its job without collision.
-  'border-prominent': greyRamp[800],     // high-visibility divider
+  'border-prominent': greyRamp[800], // high-visibility divider
   'border-focus': '#828DF8',
   'border-input': greyRamp[700],
   'border-input-hover': greyRamp[600],
@@ -376,7 +410,7 @@ export const semanticColorsDark = {
   'interactive-disabled-text': 'rgba(255, 255, 255, 0.26)',
 
   // Divider
-  'divider': 'rgba(255, 255, 255, 0.09)',
+  divider: 'rgba(255, 255, 255, 0.09)',
 
   // Avatar default
   'avatar-background': greyRamp[700],