@titan-design/react-ui 0.13.0 → 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/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/tokens/primitives.ts

@@ -31,6 +31,39 @@ export const primitiveColors = {
  */
 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)
  *