@titan-design/react-ui 0.12.1 → 0.14.0

package/src/theme/subtle-tone-weight.test.ts

@@ -0,0 +1,163 @@
+/**
+ * AW-133 — the `-subtle` fill and the text on it, as a gate.
+ *
+ * The status family had one token doing two incompatible jobs. `status-error`
+ * and `brand-secondary` sit at ramp rung 600 so a white label reads on them as a
+ * solid fill; that same depth made them unreadable as TEXT on a dark plane, and a
+ * subtle Pill in those tones measured 2.9-3.1 against its own fill. The four
+ * lighter tones had the mirror problem. Splitting the roles fixed it: `on-*-subtle`
+ * is text on the subtle fill, levelled at rung 300.
+ *
+ * The numbers run in CI so a future retune cannot quietly reopen it.
+ */
+import { describe, it, expect } from 'vitest'
+import { greyRamp } from './tokens/primitives'
+import { semanticColorsDark } from './tokens/semantic'
+
+const hex2rgb = (h: string): [number, number, number] => {
+  const n = parseInt(h.slice(1), 16)
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+}
+const srgb2lin = (c: number) => {
+  const s = c / 255
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+}
+const relLum = (rgb: number[]) => {
+  const [r, g, b] = rgb.map(srgb2lin)
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+const contrast = (a: number[], b: number[]) => {
+  const [hi, lo] = [relLum(a), relLum(b)].sort((x, y) => y - x)
+  return (hi + 0.05) / (lo + 0.05)
+}
+/** OKLab lightness — the perceptual axis the ramps were generated on. */
+const oklabL = (rgb: number[]) => {
+  const [r, g, b] = rgb.map(srgb2lin)
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
+  return 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s
+}
+/** OKLCH chroma — how saturated, independent of how light. */
+const oklabChroma = (rgb: number[]) => {
+  const [r, g, b] = rgb.map(srgb2lin)
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
+  const a = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s
+  const bb = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
+  return Math.sqrt(a * a + bb * bb)
+}
+
+const parseRgba = (v: string): { rgb: number[]; alpha: number } => {
+  const m = v.match(/rgba?\(([^)]+)\)/)
+  if (!m) throw new Error(`expected an rgba() subtle fill, got "${v}"`)
+  const parts = m[1].split(',').map((n) => parseFloat(n.trim()))
+  return { rgb: parts.slice(0, 3), alpha: parts[3] ?? 1 }
+}
+const composite = (fill: string, plane: string) => {
+  const { rgb, alpha } = parseRgba(fill)
+  const bg = hex2rgb(plane)
+  return rgb.map((c, i) => Math.round(c * alpha + bg[i] * (1 - alpha)))
+}
+
+/** The two planes a subtle pill actually lands on. */
+const PAGE = greyRamp[925]
+const CARD = greyRamp[875]
+
+/**
+ * Four tones level at ramp rung 300. Two are deliberate exceptions, both operator
+ * calls during the AW-133 review, and both are held here rather than quietly
+ * widening the band:
+ *
+ * - `brand` keeps the exact `orange[400]` brand hue instead of levelling, so the
+ *   Voltras tone never drifts. It is the darkest label and the lowest contrast.
+ * - `error` sits at `red[400]`, a rung darker than its siblings. red[300] levelled
+ *   perfectly but read PINK: a red that light can only hold ~0.121 OKLCH chroma.
+ *   red[400] carries ~0.165 and reads red. Its fill is thinned to 0.08 to buy back
+ *   the contrast that darkness costs, which is why it still beats brand's floor.
+ */
+const TONES = [
+  {
+    name: 'brand',
+    fill: 'brand-primary-subtle',
+    text: 'on-brand-primary-subtle',
+    min: 4.0,
+    levelled: false,
+  },
+  {
+    name: 'accent',
+    fill: 'brand-secondary-subtle',
+    text: 'on-brand-secondary-subtle',
+    min: 4.5,
+    levelled: true,
+  },
+  {
+    name: 'success',
+    fill: 'status-success-subtle',
+    text: 'on-status-success-subtle',
+    min: 4.5,
+    levelled: true,
+  },
+  {
+    name: 'warning',
+    fill: 'status-warning-subtle',
+    text: 'on-status-warning-subtle',
+    min: 4.5,
+    levelled: true,
+  },
+  {
+    name: 'error',
+    fill: 'status-error-subtle',
+    text: 'on-status-error-subtle',
+    min: 4.2,
+    levelled: false,
+  },
+  {
+    name: 'info',
+    fill: 'status-info-subtle',
+    text: 'on-status-info-subtle',
+    min: 4.5,
+    levelled: true,
+  },
+] as const
+
+describe('subtle tone weight (dark)', () => {
+  it.each(TONES)('$name text clears its floor on both planes', ({ fill, text, min }) => {
+    const label = hex2rgb(semanticColorsDark[text])
+    for (const plane of [PAGE, CARD]) {
+      const composited = composite(semanticColorsDark[fill], plane)
+      expect(contrast(label, composited)).toBeGreaterThanOrEqual(min)
+    }
+  })
+
+  // The original defect was a WEIGHT mismatch, not only a contrast one: the family
+  // spanned OKLCH L 0.550-0.813, so accent and error read as a different rung of
+  // the system. Hold the levelled tones in a tight band; the two exceptions are
+  // measured by their own floors above.
+  it('levels the unexceptional tones to one weight', () => {
+    const ls = TONES.filter((t) => t.levelled).map((t) =>
+      oklabL(hex2rgb(semanticColorsDark[t.text]))
+    )
+    expect(Math.max(...ls) - Math.min(...ls)).toBeLessThanOrEqual(0.06)
+  })
+
+  // Guards the operator's actual complaint. Levelling error back onto rung 300 would
+  // satisfy every other assertion in this file — tighter band, higher contrast — and
+  // reintroduce the pink. Chroma is the thing that made it wrong, so chroma is what
+  // gets asserted.
+  it('keeps error saturated enough to read red rather than pink', () => {
+    const c = oklabChroma(hex2rgb(semanticColorsDark['on-status-error-subtle']))
+    expect(c).toBeGreaterThanOrEqual(0.15)
+  })
+
+  // A fill whose hue drifts from its label's re-opens the split this fixed.
+  it('draws each fill from the same hue family as its label', () => {
+    for (const { fill, text, name } of TONES) {
+      if (name === 'brand') continue
+      const fillRgb = parseRgba(semanticColorsDark[fill]).rgb
+      const labelRgb = hex2rgb(semanticColorsDark[text])
+      expect(fillRgb).toEqual(labelRgb)
+    }
+  })
+})

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')
+  })
+})

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/tailwind-var-opacity.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { createRequire } from 'node:module'
+import { readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Tailwind opacity modifiers on var()-backed colours (VW-308).
+ *
+ * Tailwind v3 cannot apply `/<n>` to a colour whose value is a `var(--…)`
+ * reference. It does not warn and does not fall back: it emits NO RULE, and the
+ * class is dead CSS on web. Every colour in `tailwind.config.js` is var()-backed
+ * (that is what makes light/dark switching work), so `bg-brand-primary/10` never
+ * painted anything — while the literal-valued `text-white/70` compiles fine.
+ * That asymmetry is why it sat unnoticed in four components.
+ *
+ * This test compiles the REAL `tailwind.config.js` against a fixture, which is
+ * how the finding was reproduced. It pins three things:
+ *   1. the defect itself, so nobody "fixes" a call site back to a modifier;
+ *   2. a POSITIVE CONTROL — `text-white/70` and `bg-black/50` still compile, so
+ *      an empty stylesheet from a broken harness can't pass as proof;
+ *   3. that no var()-backed opacity modifier survives anywhere in `src/`.
+ *
+ * The chosen fix is (3), not making the modifier work: the `<alpha-value>`
+ * pattern needs channel-triplet CSS vars, a hand-aligned rewrite of the whole
+ * token layer, and `color-mix()` — the config-only alternative — is not a value
+ * React Native understands. The wash ladder (`-subtle`/`-muted`/`-strong`)
+ * already expresses translucency on both platforms.
+ */
+
+const require = createRequire(import.meta.url)
+const uiRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+
+// postcss is a declared dependency of tailwindcss, not of this package; resolve
+// it from there rather than relying on hoisting.
+const tailwindEntry = require.resolve('tailwindcss', { paths: [uiRoot] })
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const tailwind = require(tailwindEntry) as any
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const postcss = createRequire(tailwindEntry)('postcss') as any
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const tailwindConfig = require(path.join(uiRoot, 'tailwind.config.js')) as any
+
+/** `brand.primary.DEFAULT` -> the `brand-primary` class suffix. */
+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 varBackedTokens = new Set(
+  Object.entries(flattenColors(tailwindConfig.theme?.extend?.colors ?? {}))
+    .filter(([, value]) => /^var\(--color-/.test(value))
+    .map(([name]) => name)
+)
+
+const PROBE_CLASSES = [
+  // The finding, verbatim.
+  'bg-brand-primary/10',
+  'text-on-status-success/70',
+  // The four call sites' original classes.
+  'bg-status-success/10',
+  'bg-brand-primary/20',
+  'text-text-tertiary/40',
+  // Positive control: literal-valued colours, which DO support the modifier.
+  'text-white/70',
+  'bg-black/50',
+  // The replacements the call sites now use.
+  'bg-brand-primary-subtle',
+  'bg-status-success-subtle',
+  'bg-brand-primary-muted',
+  'bg-status-info-muted',
+  'text-text-disabled',
+]
+
+let emitted: Set<string>
+
+beforeAll(async () => {
+  const raw = `<div class="${PROBE_CLASSES.join(' ')}"></div>`
+  const result = await postcss([
+    tailwind({ ...tailwindConfig, content: { files: [{ raw, extension: 'html' }] } }),
+  ]).process('@tailwind utilities;', { from: undefined })
+
+  emitted = new Set(
+    [...(result.css as string).matchAll(/^\.([^\s{]+)\s*\{/gm)].map((m) => m[1].replace(/\\/g, ''))
+  )
+}, 30_000)
+
+describe('tailwind opacity modifiers on var()-backed colours (VW-308)', () => {
+  it('compiles the real config against the fixture at all', () => {
+    // Guards the harness: without this, every "emits no rule" assertion below
+    // would also pass against a stylesheet that failed to build.
+    expect(emitted.size).toBeGreaterThan(0)
+  })
+
+  // POSITIVE CONTROL. These are literal colours in tailwind's own palette, so
+  // the modifier works. If one of these ever stops compiling, the harness is
+  // broken, not the design system.
+  it.each(['text-white/70', 'bg-black/50'])('%s compiles (positive control)', (className) => {
+    expect(emitted).toContain(className)
+  })
+
+  it.each([
+    'bg-brand-primary/10',
+    'text-on-status-success/70',
+    'bg-status-success/10',
+    'bg-brand-primary/20',
+    'text-text-tertiary/40',
+  ])('%s emits NO rule — this is the defect, do not use it', (className) => {
+    expect(emitted).not.toContain(className)
+  })
+
+  it.each([
+    'bg-brand-primary-subtle',
+    'bg-status-success-subtle',
+    'bg-brand-primary-muted',
+    'bg-status-info-muted',
+    'text-text-disabled',
+  ])('%s compiles — the replacement the call sites use', (className) => {
+    expect(emitted).toContain(className)
+  })
+})
+
+const OPACITY_UTILITY =
+  /\b(?:[a-z][a-z0-9-]*:)*(?:bg|text|border|ring|fill|stroke|from|to|via|shadow|outline|decoration|divide|accent|caret|placeholder)-([a-z][a-zA-Z0-9-]*)\/(?:\[[^\]]+\]|\d+)/g
+
+function sourceFiles(dir: string, found: string[] = []): string[] {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) sourceFiles(full, found)
+    else if (/\.(ts|tsx)$/.test(entry.name)) found.push(full)
+  }
+  return found
+}
+
+describe('no var()-backed opacity modifier survives in src/', () => {
+  it('finds no dead colour class', () => {
+    const srcRoot = path.join(uiRoot, 'src')
+    const violations: string[] = []
+
+    for (const file of sourceFiles(srcRoot)) {
+      // This file quotes the dead classes on purpose, as the probe list above.
+      if (file === fileURLToPath(import.meta.url)) continue
+      for (const match of readFileSync(file, 'utf8').matchAll(OPACITY_UTILITY)) {
+        if (varBackedTokens.has(match[1])) {
+          violations.push(`${path.relative(uiRoot, file)}: ${match[0]}`)
+        }
+      }
+    }
+
+    expect(violations, `dead colour classes (VW-308):\n${violations.join('\n')}`).toEqual([])
+  })
+})

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,51 @@ 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
+
+/**
+ * Result/outcome palette anchors (VW-83): Material-style green/red/grey chosen
+ * for the result-improve/-degrade/-inconclusive tokens. No `primitiveRamps` step
+ * matches any of these exactly (the ramps are OKLCH-generated with a different
+ * hue/chroma arc), so they are pinned by name here rather than left as raw hex
+ * in semantic.ts — same pattern as {@link alertRedVivid}.
+ */
+export const resultPaletteColors = {
+  improve: '#4caf50',
+  improveDark: '#248a24',
+  degrade: '#ef5350',
+  degradeDark: '#b30000',
+  inconclusive: '#9E9A97',
+} as const
+
+/**
+ * One-off semantic literals (VW-83) with no exact `greyRamp`/`primitiveRamps`
+ * match, pinned by name instead of left as raw hex in semantic.ts.
+ */
+export const semanticPins = {
+  // Cool navy-black; darker and more blue-shifted than any warm greyRamp step.
+  textPrimaryLight: '#121828',
+  // Cool blue-grey; outside greyRamp's warm (R>=G>=B) scale.
+  textSecondaryLight: '#65748B',
+  // Pure neutral grey (R=G=B); no warm greyRamp step lands on it exactly.
+  backgroundBaseLight: '#EBEBEB',
+  // Near-neutral grey, kept one step off backgroundBaseLight by design.
+  dividerLight: '#E8E9EB',
+  // Periwinkle/indigo; more purple than any primitiveRamps.blue step. Shared by
+  // dark-mode text-link, border-focus and border-input-focus.
+  focusIndigoDark: '#828DF8',
+} as const
+
 /**
  * Unified warm-neutral grey ramp (TD-07.14)
  *
@@ -244,7 +289,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 +435,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 +495,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 = {