@titan-design/react-ui 0.12.0 → 0.13.0

package/src/theme/global.css

@@ -19,10 +19,14 @@
     --color-brand-primary-light: #FFA063;
     --color-brand-primary-dark: #DA5F00;
     --color-brand-primary-subtle: rgba(255, 121, 0, 0.12);
+    --color-brand-primary-muted: rgba(255, 121, 0, 0.30);
+    --color-brand-primary-strong: rgba(255, 121, 0, 0.50);
     --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-secondary-muted: rgba(48, 123, 155, 0.30);
+    --color-brand-secondary-strong: rgba(48, 123, 155, 0.50);
     --color-brand-primary-hover: #FFA063;
     --color-brand-primary-active: #FFC7A2;
     --color-brand-secondary-hover: #2697B7;
@@ -35,26 +39,36 @@
     --color-status-success-light: #58F69E;
     --color-status-success-dark: #298732;
     --color-status-success-subtle: rgba(46, 213, 115, 0.12);
+    --color-status-success-muted: rgba(46, 213, 115, 0.30);
+    --color-status-success-strong: rgba(46, 213, 115, 0.50);
     --color-status-live: #2ED573;
     --color-status-live-muted: #22A444;
     --color-status-error: #D14343;
     --color-status-error-light: #E05254;
     --color-status-error-dark: #A4221C;
     --color-status-error-subtle: rgba(209, 67, 67, 0.12);
-    --color-status-error-vivid: #D14343;
+    --color-status-error-muted: rgba(209, 67, 67, 0.30);
+    --color-status-error-strong: rgba(209, 67, 67, 0.50);
+    --color-status-error-vivid: #FF4757;
     --color-status-error-vivid-light: #E05254;
     --color-status-error-vivid-dark: #A4221C;
     --color-status-error-vivid-subtle: rgba(255, 71, 87, 0.12);
+    --color-status-error-vivid-muted: rgba(255, 71, 87, 0.30);
+    --color-status-error-vivid-strong: rgba(255, 71, 87, 0.50);
     --color-status-error-vivid-rgb: 255, 71, 87;
     --color-border-prominent: #424140;
     --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-warning-muted: rgba(249, 180, 21, 0.30);
+    --color-status-warning-strong: rgba(249, 180, 21, 0.50);
     --color-status-info: #2196F3;
     --color-status-info-light: #78C2FF;
     --color-status-info-dark: #1072CB;
     --color-status-info-subtle: rgba(33, 150, 243, 0.12);
+    --color-status-info-muted: rgba(33, 150, 243, 0.30);
+    --color-status-info-strong: rgba(33, 150, 243, 0.50);
 
     --color-on-status-success: #FFFFFF;
     --color-on-status-error: #FFFFFF;
@@ -171,10 +185,14 @@
     --color-brand-primary-light: #FFA063;
     --color-brand-primary-dark: #DA5F00;
     --color-brand-primary-subtle: rgba(255, 121, 0, 0.08);
+    --color-brand-primary-muted: rgba(255, 121, 0, 0.30);
+    --color-brand-primary-strong: rgba(255, 121, 0, 0.50);
     --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-secondary-muted: rgba(48, 123, 155, 0.30);
+    --color-brand-secondary-strong: rgba(48, 123, 155, 0.50);
     --color-brand-primary-hover: #DA5F00;
     --color-brand-primary-active: #B94A00;
     --color-brand-secondary-hover: #2A617F;
@@ -187,26 +205,36 @@
     --color-status-success-light: #58F69E;
     --color-status-success-dark: #298732;
     --color-status-success-subtle: #E3FFEE;
+    --color-status-success-muted: rgba(46, 213, 115, 0.30);
+    --color-status-success-strong: rgba(46, 213, 115, 0.50);
     --color-status-live: #2ED573;
     --color-status-live-muted: #22A444;
     --color-status-error: #D14343;
     --color-status-error-light: #E05254;
     --color-status-error-dark: #A4221C;
     --color-status-error-subtle: #FFF4F4;
-    --color-status-error-vivid: #D14343;
+    --color-status-error-muted: rgba(209, 67, 67, 0.30);
+    --color-status-error-strong: rgba(209, 67, 67, 0.50);
+    --color-status-error-vivid: #FF4757;
     --color-status-error-vivid-light: #E05254;
     --color-status-error-vivid-dark: #A4221C;
     --color-status-error-vivid-subtle: rgba(255, 71, 87, 0.12);
+    --color-status-error-vivid-muted: rgba(255, 71, 87, 0.30);
+    --color-status-error-vivid-strong: rgba(255, 71, 87, 0.50);
     --color-status-error-vivid-rgb: 255, 71, 87;
     --color-border-prominent: #A29F9D;
     --color-status-warning: #F9B415;
     --color-status-warning-light: #FFD352;
     --color-status-warning-dark: #C27400;
     --color-status-warning-subtle: #FFF7DD;
+    --color-status-warning-muted: rgba(249, 180, 21, 0.30);
+    --color-status-warning-strong: rgba(249, 180, 21, 0.50);
     --color-status-info: #2196F3;
     --color-status-info-light: #78C2FF;
     --color-status-info-dark: #1072CB;
     --color-status-info-subtle: #EFF8FF;
+    --color-status-info-muted: rgba(33, 150, 243, 0.30);
+    --color-status-info-strong: rgba(33, 150, 243, 0.50);
 
     --color-on-status-success: #FFFFFF;
     --color-on-status-error: #FFFFFF;

package/src/theme/grey-ramp.test.ts

@@ -11,7 +11,6 @@ import { execFileSync } from 'node:child_process'
 import { join } from 'node:path'
 import { greyRamp, SURFACE_PLANE_STEPS, primitiveRamps } from './tokens/primitives'
 
-
 // ── colour math (CIELAB D65 + WCAG relative luminance) ──────────────────────
 const hex2rgb = (h: string): [number, number, number] => {
   const n = parseInt(h.slice(1), 16)
@@ -42,9 +41,15 @@ const warmth = (hex: string) => {
 
 /** Machado-2009 dichromacy, severity 1.0. */
 const CVD = {
-  deuteranopia: [0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.01182, 0.04294, 0.968881],
-  protanopia: [0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998],
-  tritanopia: [1.255528, -0.076749, -0.178779, -0.078411, 0.930809, 0.147602, 0.004733, 0.691367, 0.3039],
+  deuteranopia: [
+    0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.01182, 0.04294, 0.968881,
+  ],
+  protanopia: [
+    0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998,
+  ],
+  tritanopia: [
+    1.255528, -0.076749, -0.178779, -0.078411, 0.930809, 0.147602, 0.004733, 0.691367, 0.3039,
+  ],
 } as const
 function simulateCvd(m: readonly number[], hex: string): string {
   const [r, g, b] = hex2rgb(hex)
@@ -56,13 +61,19 @@ function simulateCvd(m: readonly number[], hex: string): string {
   return (
     '#' +
     out
-      .map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, '0'))
+      .map((v) =>
+        Math.round(Math.max(0, Math.min(255, v)))
+          .toString(16)
+          .padStart(2, '0')
+      )
       .join('')
       .toUpperCase()
   )
 }
 
-const STEPS = Object.keys(greyRamp).map(Number).sort((a, b) => a - b)
+const STEPS = Object.keys(greyRamp)
+  .map(Number)
+  .sort((a, b) => a - b)
 const hexAt = (step: number) => greyRamp[step as keyof typeof greyRamp]
 
 describe('greyRamp — shape', () => {
@@ -82,7 +93,9 @@ describe('greyRamp — shape', () => {
   it('has no two steps a reader could not tell apart', () => {
     for (let i = 1; i < STEPS.length; i++) {
       const d = dE76(hexAt(STEPS[i - 1]), hexAt(STEPS[i]))
-      expect(d, `steps ${STEPS[i - 1]}/${STEPS[i]} collapse at ΔE ${d.toFixed(2)}`).toBeGreaterThan(1.5)
+      expect(d, `steps ${STEPS[i - 1]}/${STEPS[i]} collapse at ΔE ${d.toFixed(2)}`).toBeGreaterThan(
+        1.5
+      )
     }
   })
 
@@ -150,7 +163,10 @@ describe('greyRamp — accessibility gate (TD-07.15)', () => {
       // Adjacent steps must stay separable AFTER simulation, or the depth
       // ordering of the surface stack stops reading for those viewers.
       for (let i = 1; i < STEPS.length; i++) {
-        const d = dE76(simulateCvd(matrix, hexAt(STEPS[i - 1])), simulateCvd(matrix, hexAt(STEPS[i])))
+        const d = dE76(
+          simulateCvd(matrix, hexAt(STEPS[i - 1])),
+          simulateCvd(matrix, hexAt(STEPS[i]))
+        )
         expect(d, `${mode}: grey-${STEPS[i - 1]}/${STEPS[i]} merge`).toBeGreaterThan(1.5)
       }
     }

package/src/theme/lift.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest'
+import { liftShadow, liftStyle, LIFT_RIM_ALPHA, FLOATING_LIFT_MIN } from './lift'
+
+describe('liftShadow', () => {
+  it('leads with the card rim on dark: one grade under the paperSheet hero rim', () => {
+    expect(liftShadow(1, 'dark')).toMatch(/^inset 0 1px 0 rgba\(255,255,255,0\.12\)/)
+    expect(LIFT_RIM_ALPHA.dark).toBe(0.12)
+  })
+
+  it('omits the rim when asked, keeping the ambient layers', () => {
+    const shadow = liftShadow(2, 'dark', { rim: 0 })
+    expect(shadow).not.toContain('inset')
+    expect(shadow.split(', ').length).toBe(2)
+  })
+
+  it('honours a rim override (a hero surface can ask for the paperSheet rim)', () => {
+    expect(liftShadow(2, 'dark', { rim: 0.2 })).toContain('rgba(255,255,255,0.20)')
+  })
+
+  it('casts a lighter shadow on a light surface, same geometry', () => {
+    const dark = liftShadow(3, 'dark', { rim: 0 }).split(', ')
+    const light = liftShadow(3, 'light', { rim: 0 }).split(', ')
+    expect(light.length).toBe(dark.length)
+    const alpha = (layer: string) => Number(/rgba\(0,0,0,([\d.]+)\)/.exec(layer)![1])
+    for (let i = 0; i < dark.length; i++) expect(alpha(light[i])).toBeLessThan(alpha(dark[i]))
+  })
+
+  it('uses three ambient layers from the floating threshold up', () => {
+    expect(liftShadow(FLOATING_LIFT_MIN, 'dark', { rim: 0 }).split(', ').length).toBe(3)
+    expect(liftShadow(3, 'dark', { rim: 0 }).split(', ').length).toBe(2)
+  })
+})
+
+describe('liftStyle', () => {
+  it('returns a web boxShadow under the RNW alias', () => {
+    const style = liftStyle(2) as { boxShadow?: string }
+    expect(style.boxShadow).toContain('inset 0 1px 0')
+  })
+})

package/src/theme/lift.ts

@@ -0,0 +1,102 @@
+/**
+ * LIFT — the treatment a plane wears when it sits above its neighbour.
+ *
+ * Tone says which plane a container sits on; lift says it is resting ON the one
+ * below. Two cues, both lit from above:
+ *
+ *   RIM      a crisp 1px top rim-light. The one neumorphism half that survives
+ *            near black. paperSheet's hero rim is 0.20 (VW-99 run 2); a card is
+ *            not a hero, so the default lift sits one grade quieter at 0.12,
+ *            chosen against 0.20 side by side in Lab/Depth (2026-09-08).
+ *   AMBIENT  a soft shadow cast onto the plane below, growing with the number of
+ *            planes crossed. Content lifts (1–3) are tight; floating lifts (4–5)
+ *            are large and soft, describing separation from the page rather than
+ *            rank in a stack.
+ *
+ * Neither cue is a hairline ring: a ring is an edge, not a lift, and stays the
+ * divider's job. Web carries the multi-layer boxShadow; native gets the single
+ * shadow* set. The tone underneath is load-bearing on its own either way.
+ */
+import { Platform, type ViewStyle } from 'react-native'
+import type { ThemeMode } from './tokens/semantic'
+
+export type LiftStep = 1 | 2 | 3 | 4 | 5
+
+/** The lowest lift that is FLOATING (menu, popover, toast) rather than content. */
+export const FLOATING_LIFT_MIN: LiftStep = 4
+
+/** Rim-light alpha per mode. Light mode is a placeholder pending its own pass. */
+export const LIFT_RIM_ALPHA: Record<ThemeMode, number> = { dark: 0.12, light: 0.9 }
+
+interface ShadowLayer {
+  y: number
+  blur: number
+  alpha: number
+}
+
+const AMBIENT: Record<LiftStep, ShadowLayer[]> = {
+  1: [
+    { y: 1, blur: 2, alpha: 0.35 },
+    { y: 2, blur: 6, alpha: 0.3 },
+  ],
+  2: [
+    { y: 1, blur: 2, alpha: 0.35 },
+    { y: 4, blur: 12, alpha: 0.32 },
+  ],
+  3: [
+    { y: 2, blur: 4, alpha: 0.35 },
+    { y: 8, blur: 22, alpha: 0.35 },
+  ],
+  4: [
+    { y: 1, blur: 2, alpha: 0.35 },
+    { y: 10, blur: 24, alpha: 0.3 },
+    { y: 24, blur: 48, alpha: 0.2 },
+  ],
+  5: [
+    { y: 2, blur: 4, alpha: 0.4 },
+    { y: 16, blur: 32, alpha: 0.35 },
+    { y: 32, blur: 64, alpha: 0.25 },
+  ],
+}
+
+/** A light surface casts a lighter shadow: same geometry, scaled alpha. */
+const AMBIENT_ALPHA_SCALE: Record<ThemeMode, number> = { dark: 1, light: 0.4 }
+
+export interface LiftOptions {
+  /** Override the rim alpha. `0` drops the rim and leaves the ambient shadow alone. */
+  rim?: number
+}
+
+function ambientLayers(step: LiftStep, mode: ThemeMode): string[] {
+  const scale = AMBIENT_ALPHA_SCALE[mode]
+  return AMBIENT[step].map(
+    ({ y, blur, alpha }) => `0 ${y}px ${blur}px rgba(0,0,0,${(alpha * scale).toFixed(2)})`
+  )
+}
+
+/** The web boxShadow string for a lift: rim first, then the ambient layers. */
+export function liftShadow(step: LiftStep, mode: ThemeMode = 'dark', opts: LiftOptions = {}) {
+  const rim = opts.rim ?? LIFT_RIM_ALPHA[mode]
+  const layers = ambientLayers(step, mode)
+  if (rim > 0) layers.unshift(`inset 0 1px 0 rgba(255,255,255,${rim.toFixed(2)})`)
+  return layers.join(', ')
+}
+
+/** Platform style for a lift. Compose after `backgroundColor`; never instead of it. */
+export function liftStyle(
+  step: LiftStep,
+  mode: ThemeMode = 'dark',
+  opts: LiftOptions = {}
+): ViewStyle {
+  const deepest = AMBIENT[step][AMBIENT[step].length - 1]
+  return Platform.select({
+    web: { boxShadow: liftShadow(step, mode, opts) } as unknown as ViewStyle,
+    default: {
+      shadowColor: '#000',
+      shadowOffset: { width: 0, height: Math.round(deepest.y / 2) },
+      shadowOpacity: deepest.alpha * AMBIENT_ALPHA_SCALE[mode],
+      shadowRadius: deepest.blur / 2,
+      elevation: step,
+    },
+  }) as ViewStyle
+}

package/src/theme/materials.test.ts

@@ -15,7 +15,8 @@ import { describe, it, expect } from 'vitest'
 import { grainOpacityForTone, grainForTone, paperSheet, insetWell, barPaper } from './materials'
 import { greyRamp } from './tokens/primitives'
 
-const styleOf = (s: Record<string, unknown>) => s as { backgroundImage?: string; boxShadow?: string; backgroundColor?: string }
+const styleOf = (s: Record<string, unknown>) =>
+  s as { backgroundImage?: string; boxShadow?: string; backgroundColor?: string }
 
 describe('grain', () => {
   it('scales opacity with the tone it sits on', () => {
@@ -75,7 +76,9 @@ describe('insetWell', () => {
     // a darker rectangle. It is the light on the floor that says "below".
     const shadow = styleOf(insetWell(greyRamp[950])).boxShadow!
     expect(shadow).toContain('inset 0 2px')
-    expect(shadow, 'missing the bottom floor rim').toContain('inset 0 -1px 0 rgba(255,255,255,0.12)')
+    expect(shadow, 'missing the bottom floor rim').toContain(
+      'inset 0 -1px 0 rgba(255,255,255,0.12)'
+    )
   })
 
   it('is entirely inset — a well must not cast outward', () => {

package/src/theme/materials.ts

@@ -54,10 +54,12 @@
  *
  * Kept: grain, rim-light, contact shadow.
  *
- * See coordination/design-explorations/surface-system-north-star.md §4 and
- * coordination/validation-runbooks/VW-99-depth-wall-calibration.md.
+ * See `sources/design/surface-system-north-star.md` §4 and
+ * `sources/runbooks/VW-99-depth-wall-calibration.md`. Those paths are relative to
+ * the `voltras-workspace` active-work initiative (`active-work open voltras-workspace`), not this repo —
+ * titan-design has no `sources/` directory, so they do not resolve from here.
  */
-import type { ViewStyle } from 'react-native'
+import type { TextStyle, ViewStyle } from 'react-native'
 import { getSemanticColors } from './tokens/semantic'
 
 const c = getSemanticColors('dark')
@@ -66,7 +68,13 @@ const c = getSemanticColors('dark')
 
 function parseHex(hex: string): [number, number, number] | null {
   const h = hex.replace('#', '')
-  const full = h.length === 3 ? h.split('').map((ch) => ch + ch).join('') : h
+  const full =
+    h.length === 3
+      ? h
+          .split('')
+          .map((ch) => ch + ch)
+          .join('')
+      : h
   const rgb: [number, number, number] = [
     parseInt(full.slice(0, 2), 16),
     parseInt(full.slice(2, 4), 16),
@@ -209,3 +217,29 @@ export function barPaper(color: string, flip = false): ViewStyle {
       : 'inset 0 1.5px 0 rgba(255,255,255,0.22), 0 6px 16px rgba(0,0,0,0.45)',
   } as unknown as ViewStyle
 }
+
+/**
+ * A POST-IT card: a matte tinted sheet with a crisp rim, a defined contact
+ * shadow, and a deliberate CANT (`deg`) so it reads as a stuck note — where a
+ * small unit of data wants to feel pinned to the surface (alerts, next-set). A
+ * degree or two, not a fraction, so the tilt is intentional rather than a bug.
+ */
+export function postIt(tone: string = c['surface-raised'], deg = -1.5): ViewStyle {
+  return {
+    backgroundColor: tone,
+    backgroundImage: grainForTone(tone),
+    boxShadow: 'inset 0 1px 0 rgba(255,255,255,0.12), 0 6px 14px rgba(0,0,0,0.45)',
+    transform: [{ rotate: `${deg}deg` }],
+  } as unknown as ViewStyle
+}
+
+/**
+ * DEBOSSED (engraved) text: a 1px light highlight dropped just below the glyphs
+ * so a label reads as pressed INTO the surface. Deliberate, for section eyebrows
+ * on a matte plane — not body copy. Pair with a tertiary/dim text colour.
+ */
+export const debossLabel: TextStyle = {
+  textShadowColor: 'rgba(255,255,255,0.11)',
+  textShadowOffset: { width: 0, height: 1 },
+  textShadowRadius: 0,
+}

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

@@ -37,7 +37,7 @@ const colorTree = tailwindConfig.theme?.extend?.colors ?? {}
 // `brand-primary` class).
 function flattenColors(
   node: Record<string, unknown>,
-  prefix: string[] = [],
+  prefix: string[] = []
 ): Record<string, string> {
   const out: Record<string, string> = {}
   for (const [key, value] of Object.entries(node)) {
@@ -83,11 +83,11 @@ describe('native theming guard (no color token renders black on native)', () =>
     }
     expect(
       undefinedDark,
-      'tailwind colors point at vars missing from darkThemeCSSVars (className renders black on native dark)',
+      '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)',
+      'tailwind colors point at vars missing from lightThemeCSSVars (className renders black on native light)'
     ).toEqual([])
   })
 
@@ -106,11 +106,11 @@ describe('native theming guard (no color token renders black on native)', () =>
       }
       expect(
         invalidValues,
-        `getSemanticColors('${mode}') has tokens with no valid color (renders black/unset on native)`,
+        `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)`,
+        `resolveColor tokens missing a --color-<token> in ${mode} vars (renders unset on web)`
       ).toEqual([])
     }
   })

package/src/theme/presets/apply.ts

@@ -36,6 +36,10 @@ function injectFontImport(url: string) {
   document.head.appendChild(link)
 }
 
+/**
+ * @deprecated Use `ThemeProvider` with semantic tokens — removed once audiobook
+ * migrates off presets (AW-129).
+ */
 export function applyThemePreset(preset: ThemePreset): () => void {
   if (typeof document === 'undefined') {
     return () => {}

package/src/theme/presets/audiobook.ts

@@ -5,12 +5,15 @@ import type { ThemePreset } from './types'
  *
  * Warm copper/patina aesthetic inspired by vintage audio equipment
  * and reading lounges. Dark-mode only design with editorial typography.
+ *
+ * @deprecated Use `ThemeProvider` with semantic tokens — removed once audiobook
+ * migrates off presets (AW-129).
  */
 export const audiobookPreset: ThemePreset = {
   name: 'audiobook',
   description: 'Warm copper/patina theme with editorial typography',
   fontImport:
-    "https://fonts.googleapis.com/css2?family=Newsreader:ital,wght@0,400;0,600;0,700;1,400&family=Outfit:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap",
+    'https://fonts.googleapis.com/css2?family=Newsreader:ital,wght@0,400;0,600;0,700;1,400&family=Outfit:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap',
   fonts: {
     sans: "'Outfit', 'Avenir', 'Avenir Next', system-ui, sans-serif",
     body: "'Outfit', 'Avenir', 'Avenir Next', system-ui, sans-serif",
@@ -77,7 +80,7 @@ export const audiobookPreset: ThemePreset = {
       'interactive-active': 'rgba(255, 255, 255, 0.16)',
       'interactive-selected': 'rgba(255, 255, 255, 0.08)',
 
-      'divider': 'rgba(255, 255, 255, 0.06)',
+      divider: 'rgba(255, 255, 255, 0.06)',
 
       // Glow RGB values for shadow utilities
       'brand-primary-rgb': '212, 120, 42',

package/src/theme/presets/default.ts

@@ -1,5 +1,9 @@
 import type { ThemePreset } from './types'
 
+/**
+ * @deprecated Use `ThemeProvider` with semantic tokens — removed once audiobook
+ * migrates off presets (AW-129).
+ */
 export const defaultPreset: ThemePreset = {
   name: 'default',
   description: 'Titan Design System default theme — orange accent, steel secondary',

package/src/theme/presets/index.ts

@@ -1,4 +1,17 @@
-export type { ThemePreset, ThemePresetColors, ThemePresetFonts, ThemePresetRadii, ThemePresetShadows } from './types'
+/**
+ * @deprecated The whole `theme/presets` barrel. Use `ThemeProvider` with
+ * semantic tokens — removed once audiobook migrates off presets (AW-129).
+ */
+export type {
+  ThemePreset,
+  ThemePresetColors,
+  ThemePresetFonts,
+  ThemePresetRadii,
+  ThemePresetShadows,
+} from './types'
+/** @deprecated Use `ThemeProvider` with semantic tokens (AW-129). */
 export { applyThemePreset } from './apply'
+/** @deprecated Use `ThemeProvider` with semantic tokens (AW-129). */
 export { defaultPreset } from './default'
+/** @deprecated Use `ThemeProvider` with semantic tokens (AW-129). */
 export { audiobookPreset } from './audiobook'

package/src/theme/presets/types.ts

@@ -32,7 +32,7 @@ export interface ThemePresetColors {
   'hairline-subtle'?: string
   'hairline-strong'?: string
   'border-focus'?: string
-  'divider'?: string
+  divider?: string
   [key: `${string}`]: string | undefined
 }
 

package/src/theme/semantic-contrast.test.ts

@@ -54,7 +54,7 @@ describe('semantic text on the surface planes (dark)', () => {
         const ratio = contrast(fg, greyRamp[plane])
         expect(
           ratio,
-          `${role} ${fg} on grey-${plane} ${greyRamp[plane]} is ${ratio.toFixed(2)}:1, needs ${min}`,
+          `${role} ${fg} on grey-${plane} ${greyRamp[plane]} is ${ratio.toFixed(2)}:1, needs ${min}`
         ).toBeGreaterThanOrEqual(min)
       })
     })
@@ -68,10 +68,19 @@ describe('semantic text on the surface planes (dark)', () => {
   it('keeps primary > secondary > tertiary in contrast on every plane', () => {
     for (const plane of PLANES) {
       const [pri, sec, ter] = TEXT_ROLES.map(({ role }) =>
-        contrast(semanticColorsDark[role as keyof typeof semanticColorsDark] as string, greyRamp[plane]),
+        contrast(
+          semanticColorsDark[role as keyof typeof semanticColorsDark] as string,
+          greyRamp[plane]
+        )
       )
-      expect(pri, `on grey-${plane}: primary ${pri.toFixed(2)} vs secondary ${sec.toFixed(2)}`).toBeGreaterThan(sec)
-      expect(sec, `on grey-${plane}: secondary ${sec.toFixed(2)} vs tertiary ${ter.toFixed(2)}`).toBeGreaterThan(ter)
+      expect(
+        pri,
+        `on grey-${plane}: primary ${pri.toFixed(2)} vs secondary ${sec.toFixed(2)}`
+      ).toBeGreaterThan(sec)
+      expect(
+        sec,
+        `on grey-${plane}: secondary ${sec.toFixed(2)} vs tertiary ${ter.toFixed(2)}`
+      ).toBeGreaterThan(ter)
     }
   })
 

package/src/theme/status-distinctness.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Status tokens that mean different things must LOOK different.
+ *
+ * `status-error-vivid` existed to separate "drop everything" from "serious",
+ * and it pointed at `ramp.red[600]` — the exact value of `status-error`. The two
+ * had been rendering as one colour for as long as the token had existed, in both
+ * themes. Three other places in the system already disagreed with it and said
+ * vivid was `#FF4757`: `--color-status-error-vivid-rgb`, the `-subtle` rgba, and
+ * the `glow` shadow in `Indicator`. Only the value anyone actually rendered was
+ * wrong.
+ *
+ * Nothing caught it because every existing token test asks whether a value is
+ * PRESENT and parity-matched across config.ts and global.css — a collapsed token
+ * is present and matches perfectly. Distinctness is a different question, so it
+ * gets its own gate.
+ *
+ * Found 2026-08-31 by measuring a rendered Storybook story, not by reading the
+ * tokens: `SeverityLabel`'s Critical and High dots came back the same RGB.
+ */
+import { describe, it, expect } from 'vitest'
+import { semanticColorsDark, semanticColorsLight } from './tokens/semantic'
+import { alertRedVivid } from './tokens/primitives'
+
+type SemanticMap = Record<string, string>
+
+const THEMES: [string, SemanticMap][] = [
+  ['dark', semanticColorsDark as SemanticMap],
+  ['light', semanticColorsLight as SemanticMap],
+]
+
+/**
+ * Token pairs a viewer is expected to tell apart at a glance. Each pair carries
+ * the reason, so a future retune can weigh it rather than just delete the row.
+ */
+const MUST_DIFFER: [string, string, string][] = [
+  [
+    'status-error',
+    'status-error-vivid',
+    'severity Critical vs High, and DeviceRow/DeviceIndicator "lost" vs a plain error',
+  ],
+  ['status-error', 'status-warning', 'error vs warning is the most common status pairing'],
+  ['status-warning', 'status-info', 'warning vs informational'],
+  ['status-success', 'status-info', 'succeeded vs merely reporting'],
+]
+
+describe('semantically distinct status tokens render distinct values', () => {
+  for (const [theme, colors] of THEMES) {
+    for (const [a, b, why] of MUST_DIFFER) {
+      it(`${theme}: ${a} !== ${b} — ${why}`, () => {
+        // Both must exist, or the assertion passes vacuously on a typo.
+        expect(colors[a], `${a} missing from ${theme}`).toBeTruthy()
+        expect(colors[b], `${b} missing from ${theme}`).toBeTruthy()
+        expect(colors[a]!.toLowerCase()).not.toBe(colors[b]!.toLowerCase())
+      })
+    }
+  }
+})
+
+describe('status-error-vivid is the vivid red the rest of the system already assumes', () => {
+  for (const [theme, colors] of THEMES) {
+    it(`${theme}: is the alertRedVivid primitive that -rgb, -subtle and Indicator's glow encode`, () => {
+      expect(colors['status-error-vivid']).toBe(alertRedVivid)
+      expect(alertRedVivid.toLowerCase()).toBe('#ff4757')
+    })
+  }
+})

package/src/theme/surface-planes.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { PLANE_ORDER, pressedLevel, raisedLevel, surfaceBackground } from './surface-planes'
+import { getSemanticColors } from './tokens/semantic'
+
+describe('surface planes', () => {
+  it('orders the six planes darkest first', () => {
+    expect(PLANE_ORDER).toEqual(['frame', 'background', 'base', 'elevated', 'raised', 'overlay'])
+  })
+
+  it('resolves each plane to its semantic token, literal hex', () => {
+    const dark = getSemanticColors('dark')
+    expect(surfaceBackground('frame', 'dark')).toBe(dark['background-frame'])
+    expect(surfaceBackground('base', 'dark')).toBe(dark['surface-base'])
+    expect(surfaceBackground('overlay', 'dark')).toMatch(/^#[0-9A-F]{6}$/i)
+  })
+
+  it.each([
+    ['base', 1, 'elevated'],
+    ['base', 2, 'raised'],
+    ['base', 3, 'overlay'],
+    ['elevated', 2, 'overlay'],
+    ['raised', 3, 'overlay'],
+    ['overlay', 1, 'overlay'],
+  ] as const)('raisedLevel(%s, %i) → %s, clamped at overlay', (from, steps, expected) => {
+    expect(raisedLevel(from, steps)).toBe(expected)
+  })
+
+  it('raisedLevel with zero steps stays put', () => {
+    expect(raisedLevel('raised', 0)).toBe('raised')
+  })
+
+  it('pressedLevel steps down and clamps at the frame', () => {
+    expect(pressedLevel('base')).toBe('background')
+    expect(pressedLevel('background')).toBe('frame')
+    expect(pressedLevel('frame')).toBe('frame')
+  })
+})