@titan-design/react-ui 0.12.0 → 0.13.0

package/src/theme/barrel.ts

@@ -34,14 +34,15 @@ export {
   type ShadowIntensity,
 } from './color-utils'
 export {
-  getElevationConfig,
+  ELEVATION_PLANE,
+  elevationPlane,
   getElevationSurface,
   getElevationShadow,
-  getBaseSurfaceColor,
-  getValidatedElevation,
-  componentElevationRanges,
+  getPressedRecessShadow,
+  FLOATING_ELEVATION_MIN,
+  PRESSED_ELEVATION_LEVEL,
   type ElevationLevel,
-  type ElevationConfig,
-  type ComponentType,
 } from './elevation'
+export * from './lift'
+export * from './surface-planes'
 export * from './presets'

package/src/theme/color-stories.coverage.test.ts

@@ -60,7 +60,7 @@ const DOCUMENTED_ELSEWHERE: Record<string, string> = {
 const isSurfaceToken = (name: string) => /^(surface|background)-/.test(name)
 
 /** Must mirror VARIANT_SUFFIXES in ColorPalettes.stories.tsx (asserted below). */
-const VARIANT_SUFFIXES = ['light', 'dark', 'subtle', 'hover', 'active', 'muted'] as const
+const VARIANT_SUFFIXES = ['light', 'dark', 'subtle', 'muted', 'strong', 'hover', 'active'] as const
 
 describe('Foundations/Color story coverage', () => {
   it('every surface/background token resolves to a plane in the shipped ramp', () => {

package/src/theme/color-utils.ts

@@ -26,9 +26,9 @@
  */
 export function hexToRgb(hex: string): { r: number; g: number; b: number } | null {
   const cleaned = hex.replace('#', '')
-  
+
   let r: number, g: number, b: number
-  
+
   if (cleaned.length === 3) {
     r = parseInt(cleaned[0] + cleaned[0], 16)
     g = parseInt(cleaned[1] + cleaned[1], 16)
@@ -40,7 +40,7 @@ export function hexToRgb(hex: string): { r: number; g: number; b: number } | nul
   } else {
     return null
   }
-  
+
   return { r, g, b }
 }
 
@@ -51,17 +51,17 @@ export function rgbToHsv(r: number, g: number, b: number): { h: number; s: numbe
   const rNorm = r / 255
   const gNorm = g / 255
   const bNorm = b / 255
-  
+
   const max = Math.max(rNorm, gNorm, bNorm)
   const min = Math.min(rNorm, gNorm, bNorm)
   const delta = max - min
-  
+
   // Value
   const v = max
-  
+
   // Saturation
   const s = max === 0 ? 0 : delta / max
-  
+
   // Hue
   let h = 0
   if (delta !== 0) {
@@ -74,7 +74,7 @@ export function rgbToHsv(r: number, g: number, b: number): { h: number; s: numbe
     }
   }
   if (h < 0) h += 360
-  
+
   return { h, s, v }
 }
 
@@ -83,25 +83,37 @@ export function rgbToHsv(r: number, g: number, b: number): { h: number; s: numbe
  */
 export function hsvToRgb(h: number, s: number, v: number): { r: number; g: number; b: number } {
   const c = v * s
-  const x = c * (1 - Math.abs((h / 60) % 2 - 1))
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
   const m = v - c
-  
+
   let rPrime: number, gPrime: number, bPrime: number
 
   if (h >= 0 && h < 60) {
-    rPrime = c; gPrime = x; bPrime = 0
+    rPrime = c
+    gPrime = x
+    bPrime = 0
   } else if (h >= 60 && h < 120) {
-    rPrime = x; gPrime = c; bPrime = 0
+    rPrime = x
+    gPrime = c
+    bPrime = 0
   } else if (h >= 120 && h < 180) {
-    rPrime = 0; gPrime = c; bPrime = x
+    rPrime = 0
+    gPrime = c
+    bPrime = x
   } else if (h >= 180 && h < 240) {
-    rPrime = 0; gPrime = x; bPrime = c
+    rPrime = 0
+    gPrime = x
+    bPrime = c
   } else if (h >= 240 && h < 300) {
-    rPrime = x; gPrime = 0; bPrime = c
+    rPrime = x
+    gPrime = 0
+    bPrime = c
   } else {
-    rPrime = c; gPrime = 0; bPrime = x
+    rPrime = c
+    gPrime = 0
+    bPrime = x
   }
-  
+
   return {
     r: Math.round((rPrime + m) * 255),
     g: Math.round((gPrime + m) * 255),
@@ -122,34 +134,34 @@ export function rgbToHex(r: number, g: number, b: number): string {
 
 /**
  * Lighten a color by increasing its HSV Value component.
- * 
+ *
  * @param hex - The hex color to lighten
  * @param amount - Amount to increase V by (0-1)
  */
 export function lighten(hex: string, amount: number = 0.1): string {
   const rgb = hexToRgb(hex)
   if (!rgb) return hex
-  
+
   const hsv = rgbToHsv(rgb.r, rgb.g, rgb.b)
   const newV = Math.min(1, hsv.v + amount)
-  
+
   const newRgb = hsvToRgb(hsv.h, hsv.s, newV)
   return rgbToHex(newRgb.r, newRgb.g, newRgb.b)
 }
 
 /**
  * Darken a color by decreasing its HSV Value component.
- * 
+ *
  * @param hex - The hex color to darken
  * @param amount - Amount to decrease V by (0-1)
  */
 export function darken(hex: string, amount: number = 0.1): string {
   const rgb = hexToRgb(hex)
   if (!rgb) return hex
-  
+
   const hsv = rgbToHsv(rgb.r, rgb.g, rgb.b)
   const newV = Math.max(0, hsv.v - amount)
-  
+
   const newRgb = hsvToRgb(hsv.h, hsv.s, newV)
   return rgbToHex(newRgb.r, newRgb.g, newRgb.b)
 }
@@ -157,12 +169,12 @@ export function darken(hex: string, amount: number = 0.1): string {
 /**
  * Get hover colors for a button based on its background color.
  * Automatically adapts intensity based on the color's luminance.
- * 
+ *
  * @param bgColor - The button's background color (hex)
  * @param intensity - How strong the hover effect should be ('subtle' | 'medium' | 'strong')
  */
 export function getHoverColors(
-  bgColor: string, 
+  bgColor: string,
   intensity: 'subtle' | 'medium' | 'strong' = 'medium'
 ): { raised: string; pressed: string } {
   const amounts = {
@@ -170,12 +182,12 @@ export function getHoverColors(
     medium: 0.02,
     strong: 0.03,
   }
-  
+
   const amount = amounts[intensity]
-  
+
   return {
-    raised: lighten(bgColor, amount),  // Raised hover: lighten (lifting up)
-    pressed: darken(bgColor, amount),  // Pressed hover: darken (pressing down)
+    raised: lighten(bgColor, amount), // Raised hover: lighten (lifting up)
+    pressed: darken(bgColor, amount), // Pressed hover: darken (pressing down)
   }
 }
 

package/src/theme/config.completeness.test.ts

@@ -69,7 +69,7 @@ describe('token codegen completeness (config.ts vs global.css)', () => {
 
     it(`${mode}: config emits no var absent from global.css`, () => {
       const extra = Object.keys(cfg).filter(
-        (name) => !globalVars.has(name) && !CODEGEN_ALLOWLIST.has(name),
+        (name) => !globalVars.has(name) && !CODEGEN_ALLOWLIST.has(name)
       )
       expect(extra, 'config.ts vars not present in global.css :root').toEqual([])
     })

package/src/theme/config.ts

@@ -43,29 +43,43 @@ export const lightThemeCSSVars = {
   '--color-brand-primary-light': semanticColorsLight['brand-primary-light'],
   '--color-brand-primary-dark': semanticColorsLight['brand-primary-dark'],
   '--color-brand-primary-subtle': semanticColorsLight['brand-primary-subtle'],
+  '--color-brand-primary-muted': semanticColorsLight['brand-primary-muted'],
+  '--color-brand-primary-strong': semanticColorsLight['brand-primary-strong'],
   '--color-brand-secondary': semanticColorsLight['brand-secondary'],
   '--color-brand-secondary-light': semanticColorsLight['brand-secondary-light'],
   '--color-brand-secondary-dark': semanticColorsLight['brand-secondary-dark'],
   '--color-brand-secondary-subtle': semanticColorsLight['brand-secondary-subtle'],
+  '--color-brand-secondary-muted': semanticColorsLight['brand-secondary-muted'],
+  '--color-brand-secondary-strong': semanticColorsLight['brand-secondary-strong'],
 
   '--color-on-brand-primary': semanticColorsLight['on-brand-primary'],
   '--color-on-brand-secondary': semanticColorsLight['on-brand-secondary'],
 
   '--color-status-success': semanticColorsLight['status-success'],
   '--color-status-success-subtle': semanticColorsLight['status-success-subtle'],
+  '--color-status-success-muted': semanticColorsLight['status-success-muted'],
+  '--color-status-success-strong': semanticColorsLight['status-success-strong'],
   '--color-status-live': semanticColorsLight['status-live'],
   '--color-status-live-muted': semanticColorsLight['status-live-muted'],
   '--color-status-error': semanticColorsLight['status-error'],
   '--color-status-error-subtle': semanticColorsLight['status-error-subtle'],
+  '--color-status-error-muted': semanticColorsLight['status-error-muted'],
+  '--color-status-error-strong': semanticColorsLight['status-error-strong'],
   '--color-status-warning': semanticColorsLight['status-warning'],
   '--color-status-warning-subtle': semanticColorsLight['status-warning-subtle'],
+  '--color-status-warning-muted': semanticColorsLight['status-warning-muted'],
+  '--color-status-warning-strong': semanticColorsLight['status-warning-strong'],
   '--color-status-info': semanticColorsLight['status-info'],
   '--color-status-info-subtle': semanticColorsLight['status-info-subtle'],
+  '--color-status-info-muted': semanticColorsLight['status-info-muted'],
+  '--color-status-info-strong': semanticColorsLight['status-info-strong'],
 
   '--color-status-error-vivid': semanticColorsLight['status-error-vivid'],
   '--color-status-error-vivid-light': semanticColorsLight['status-error-vivid-light'],
   '--color-status-error-vivid-dark': semanticColorsLight['status-error-vivid-dark'],
   '--color-status-error-vivid-subtle': semanticColorsLight['status-error-vivid-subtle'],
+  '--color-status-error-vivid-muted': semanticColorsLight['status-error-vivid-muted'],
+  '--color-status-error-vivid-strong': semanticColorsLight['status-error-vivid-strong'],
 
   '--color-text-primary': semanticColorsLight['text-primary'],
   '--color-text-secondary': semanticColorsLight['text-secondary'],
@@ -166,29 +180,43 @@ export const darkThemeCSSVars = {
   '--color-brand-primary-light': semanticColorsDark['brand-primary-light'],
   '--color-brand-primary-dark': semanticColorsDark['brand-primary-dark'],
   '--color-brand-primary-subtle': semanticColorsDark['brand-primary-subtle'],
+  '--color-brand-primary-muted': semanticColorsDark['brand-primary-muted'],
+  '--color-brand-primary-strong': semanticColorsDark['brand-primary-strong'],
   '--color-brand-secondary': semanticColorsDark['brand-secondary'],
   '--color-brand-secondary-light': semanticColorsDark['brand-secondary-light'],
   '--color-brand-secondary-dark': semanticColorsDark['brand-secondary-dark'],
   '--color-brand-secondary-subtle': semanticColorsDark['brand-secondary-subtle'],
+  '--color-brand-secondary-muted': semanticColorsDark['brand-secondary-muted'],
+  '--color-brand-secondary-strong': semanticColorsDark['brand-secondary-strong'],
 
   '--color-on-brand-primary': semanticColorsDark['on-brand-primary'],
   '--color-on-brand-secondary': semanticColorsDark['on-brand-secondary'],
 
   '--color-status-success': semanticColorsDark['status-success'],
   '--color-status-success-subtle': semanticColorsDark['status-success-subtle'],
+  '--color-status-success-muted': semanticColorsDark['status-success-muted'],
+  '--color-status-success-strong': semanticColorsDark['status-success-strong'],
   '--color-status-live': semanticColorsDark['status-live'],
   '--color-status-live-muted': semanticColorsDark['status-live-muted'],
   '--color-status-error': semanticColorsDark['status-error'],
   '--color-status-error-subtle': semanticColorsDark['status-error-subtle'],
+  '--color-status-error-muted': semanticColorsDark['status-error-muted'],
+  '--color-status-error-strong': semanticColorsDark['status-error-strong'],
   '--color-status-warning': semanticColorsDark['status-warning'],
   '--color-status-warning-subtle': semanticColorsDark['status-warning-subtle'],
+  '--color-status-warning-muted': semanticColorsDark['status-warning-muted'],
+  '--color-status-warning-strong': semanticColorsDark['status-warning-strong'],
   '--color-status-info': semanticColorsDark['status-info'],
   '--color-status-info-subtle': semanticColorsDark['status-info-subtle'],
+  '--color-status-info-muted': semanticColorsDark['status-info-muted'],
+  '--color-status-info-strong': semanticColorsDark['status-info-strong'],
 
   '--color-status-error-vivid': semanticColorsDark['status-error-vivid'],
   '--color-status-error-vivid-light': semanticColorsDark['status-error-vivid-light'],
   '--color-status-error-vivid-dark': semanticColorsDark['status-error-vivid-dark'],
   '--color-status-error-vivid-subtle': semanticColorsDark['status-error-vivid-subtle'],
+  '--color-status-error-vivid-muted': semanticColorsDark['status-error-vivid-muted'],
+  '--color-status-error-vivid-strong': semanticColorsDark['status-error-vivid-strong'],
 
   '--color-text-primary': semanticColorsDark['text-primary'],
   '--color-text-secondary': semanticColorsDark['text-secondary'],

package/src/theme/elevation.test.ts

@@ -1,88 +1,114 @@
 import { describe, it, expect } from 'vitest'
-import { getGlowShadow, getElevationSurface, getElevationShadow, getBaseSurfaceColor, FLOATING_ELEVATION_MIN } from './elevation'
+import {
+  ELEVATION_PLANE,
+  FLOATING_ELEVATION_MIN,
+  getElevationShadow,
+  getElevationSurface,
+  getGlowShadow,
+  getPressedRecessShadow,
+  type ElevationLevel,
+} from './elevation'
+import { getSemanticColors } from './tokens/semantic'
+import { surfaceBackground, PLANE_ORDER } from './surface-planes'
+
+const web = (style: object) => style as { boxShadow?: string }
 
 describe('getGlowShadow', () => {
   it('returns shadow style for valid hex color', () => {
     const style = getGlowShadow('#FF7900', 'medium')
-    expect(style).toBeDefined()
     expect(Object.keys(style).length).toBeGreaterThan(0)
   })
 
   it('returns empty object for invalid color', () => {
-    const style = getGlowShadow('not-a-color')
-    expect(style).toEqual({})
+    expect(getGlowShadow('not-a-color')).toEqual({})
   })
 
   it('scales intensity across levels', () => {
-    const subtle = getGlowShadow('#FF7900', 'subtle')
-    const strong = getGlowShadow('#FF7900', 'strong')
-    expect(subtle).not.toEqual(strong)
+    expect(getGlowShadow('#FF7900', 'subtle')).not.toEqual(getGlowShadow('#FF7900', 'strong'))
   })
 
   it('defaults to medium intensity', () => {
-    const defaultStyle = getGlowShadow('#FF7900')
-    const mediumStyle = getGlowShadow('#FF7900', 'medium')
-    expect(defaultStyle).toEqual(mediumStyle)
+    expect(getGlowShadow('#FF7900')).toEqual(getGlowShadow('#FF7900', 'medium'))
   })
 })
 
-// ── TD-07.16: the depth model ───────────────────────────────────────────────
-
-describe('elevation depth model', () => {
-  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 fl = (t: number) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116)
-  const Lstar = (hex: string) => {
-    const [r, g, b] = hex2rgb(hex).map(srgb2lin)
-    return 116 * fl(r * 0.2126729 + g * 0.7151522 + b * 0.072175) - 16
-  }
-
-  const base = getBaseSurfaceColor('dark')
-
-  /**
-   * With drop-shadow gated off below FLOATING_ELEVATION_MIN, TONE is the only
-   * thing separating levels 0-3. Level 1 previously moved 0.01 (~2 RGB), which
-   * is under the perceptual floor — so the level existed in the type system and
-   * nowhere on screen.
-   */
-  it('separates every adjacent content level by a visible tonal step', () => {
-    const levels = [0, 1, 2, 3] as const
-    for (let i = 1; i < levels.length; i++) {
-      const prev = Lstar(getElevationSurface(base, levels[i - 1], 'dark'))
-      const cur = Lstar(getElevationSurface(base, levels[i], 'dark'))
-      const step = cur - prev
-      expect(step, `L${levels[i - 1]}→L${levels[i]} moves ΔL* ${step.toFixed(2)}`).toBeGreaterThan(1)
+describe('elevation resolves to the grey ramp', () => {
+  const LEVELS: ElevationLevel[] = [-2, -1, 0, 1, 2, 3, 4, 5]
+  const dark = getSemanticColors('dark')
+  const rampHexes = new Set(PLANE_ORDER.map((plane) => surfaceBackground(plane, 'dark')))
+
+  it('every level paints a plane that is on the ramp, never a derived colour', () => {
+    for (const level of LEVELS) {
+      const hex = getElevationSurface(level, 'dark')
+      expect(rampHexes.has(hex), `level ${level} → ${hex}`).toBe(true)
     }
   })
 
-  it('gets lighter as it rises, never darker', () => {
-    const ls = ([0, 1, 2, 3, 4, 5] as const).map((lv) => Lstar(getElevationSurface(base, lv, 'dark')))
-    for (let i = 1; i < ls.length; i++) expect(ls[i]).toBeGreaterThan(ls[i - 1])
+  it('reads the page plane at 0 and climbs one plane per content level', () => {
+    expect(getElevationSurface(0, 'dark')).toBe(dark['surface-base'])
+    expect(getElevationSurface(1, 'dark')).toBe(dark['surface-elevated'])
+    expect(getElevationSurface(2, 'dark')).toBe(dark['surface-raised'])
+    expect(getElevationSurface(3, 'dark')).toBe(dark['surface-overlay'])
+  })
+
+  it('floating levels share the overlay plane: past the ramp, the shadow separates', () => {
+    expect(ELEVATION_PLANE[4]).toBe('overlay')
+    expect(ELEVATION_PLANE[5]).toBe('overlay')
+    expect(FLOATING_ELEVATION_MIN).toBe(4)
   })
 
-  it('casts NO outward shadow below the floating threshold', () => {
-    // Dark-on-dark drop shadows are inert — they cost a composite layer and
-    // show nothing. Inline hierarchy is the hairline's job.
-    for (const lv of [1, 2, 3] as const) {
-      expect(getElevationShadow(base, lv, 'dark'), `level ${lv}`).toEqual({})
+  it('steps down the ramp below zero', () => {
+    expect(getElevationSurface(-1, 'dark')).toBe(dark['background-base'])
+    expect(getElevationSurface(-2, 'dark')).toBe(dark['background-frame'])
+  })
+})
+
+describe('elevation treatment: recess below, nothing at 0, lift above', () => {
+  it('wears no treatment at level 0', () => {
+    expect(getElevationShadow(0, 'dark')).toEqual({})
+  })
+
+  it('lifts every content level with a top rim-light AND an ambient shadow', () => {
+    for (const level of [1, 2, 3] as const) {
+      const shadow = web(getElevationShadow(level, 'dark')).boxShadow ?? ''
+      expect(shadow, `level ${level} rim`).toContain('inset 0 1px 0 rgba(255,255,255,0.12)')
+      expect(
+        shadow.split(', ').filter((layer) => !layer.startsWith('inset')).length
+      ).toBeGreaterThan(0)
     }
   })
 
-  it('does cast one at and above the floating threshold', () => {
-    for (const lv of [FLOATING_ELEVATION_MIN, 5] as const) {
-      expect(Object.keys(getElevationShadow(base, lv, 'dark')).length, `level ${lv}`).toBeGreaterThan(0)
+  it('grows the ambient shadow with each content level', () => {
+    const reach = (level: ElevationLevel) => {
+      const layers = web(getElevationShadow(level, 'dark')).boxShadow!.split(', ')
+      return Math.max(...layers.map((l) => Number(/0 (\d+)px/.exec(l)?.[1] ?? 0)))
     }
+    expect(reach(1)).toBeLessThan(reach(2))
+    expect(reach(2)).toBeLessThan(reach(3))
+    expect(reach(3)).toBeLessThan(reach(4))
+    expect(reach(4)).toBeLessThan(reach(5))
+  })
+
+  it('floats without a hairline ring: lift is rim + shadow only', () => {
+    const style = getElevationShadow(4, 'dark') as Record<string, unknown>
+    expect(style.borderWidth).toBeUndefined()
+    expect(style.borderColor).toBeUndefined()
   })
 
-  it('keeps the recess on inset levels — a well is not a cast shadow', () => {
-    for (const lv of [-1, -2] as const) {
-      expect(Object.keys(getElevationShadow(base, lv, 'dark')).length, `level ${lv}`).toBeGreaterThan(0)
+  it('lets a caller drop the rim for a specimen', () => {
+    expect(web(getElevationShadow(2, 'dark', { rim: 0 })).boxShadow).not.toContain('inset')
+  })
+
+  it('recesses inset levels with the insetWell cut, not a cast shadow', () => {
+    for (const level of [-1, -2] as const) {
+      const shadow = web(getElevationShadow(level, 'dark')).boxShadow ?? ''
+      expect(shadow, `level ${level}`).toContain('inset 0 2px 6px')
+      expect(shadow, `level ${level}`).toContain('inset 0 -1px 0')
     }
   })
+
+  it('getPressedRecessShadow returns the same cut for a given fill', () => {
+    const fill = getSemanticColors('dark')['background-base']
+    expect(web(getPressedRecessShadow(fill, 'dark')).boxShadow).toContain('inset')
+  })
 })