@titan-design/react-ui 0.5.0 → 0.7.0

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

@@ -0,0 +1,232 @@
+import { describe, it, expect } from 'vitest'
+import {
+  primitiveRamps,
+  categoricalPalette,
+  getCategoricalColor,
+  CATEGORICAL_CVD_SAFE_MAX,
+  divergingScale,
+  sequentialEffort,
+  bestTextColor,
+} from './primitives'
+
+// --- Minimal OKLab + Machado-2009 dichromacy math (ported from the color-system
+// derivation tools) so the categorical CVD floor is a real, checked property. ---
+const hexToRgb = (hex: string): [number, number, number] => {
+  const h = hex.replace('#', '')
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255) as [number, number, number]
+}
+const lin = (c: number) => (c >= 0.04045 ? ((c + 0.055) / 1.055) ** 2.4 : c / 12.92)
+const toOklab = ([r, g, b]: number[]): [number, number, number] => {
+  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,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ]
+}
+const mul = (M: number[], v: number[]) => [
+  M[0] * v[0] + M[1] * v[1] + M[2] * v[2],
+  M[3] * v[0] + M[4] * v[1] + M[5] * v[2],
+  M[6] * v[0] + M[7] * v[1] + M[8] * v[2],
+]
+// 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 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))),
+  )
+}
+
+const HEX6 = /^#[0-9A-F]{6}$/
+const STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const
+const HUES = ['red', 'orange', 'amber', 'green', 'cyan', 'blue', 'magenta'] as const
+
+describe('primitiveRamps', () => {
+  it('has all seven consolidated hues', () => {
+    expect(Object.keys(primitiveRamps).sort()).toEqual([...HUES].sort())
+  })
+
+  it('gives every hue all eleven perceptual steps as uppercase 6-digit hex', () => {
+    for (const hue of HUES) {
+      const ramp = primitiveRamps[hue] as Record<number, string>
+      for (const step of STEPS) {
+        expect(ramp[step], `${hue}-${step}`).toMatch(HEX6)
+      }
+    }
+  })
+
+  it('flows through each pinned anchor color at its step', () => {
+    // The step each ramp is pinned to its brand/semantic anchor hex.
+    const anchors: Record<string, string> = {
+      'red-600': '#D14343', // status-error
+      'orange-400': '#FF7900', // brand-primary
+      'amber-300': '#F9B415', // status-warning
+      'green-300': '#2ED573', // status-success
+      'cyan-300': '#22D3EE', // vivid cyan identity
+      'blue-500': '#2196F3', // status-info
+      'magenta-700': '#9C0D7A',
+    }
+    for (const [key, hex] of Object.entries(anchors)) {
+      const [hue, step] = key.split('-')
+      expect((primitiveRamps as never)[hue][Number(step)]).toBe(hex)
+    }
+  })
+
+  it('increases in darkness monotonically (OKLab L descends 50 -> 950)', () => {
+    for (const hue of HUES) {
+      const ramp = primitiveRamps[hue] as Record<number, string>
+      const lightness = STEPS.map((s) => toOklab(hexToRgb(ramp[s]).map(lin))[0])
+      for (let i = 1; i < lightness.length; i++) {
+        expect(lightness[i], `${hue} ${STEPS[i - 1]}->${STEPS[i]}`).toBeLessThan(lightness[i - 1])
+      }
+    }
+  })
+})
+
+describe('categoricalPalette', () => {
+  it('has two ordered variants of seven colors', () => {
+    expect(categoricalPalette.default).toHaveLength(7)
+    expect(categoricalPalette.dark).toHaveLength(7)
+  })
+
+  it('is all uppercase 6-digit hex', () => {
+    for (const variant of ['default', 'dark'] as const) {
+      for (const hex of categoricalPalette[variant]) {
+        expect(hex).toMatch(HEX6)
+      }
+    }
+  })
+
+  it('holds the deut/protanopia dichromacy floor (deltaE >= 8) through the CVD-safe max', () => {
+    // The first CATEGORICAL_CVD_SAFE_MAX colors are legend-free CVD-safe; the 7th is extended.
+    for (const variant of ['default', 'dark'] as const) {
+      const colors = categoricalPalette[variant].slice(0, CATEGORICAL_CVD_SAFE_MAX)
+      let worst = Infinity
+      for (let i = 0; i < colors.length; i++) {
+        for (let j = i + 1; j < colors.length; j++) {
+          worst = Math.min(worst, cvdDelta(colors[i], colors[j]))
+        }
+      }
+      expect(worst, `${variant} min CVD deltaE (first ${CATEGORICAL_CVD_SAFE_MAX})`).toBeGreaterThanOrEqual(8)
+    }
+  })
+
+  it('is nested-stable: no color repeats within a variant', () => {
+    for (const variant of ['default', 'dark'] as const) {
+      expect(new Set(categoricalPalette[variant]).size).toBe(categoricalPalette[variant].length)
+    }
+  })
+
+  it('carries readable in-place text: default on black (>=4.5), dark on white (>=3.5)', () => {
+    const relLum = (hex: string) => {
+      const [r, g, b] = hexToRgb(hex).map(lin)
+      return 0.2126 * r + 0.7152 * g + 0.0722 * b
+    }
+    const onBlack = (hex: string) => (relLum(hex) + 0.05) / 0.05
+    const onWhite = (hex: string) => 1.05 / (relLum(hex) + 0.05)
+    // The in-place text guarantee covers the CVD-safe range; the 7th extended
+    // color trades contrast for separation and is meant to be legend-paired.
+    for (const hex of categoricalPalette.default.slice(0, CATEGORICAL_CVD_SAFE_MAX)) {
+      expect(onBlack(hex), `default ${hex} black-text contrast`).toBeGreaterThanOrEqual(4.5)
+    }
+    for (const hex of categoricalPalette.dark.slice(0, CATEGORICAL_CVD_SAFE_MAX)) {
+      expect(onWhite(hex), `dark ${hex} white-text contrast`).toBeGreaterThanOrEqual(3.5)
+    }
+  })
+})
+
+describe('getCategoricalColor', () => {
+  it('returns default-variant colors by index', () => {
+    expect(getCategoricalColor(0)).toBe(categoricalPalette.default[0])
+    expect(getCategoricalColor(4)).toBe(categoricalPalette.default[4])
+  })
+
+  it('selects the requested variant', () => {
+    expect(getCategoricalColor(2, 'dark')).toBe(categoricalPalette.dark[2])
+    expect(getCategoricalColor(1, 'dark')).toBe(categoricalPalette.dark[1])
+  })
+
+  it('wraps past the end of the palette', () => {
+    expect(getCategoricalColor(7)).toBe(categoricalPalette.default[0])
+    expect(getCategoricalColor(9)).toBe(categoricalPalette.default[2])
+  })
+
+  it('clamps negative and fractional indices', () => {
+    expect(getCategoricalColor(-3)).toBe(categoricalPalette.default[0])
+    expect(getCategoricalColor(2.9)).toBe(categoricalPalette.default[2])
+  })
+})
+
+const relLum = (hex: string) => {
+  const [r, g, b] = hexToRgb(hex).map(lin)
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+const bestContrast = (hex: string) => {
+  const l = relLum(hex)
+  return Math.max((l + 0.05) / 0.05, 1.05 / (l + 0.05))
+}
+
+describe('divergingScale', () => {
+  it('is a five-stop diverging scale of uppercase hex', () => {
+    expect(divergingScale).toHaveLength(5)
+    for (const hex of divergingScale) expect(hex).toMatch(HEX6)
+  })
+
+  it('has a light center and dark extremes (diverging shape)', () => {
+    const L = divergingScale.map((h) => toOklab(hexToRgb(h).map(lin))[0])
+    expect(L[2], 'optimal is the lightest').toBeGreaterThan(Math.max(L[0], L[4]))
+    expect(L[0], 'under is dark').toBeLessThan(L[1])
+    expect(L[4], 'over is dark').toBeLessThan(L[3])
+  })
+
+  it('holds a strong CVD floor (deltaE >= 10)', () => {
+    let worst = Infinity
+    for (let i = 0; i < divergingScale.length; i++) {
+      for (let j = i + 1; j < divergingScale.length; j++) {
+        worst = Math.min(worst, cvdDelta(divergingScale[i], divergingScale[j]))
+      }
+    }
+    expect(worst).toBeGreaterThanOrEqual(10)
+  })
+
+  it('every cell carries a legible label via best-contrast text (>=4.5)', () => {
+    for (const hex of divergingScale) {
+      expect(bestContrast(hex), `${hex}`).toBeGreaterThanOrEqual(4.5)
+    }
+  })
+})
+
+describe('sequentialEffort', () => {
+  it('is a six-stop ordinal scale of uppercase hex', () => {
+    expect(sequentialEffort).toHaveLength(6)
+    for (const hex of sequentialEffort) expect(hex).toMatch(HEX6)
+  })
+
+  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)
+    }
+  })
+
+  it('every stop carries a legible label via best-contrast text (>=4.5)', () => {
+    for (const hex of sequentialEffort) {
+      expect(bestContrast(hex), `${hex}`).toBeGreaterThanOrEqual(4.5)
+    }
+  })
+})
+
+describe('bestTextColor', () => {
+  it('picks black on light fills and white on dark fills', () => {
+    expect(bestTextColor(primitiveRamps.green[300])).toBe('#000000')
+    expect(bestTextColor(primitiveRamps.red[700])).toBe('#FFFFFF')
+    expect(bestTextColor(primitiveRamps.blue[700])).toBe('#FFFFFF')
+  })
+})

package/src/theme/tokens/primitives.ts

@@ -6,7 +6,7 @@
  */
 
 export const primitiveColors = {
-  // Blue scale (primary brand)
+  // Blue scale
   blue: {
     50: '#EFF6FF',
     100: '#DBEAFE',
@@ -14,80 +14,38 @@ export const primitiveColors = {
     300: '#93C5FD',
     400: '#60A5FA',
     500: '#3B82F6',
-    600: '#5048E5', // Primary main
-    700: '#3832A0', // Primary dark
+    600: '#5048E5',
+    700: '#3832A0',
     800: '#1E40AF',
     900: '#1E3A8A',
   },
 
-  // Green scale (secondary brand)
-  green: {
-    50: '#ECFDF5',
-    100: '#D1FAE5',
-    200: '#A7F3D0',
-    300: '#6EE7B7',
-    400: '#3FC79A', // Secondary light
-    500: '#10B981', // Secondary main
-    600: '#059669',
-    700: '#0B815A', // Secondary dark
-    800: '#065F46',
-    900: '#064E3B',
-  },
-
-  // Teal scale (success)
-  teal: {
-    50: '#F0FDFA',
-    100: '#CCFBF1',
-    200: '#99F6E4',
-    300: '#5EEAD4',
-    400: '#43C6B7', // Success light
-    500: '#14B8A6', // Success main
-    600: '#0D9488',
-    700: '#0E8074', // Success dark
-    800: '#115E59',
-    900: '#134E4A',
-  },
-
-  // Red scale (error)
+  // Red scale
   red: {
     50: '#FEF2F2',
     100: '#FEE2E2',
     200: '#FECACA',
     300: '#FCA5A5',
-    400: '#DA6868', // Error light
+    400: '#DA6868',
     500: '#EF4444',
-    600: '#D14343', // Error main
-    700: '#922E2E', // Error dark
+    600: '#D14343',
+    700: '#922E2E',
     800: '#991B1B',
     900: '#7F1D1D',
   },
 
-  // Amber scale (warning)
-  amber: {
-    50: '#FFFBEB',
-    100: '#FEF3C7',
-    200: '#FDE68A',
-    300: '#FCD34D',
-    400: '#FFBF4C', // Warning light
-    500: '#FFB020', // Warning main
-    600: '#B27B16', // Warning dark
-    700: '#B45309',
-    800: '#92400E',
-    900: '#78350F',
-  },
-
-  // Sky/Blue scale (info)
-  sky: {
-    50: '#F0F9FF',
-    100: '#E0F2FE',
-    200: '#BAE6FD',
-    300: '#7DD3FC',
-    400: '#64B6F7', // Info light
-    500: '#2196F3', // Info main
-    600: '#0284C7',
-    700: '#0B79D0', // Info dark
-    800: '#075985',
-    900: '#0C4A6E',
+  // Vivid red scale
+  redVivid: {
+    50: '#FFECEE',
+    100: '#FFD6DB',
+    200: '#FFB3BC',
+    300: '#FF8593',
+    400: '#FF6070',
+    500: '#FF4757',
+    600: '#E63548',
+    700: '#C42539',
+    800: '#9E1C2C',
+    900: '#7A1520',
   },
 
   // Neutral/Gray scale
@@ -105,19 +63,6 @@ export const primitiveColors = {
     950: '#030712',
   },
 
-  // Orange scale (accent/brand color)
-  accent: {
-    100: '#FFA860',
-    200: '#FF9630',
-    300: '#FF8500',
-    400: '#FF7900',
-    500: '#F56C00',
-    600: '#E06D10',
-    700: '#D0620C',
-    800: '#B75500',
-    900: '#A34900',
-  },
-
   // Charcoal scale (dark backgrounds)
   charcoal: {
     0: '#6E6E6E',
@@ -133,25 +78,231 @@ export const primitiveColors = {
     900: '#101010',
   },
 
-  // Steel scale (cool accent)
-  steel: {
-    100: '#8AA4B8',
-    200: '#7894A8',
-    300: '#678498',
-    400: '#557488',
-    500: '#406D87',
-    600: '#39617A',
-    700: '#32556D',
-    800: '#243D53',
-    900: '#1D3146',
-  },
-
   // Pure colors
   white: '#FFFFFF',
   black: '#000000',
   transparent: 'transparent',
 } as const
 
+/**
+ * Derived tonal ramps (TD-05.09 color foundations)
+ *
+ * Seven OKLCH-generated hue ramps, 11 perceptual lightness steps each (50 -> 950).
+ * Built with hue-torsion + a chroma arc, anchored through existing brand/semantic
+ * hexes. `pin` marks the step each ramp flows through its anchor.
+ * This is the single source of truth for chromatic hexes — the categorical palette
+ * below references these steps rather than duplicating values.
+ * See coordination/design-explorations/foundations.
+ */
+export const primitiveRamps = {
+  red: {
+    50: '#FFF4F4',
+    100: '#FFE3E5',
+    200: '#FFC2C5',
+    300: '#FF9A9D',
+    400: '#F77175',
+    500: '#E05254',
+    600: '#D14343', // pin
+    700: '#A4221C',
+    800: '#7E1002',
+    900: '#5A0900',
+    950: '#3D0400',
+  },
+  orange: {
+    50: '#FFF5ED',
+    100: '#FFE6D4',
+    200: '#FFC7A2',
+    300: '#FFA063',
+    400: '#FF7900', // pin
+    500: '#DA5F00',
+    600: '#B94A00',
+    700: '#983804',
+    800: '#6F290F',
+    900: '#4E1C0C',
+    950: '#331107',
+  },
+  amber: {
+    50: '#FFF7DD',
+    100: '#FFEAA9',
+    200: '#FFD352',
+    300: '#F9B415', // pin
+    400: '#E08C00',
+    500: '#C27400',
+    600: '#A45E00',
+    700: '#814D14',
+    800: '#5B3A1A',
+    900: '#442503',
+    950: '#301500',
+  },
+  green: {
+    50: '#E3FFEE',
+    100: '#B5FFD2',
+    200: '#58F69E',
+    300: '#2ED573', // pin
+    400: '#21C05D',
+    500: '#22A444',
+    600: '#298732',
+    700: '#2B6B25',
+    800: '#264D1C',
+    900: '#1B3515',
+    950: '#11220D',
+  },
+  cyan: {
+    50: '#E6FBFF',
+    100: '#C2F6FF',
+    200: '#62EAFF',
+    300: '#22D3EE', // pin
+    400: '#01B5D1',
+    500: '#2697B7',
+    600: '#307B9B',
+    700: '#2A617F',
+    800: '#22465F',
+    900: '#0B3149',
+    950: '#001F36',
+  },
+  blue: {
+    50: '#EFF8FF',
+    100: '#D9EFFF',
+    200: '#ACDBFF',
+    300: '#78C2FF',
+    400: '#3CA8FF',
+    500: '#2196F3', // pin
+    600: '#1072CB',
+    700: '#135AA8',
+    800: '#14407E',
+    900: '#112C5A',
+    950: '#091B3C',
+  },
+  magenta: {
+    50: '#FFF3F9',
+    100: '#FFE2F1',
+    200: '#FFBDE2',
+    300: '#FF8FD5',
+    400: '#ED69C3',
+    500: '#D548AF',
+    600: '#BA2996',
+    700: '#9C0D7A', // pin
+    800: '#77005A',
+    900: '#56003F',
+    950: '#3B0029',
+  },
+} as const
+
+/**
+ * Categorical (qualitative) palette — an ordered, CVD-safe series expressed as
+ * references into {@link primitiveRamps} (one source of truth; the palette moves
+ * with the ramps).
+ *
+ * Design: a single canonical hue order (blue, magenta, red, orange, green, cyan,
+ * amber), with steps chosen vivid-midtone-first and fanned lighter/darker as the
+ * series grows to preserve separation. The sequence is nested-stable — a chart
+ * with N series uses the first N colors, and the series index is stable as N
+ * changes. Colorblind-safe worst-case deuteranopia/protanopia floor 8 holds
+ * through {@link CATEGORICAL_CVD_SAFE_MAX} colors; the 7th is an extended color
+ * that should be paired with a legend or other secondary encoding.
+ *
+ * Two variants: `default` (vivid, sits on neutral/light surfaces, legible under
+ * black text) and `dark` (deeper shades legible under white text on a fill). A
+ * separate "light" variant was dropped — the vivid `default` picks already clear
+ * black-text contrast, so it doubles as the light-context palette.
+ */
+export const categoricalPalette = {
+  default: [
+    primitiveRamps.blue[500],
+    primitiveRamps.magenta[500],
+    primitiveRamps.red[500],
+    primitiveRamps.orange[400],
+    primitiveRamps.green[300],
+    primitiveRamps.cyan[300],
+    primitiveRamps.amber[600], // extended (7th) — pair with a legend
+  ],
+  dark: [
+    primitiveRamps.blue[600],
+    primitiveRamps.magenta[600],
+    primitiveRamps.red[500],
+    primitiveRamps.orange[600],
+    primitiveRamps.green[800],
+    primitiveRamps.cyan[800],
+    primitiveRamps.amber[500], // extended (7th) — pair with a legend
+  ],
+} as const
+
+/** Largest series count that holds the CVD floor without a legend. */
+export const CATEGORICAL_CVD_SAFE_MAX = 6
+
+/**
+ * Categorical palette variant.
+ * - `default` : vivid; neutral/light surfaces, legible under black text
+ * - `dark`    : deeper shades, legible under white text on a filled swatch
+ */
+export type CategoricalVariant = keyof typeof categoricalPalette
+
+/**
+ * Get a color from the ordered categorical palette by series index.
+ * The palette is nested-stable, so the color for a given index does not change
+ * with the total series count; `index` simply wraps past the end.
+ *
+ * @param index - 0-based series index (wraps past the end)
+ * @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 {
+  const palette = categoricalPalette[variant]
+  index = Math.max(0, Math.floor(index))
+  return palette[index % palette.length]
+}
+
+/**
+ * Diverging status scale (BodyMap training-status: under → optimal → over) as
+ * references into {@link primitiveRamps}. A true diverging shape — `optimal` is
+ * the lightest center, the extremes go darker — so the signal reads in lightness
+ * (colorblind-robust; worst-case deut/protanopia min ΔE ~10.9) and the direction
+ * reads in the blue↔red axis (the CVD-safe hue pair).
+ *
+ * Tuned so every stop is dark enough for the fill yet light enough that BLACK
+ * text clears 4.5:1 on all five — no per-cell white/black flipping. The value
+ * valley is symmetric: the two mid-arms (maintenance / approaching) sit at equal
+ * lightness (both ~0.53 relative luminance), the ends darker.
+ */
+export const divergingScale = [
+  primitiveRamps.blue[500], // under
+  primitiveRamps.cyan[300], // maintenance
+  primitiveRamps.green[200], // optimal (light center)
+  primitiveRamps.amber[300], // approaching
+  primitiveRamps.red[600], // over
+] as const
+
+/**
+ * Sequential "effort" scale (low → high intensity: green → yellow → orange → red)
+ * as references into {@link primitiveRamps}. A 6-stop ordinal palette; the
+ * velocity/RPE strip sub-samples it. Every adjacent pair clears the CVD floor
+ * (min deut/protan ΔE ≥ 4.5), and within that the hue walk is kept smooth —
+ * the amber-200 → amber-300 → orange-400 run steps the yellow→orange transition
+ * gradually rather than lurching. Order encodes magnitude, so it tolerates the
+ * green↔red CVD pair. Stops 0–3 take black text; the dark reds take white.
+ */
+export const sequentialEffort = [
+  primitiveRamps.green[300],
+  primitiveRamps.amber[200],
+  primitiveRamps.amber[300],
+  primitiveRamps.orange[400],
+  primitiveRamps.red[600],
+  primitiveRamps.red[700],
+] as const
+
+/**
+ * Best-contrast text color (black or white) for a solid fill — for labels sitting
+ * on categorical/diverging/effort swatches. Uses the WCAG relative-luminance ratio.
+ */
+export function bestTextColor(hex: string): '#000000' | '#FFFFFF' {
+  const [r, g, b] = [0, 2, 4].map((i) => {
+    const c = parseInt(hex.replace('#', '').slice(i, i + 2), 16) / 255
+    return c >= 0.04045 ? ((c + 0.055) / 1.055) ** 2.4 : c / 12.92
+  })
+  const l = 0.2126 * r + 0.7152 * g + 0.0722 * b
+  return (l + 0.05) / 0.05 >= 1.05 / (l + 0.05) ? '#000000' : '#FFFFFF'
+}
+
 /**
  * Discrete rainbow palette for data visualization
  * Based on Paul Tol's color schemes: https://personal.sron.nl/~pault/#fig:scheme_rainbow_discrete