@titan-design/react-ui 0.12.1 → 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

@@ -82,9 +82,7 @@ describe('token-only subpath export (TP-16)', () => {
 
   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}/`)),
-    )
+    const leaked = bare.filter((s) => FORBIDDEN.some((f) => s === f || s.startsWith(`${f}/`)))
     expect(leaked).toEqual([])
   })
 

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)
  *
@@ -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],

package/src/theme/wash-ladder.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { semanticColorsDark, semanticColorsLight } from './tokens/semantic'
+
+/**
+ * Status and brand roles publish three wash rungs. They exist so a component can
+ * express a weight ramp without hand-mixing alpha: MesoProgressBar's segment
+ * track collapsed to one weight in three hues when only `-subtle` was available.
+ *
+ * A rung that drifts out of order silently flattens every consumer, and the
+ * consumer's own test cannot catch it — under the RNW vitest alias the rendered
+ * value is a `var(...)` reference, not an rgba triplet.
+ */
+const WASH_ROLES = [
+  'brand-primary',
+  'brand-secondary',
+  'status-success',
+  'status-error',
+  'status-error-vivid',
+  'status-warning',
+  'status-info',
+] as const
+
+const RUNGS = ['subtle', 'muted', 'strong'] as const
+
+function alphaOf(value: string): number {
+  const parts = value.match(/rgba?\(([^)]+)\)/)?.[1].split(',')
+  if (!parts) return 1 // a solid ramp pin is fully opaque
+  return parts.length === 4 ? Number(parts[3].trim()) : 1
+}
+
+describe('wash ladder', () => {
+  for (const [mode, palette] of [
+    ['dark', semanticColorsDark],
+    ['light', semanticColorsLight],
+  ] as const) {
+    describe(mode, () => {
+      for (const role of WASH_ROLES) {
+        it(`${role} publishes all three rungs`, () => {
+          for (const rung of RUNGS) {
+            expect(palette, `${role}-${rung} is missing`).toHaveProperty(`${role}-${rung}`)
+          }
+        })
+      }
+    })
+  }
+
+  // Light mode's `-subtle` is still a solid ramp tint rather than a wash, so its
+  // ladder is not comparable yet. AW-121 owns bringing light onto this model.
+  for (const role of WASH_ROLES) {
+    it(`${role} rungs ascend in weight (dark)`, () => {
+      const [subtle, muted, strong] = RUNGS.map((r) =>
+        alphaOf(semanticColorsDark[`${role}-${r}` as keyof typeof semanticColorsDark] as string)
+      )
+      expect(muted, `${role}-muted must outweigh -subtle`).toBeGreaterThan(subtle)
+      expect(strong, `${role}-strong must outweigh -muted`).toBeGreaterThan(muted)
+    })
+  }
+})

package/src/theme/workout-tokens.ts

@@ -48,13 +48,7 @@ export const WORKOUT_TOKENS = {
     over2: ramp.red[700],
     over3: ramp.red[800],
     targetLine: 'rgba(33, 150, 243, 0.5)',
-    atTargetGlow:
-      '0 0 5px 1px rgba(33, 150, 243, 0.35), 0 0 10px 3px rgba(33, 150, 243, 0.15)',
-  },
-
-  // Placeholder strip
-  placeholder: {
-    fill: '#3A3A3A',
+    atTargetGlow: '0 0 5px 1px rgba(33, 150, 243, 0.35), 0 0 10px 3px rgba(33, 150, 243, 0.15)',
   },
 
   // Deviation bar

package/src/types/jest-axe.d.ts

@@ -5,12 +5,8 @@ declare module 'jest-axe' {
   ): Promise<{ violations: unknown[] }>
 
   export const toHaveNoViolations: {
-    toHaveNoViolations(
-      results: { violations: unknown[] }
-    ): { pass: boolean; message(): string }
+    toHaveNoViolations(results: { violations: unknown[] }): { pass: boolean; message(): string }
   }
 
-  export function configureAxe(
-    options?: Record<string, unknown>
-  ): typeof axe
+  export function configureAxe(options?: Record<string, unknown>): typeof axe
 }

package/src/types/raw-md.d.ts

@@ -0,0 +1,5 @@
+/** Vite's `?raw` suffix — imports a file's contents as a string. */
+declare module '*.md?raw' {
+  const content: string
+  export default content
+}

package/src/utils/colors.ts

@@ -1,8 +1,9 @@
 /**
- * Color utility functions for the design system
+ * Color utility functions for the design system.
  *
- * lighten/darken are re-exported from shadows.ts which uses HSV-based
- * color math for more perceptually consistent results across hues.
+ * `lighten`/`darken` are re-exported from `theme/color-utils`, which does the
+ * HSV math. They are hover/state adjustments, not a depth ladder — planes come
+ * from the grey ramp.
  */
 
 export { lighten, darken } from '../theme/color-utils'
@@ -137,4 +138,3 @@ export function getLuminance(color: string): 'light' | 'dark' {
 export function getContrastText(backgroundColor: string): string {
   return getLuminance(backgroundColor) === 'light' ? '#000000' : '#FFFFFF'
 }
-

package/src/utils/form.ts

@@ -160,9 +160,7 @@ export const validationRules = {
 /**
  * Compose multiple validation functions
  */
-export function composeValidators(
-  ...validators: Array<(value: any) => string | undefined>
-) {
+export function composeValidators(...validators: Array<(value: any) => string | undefined>) {
   return (value: any): string | undefined => {
     for (const validator of validators) {
       const error = validator(value)