@ultimat3/ui 24.0.0 → 25.1.0

package/src/tokens/_touch.scss

@@ -0,0 +1,39 @@
+// The touch target: the smallest box a finger can hit reliably. WCAG 2.5.5's 44 CSS px, as rem
+// so a reader's larger text grows the target with it. One rung, in a map so it emits and reads
+// back like every other scale.
+
+$touch: (
+  target: 2.75rem,
+);
+
+@mixin emit {
+  :root {
+    @each $name, $value in $touch {
+      --touch-#{$name}: #{$value};
+    }
+  }
+}
+
+@function touch($name) {
+  @return var(--touch-#{$name});
+}
+
+/// Make the element hittable. Default: the box itself is at least the target, both axes. With
+/// `$extend: true` the BOX keeps its size and an invisible `::after` grows the hit area around it,
+/// centred — for a chart point, a dense icon row, a close glyph whose visual size is the design.
+/// The pseudo-element is the element's own, so its clicks are the element's clicks.
+@mixin touch-target($extend: false) {
+  @if $extend {
+    position: relative;
+
+    &::after {
+      content: '';
+      position: absolute;
+      inset-block: min(0px, calc((100% - #{touch(target)}) / 2));
+      inset-inline: min(0px, calc((100% - #{touch(target)}) / 2));
+    }
+  } @else {
+    min-block-size: touch(target);
+    min-inline-size: touch(target);
+  }
+}

package/src/tokens/_typography.scss

@@ -18,6 +18,20 @@ $font-family: (
     Consolas,
     monospace,
   ),
+  // Numbers in columns: a monospace-friendly stack whose figures align without `tnum` support,
+  // read through `@include t.data-text`, which adds `tabular-nums` for every family that has it.
+  // A slot of its own so a brand can put a proportional face with tabular figures here and keep
+  // `mono` for code.
+  data: (
+    ui-monospace,
+    'SFMono-Regular',
+    'Cascadia Mono',
+    'JetBrains Mono',
+    'Roboto Mono',
+    Menlo,
+    Consolas,
+    monospace,
+  ),
 );
 
 $font-size: (

package/src/tokens/color-tokens.ts

@@ -0,0 +1,133 @@
+// The colour half of the typed token mirror: every role, the chart series among them, and their
+// channels per theme. `_colors.scss` is CANONICAL; `tokens.test.ts` fails if the two disagree.
+// Split from `tokens.ts` by size alone — `tokens.ts` re-exports all of it, so there is one import.
+
+export type Theme = 'light' | 'dark';
+
+export const COLOR_ROLES = [
+  'bg',
+  'bg-soft',
+  'surface',
+  'surface-raised',
+  'fg',
+  'fg-strong',
+  'fg-muted',
+  'line',
+  'scrim',
+  'accent',
+  'accent-strong',
+  'accent-fg',
+  'success',
+  'success-soft',
+  'success-fg',
+  'warning',
+  'warning-soft',
+  'warning-fg',
+  'danger',
+  'danger-soft',
+  'danger-fg',
+  'info',
+  'info-soft',
+  'info-fg',
+  'chart-1',
+  'chart-2',
+  'chart-3',
+  'chart-4',
+  'chart-5',
+  'chart-6',
+  'chart-7',
+  'chart-8',
+] as const;
+
+export type ColorRole = (typeof COLOR_ROLES)[number];
+
+/**
+ * The categorical series, in the order a chart assigns them. Okabe–Ito-derived and measured, not
+ * picked: 3:1 against every surface (`CONTRAST_PAIRS`) and apart under protan, deutan and tritan
+ * simulation (`colour-vision.test.ts`). A ninth series reuses `chart-1` with a second encoding —
+ * a dash, a pattern, a label — never a ninth hue.
+ */
+export const CHART_ROLES = [
+  'chart-1',
+  'chart-2',
+  'chart-3',
+  'chart-4',
+  'chart-5',
+  'chart-6',
+  'chart-7',
+  'chart-8',
+] as const satisfies readonly ColorRole[];
+
+export type ChartRole = (typeof CHART_ROLES)[number];
+
+/** Space-separated RGB channels, mirroring `_colors.scss`. */
+export const colorTokens: Readonly<Record<Theme, Readonly<Record<ColorRole, string>>>> = {
+  light: {
+    bg: '253 246 240',
+    'bg-soft': '245 237 230',
+    surface: '250 245 241',
+    'surface-raised': '255 255 255',
+    fg: '38 34 31',
+    'fg-strong': '17 15 13',
+    'fg-muted': '110 102 94',
+    line: '208 198 188',
+    scrim: '17 15 13',
+    accent: '31 110 178',
+    'accent-strong': '21 92 152',
+    'accent-fg': '255 255 255',
+    success: '21 123 80',
+    'success-soft': '222 244 232',
+    'success-fg': '255 255 255',
+    warning: '155 93 7',
+    'warning-soft': '253 240 213',
+    'warning-fg': '255 255 255',
+    danger: '190 42 42',
+    'danger-soft': '253 227 227',
+    'danger-fg': '255 255 255',
+    info: '31 110 178',
+    'info-soft': '224 239 252',
+    'info-fg': '255 255 255',
+    'chart-1': '0 107 170',
+    'chart-2': '189 107 14',
+    'chart-3': '0 125 90',
+    'chart-4': '189 44 16',
+    'chart-5': '170 70 140',
+    'chart-6': '47 135 195',
+    'chart-7': '118 97 18',
+    'chart-8': '60 60 60',
+  },
+  dark: {
+    bg: '18 18 20',
+    'bg-soft': '28 28 32',
+    surface: '34 34 39',
+    'surface-raised': '44 44 50',
+    fg: '228 226 222',
+    'fg-strong': '248 247 245',
+    'fg-muted': '155 151 145',
+    line: '72 72 80',
+    scrim: '0 0 0',
+    accent: '96 170 240',
+    'accent-strong': '130 190 248',
+    'accent-fg': '16 20 26',
+    success: '74 190 130',
+    'success-soft': '22 46 34',
+    'success-fg': '12 26 18',
+    warning: '226 170 66',
+    'warning-soft': '52 42 20',
+    'warning-fg': '28 20 6',
+    danger: '240 110 110',
+    'danger-soft': '56 26 26',
+    'danger-fg': '30 12 12',
+    info: '96 170 240',
+    'info-soft': '22 38 56',
+    'info-fg': '12 20 30',
+    'chart-1': '105 201 255',
+    'chart-2': '230 153 0',
+    'chart-3': '0 167 113',
+    'chart-4': '236 111 60',
+    'chart-5': '203 126 189',
+    'chart-6': '124 153 252',
+    'chart-7': '246 234 72',
+    'chart-8': '181 181 180',
+  },
+} as const;

package/src/tokens/colour-vision.ts

@@ -0,0 +1,106 @@
+// Colour-vision simulation and perceptual distance over channel tokens, so "the chart series are
+// colour-blind safe" is a measured claim (`colour-vision.test.ts`) and an app can measure its own
+// series before it ships them. Machado, Oliveira & Fernandes (2009) at full severity, applied in
+// linear sRGB; distance is CIE76 ΔE in CIELAB (D65).
+
+/**
+ * A simulated dichromat can land a hair outside sRGB; the display clips it. Its own helper, away
+ * from the transfer curve, because the clip is a gamut fact, not part of the curve.
+ */
+const inGamut = (linear: number): number => Math.min(1, Math.max(0, linear));
+
+import { linearize, parseChannels } from './contrast';
+
+/** The three dichromacies. `typical` is the identity, so one loop covers every reader. */
+export const COLOUR_VISIONS = ['protan', 'deutan', 'tritan'] as const;
+export type ColourVision = (typeof COLOUR_VISIONS)[number] | 'typical';
+
+/**
+ * The floor two series must stay apart by, in ΔE76, under every vision. ~2.3 is a just-noticeable
+ * difference for two large flat patches; a chart compares thin lines and small slices with a gap
+ * between them, so the floor is set well above it. Measured headroom (`As of 2026-10`): the
+ * shipped light palette's closest pair is 10.7, its dark one 20.1.
+ */
+export const CHART_DISTINCT_MIN = 10;
+
+type Matrix = readonly [
+  readonly [number, number, number],
+  readonly [number, number, number],
+  readonly [number, number, number],
+];
+
+const MACHADO: Readonly<Record<(typeof COLOUR_VISIONS)[number], Matrix>> = {
+  protan: [
+    [0.152286, 1.052583, -0.204868],
+    [0.114503, 0.786281, 0.099216],
+    [-0.003882, -0.048116, 1.051998],
+  ],
+  deutan: [
+    [0.367322, 0.860646, -0.227968],
+    [0.280085, 0.672501, 0.047413],
+    [-0.01182, 0.04294, 0.968881],
+  ],
+  tritan: [
+    [1.255528, -0.076749, -0.178779],
+    [-0.078411, 0.930809, 0.147602],
+    [0.004733, 0.691367, 0.3039],
+  ],
+};
+
+/** Linear light back to an sRGB channel — the inverse of contrast.ts's `linearize`. */
+const toChannel = (linear: number): number => {
+  const v = inGamut(linear);
+  const encoded = v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055;
+  return Math.round(encoded * 255);
+};
+
+/** `"R G B"` as a reader with `vision` sees it, in the same channel spelling. */
+export function simulateColourVision(channels: string, vision: ColourVision): string {
+  if (vision === 'typical') return channels;
+  const [r, g, b] = parseChannels(channels).map(linearize) as [number, number, number];
+  return MACHADO[vision].map((row) => toChannel(row[0] * r + row[1] * g + row[2] * b)).join(' ');
+}
+
+const labF = (t: number): number =>
+  t > 216 / 24389 ? Math.cbrt(t) : ((24389 / 27) * t) / 116 + 16 / 116;
+
+function lab(channels: string): readonly [number, number, number] {
+  const [r, g, b] = parseChannels(channels).map(linearize) as [number, number, number];
+  const x = labF((0.4124 * r + 0.3576 * g + 0.1805 * b) / 0.95047);
+  const y = labF(0.2126 * r + 0.7152 * g + 0.0722 * b);
+  const z = labF((0.0193 * r + 0.1192 * g + 0.9505 * b) / 1.08883);
+  return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
+}
+
+/** CIE76 ΔE between two channel strings. 0 is identical; black to white is 100. */
+export function colourDistance(a: string, b: string): number {
+  const [l1, a1, b1] = lab(a);
+  const [l2, a2, b2] = lab(b);
+  return Math.hypot(l1 - l2, a1 - a2, b1 - b2);
+}
+
+export interface ClosestPair {
+  /** Indexes into the palette, `a < b`. */
+  readonly a: number;
+  readonly b: number;
+  readonly vision: ColourVision;
+  readonly distance: number;
+}
+
+/**
+ * The two series hardest to tell apart, and for whom. One answer rather than a matrix: a palette
+ * is as safe as its closest pair, and the pair is what an author has to move.
+ */
+export function closestChartPair(palette: readonly string[]): ClosestPair {
+  let closest: ClosestPair = { a: 0, b: 0, vision: 'typical', distance: Number.POSITIVE_INFINITY };
+  for (const vision of ['typical', ...COLOUR_VISIONS] as const) {
+    const seen = palette.map((channels) => simulateColourVision(channels, vision));
+    for (let a = 0; a < seen.length; a += 1) {
+      for (let b = a + 1; b < seen.length; b += 1) {
+        const distance = colourDistance(seen[a] as string, seen[b] as string);
+        if (distance < closest.distance) closest = { a, b, vision, distance };
+      }
+    }
+  }
+  return closest;
+}

package/src/tokens/contrast-pairs.ts

@@ -11,8 +11,8 @@
 // benchmark (EN 301 549, ADA Title II, the EAA). 4.5:1 for body text (1.4.3), 3:1 for large text
 // and non-text UI (1.4.11).
 
+import { CHART_ROLES, type ColorRole } from './color-tokens';
 import { AA_LARGE, AA_TEXT } from './contrast';
-import type { ColorRole } from './tokens';
 
 /** What a page, a card and a raised panel are made of. */
 const SURFACES: readonly ColorRole[] = ['bg', 'bg-soft', 'surface', 'surface-raised'];
@@ -68,4 +68,9 @@ export const CONTRAST_PAIRS: readonly ContrastPair[] = [
   ...STATUS.flatMap((status) => onSurfaces(status, AA_TEXT, 'status text on a surface')),
   ...onSurfaces('accent', AA_LARGE, 'the focus ring against a surface'),
   ...onSurfaces('line', VISIBLE_EDGE, 'a border or divider against a surface'),
+  // A series mark is non-text UI (1.4.11), and a dashboard puts the same series on the page, in a
+  // card and in a raised popover — so every surface, not the one a chart usually sits on.
+  ...CHART_ROLES.flatMap((role) =>
+    onSurfaces(role, AA_LARGE, `the ${role} series mark — a bar, line or slice — on a surface`),
+  ),
 ];

package/src/tokens/contrast.ts

@@ -31,7 +31,7 @@ export function parseChannels(value: string): Channels {
 }
 
 // sRGB → linear, then the ITU-R BT.709 luma weights WCAG specifies.
-function linearize(channel: number): number {
+export function linearize(channel: number): number {
   const v = channel / 255;
   return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
 }

package/src/tokens/theme.scss

@@ -8,6 +8,7 @@
 @use 'shadow';
 @use 'space';
 @use 'stroke';
+@use 'touch';
 @use 'typography';
 @use 'z';
 
@@ -16,6 +17,7 @@
 @include space.emit;
 @include radius.emit;
 @include stroke.emit;
+@include touch.emit;
 @include typography.emit;
 @include motion.emit;
 @include z.emit;

package/src/tokens/tokens.ts

@@ -5,93 +5,10 @@
 // `tokens.test.ts` (run by `x verify`) fails if the two ever disagree.
 
 import { unknownTokenError } from '../errors';
+import { COLOR_ROLES, type ColorRole, colorTokens, type Theme } from './color-tokens';
 
-export type Theme = 'light' | 'dark';
-
-export const COLOR_ROLES = [
-  'bg',
-  'bg-soft',
-  'surface',
-  'surface-raised',
-  'fg',
-  'fg-strong',
-  'fg-muted',
-  'line',
-  'scrim',
-  'accent',
-  'accent-strong',
-  'accent-fg',
-  'success',
-  'success-soft',
-  'success-fg',
-  'warning',
-  'warning-soft',
-  'warning-fg',
-  'danger',
-  'danger-soft',
-  'danger-fg',
-  'info',
-  'info-soft',
-  'info-fg',
-] as const;
-
-export type ColorRole = (typeof COLOR_ROLES)[number];
-
-/** Space-separated RGB channels, mirroring `_colors.scss`. */
-export const colorTokens: Readonly<Record<Theme, Readonly<Record<ColorRole, string>>>> = {
-  light: {
-    bg: '253 246 240',
-    'bg-soft': '245 237 230',
-    surface: '250 245 241',
-    'surface-raised': '255 255 255',
-    fg: '38 34 31',
-    'fg-strong': '17 15 13',
-    'fg-muted': '110 102 94',
-    line: '208 198 188',
-    scrim: '17 15 13',
-    accent: '31 110 178',
-    'accent-strong': '21 92 152',
-    'accent-fg': '255 255 255',
-    success: '21 123 80',
-    'success-soft': '222 244 232',
-    'success-fg': '255 255 255',
-    warning: '155 93 7',
-    'warning-soft': '253 240 213',
-    'warning-fg': '255 255 255',
-    danger: '190 42 42',
-    'danger-soft': '253 227 227',
-    'danger-fg': '255 255 255',
-    info: '31 110 178',
-    'info-soft': '224 239 252',
-    'info-fg': '255 255 255',
-  },
-  dark: {
-    bg: '18 18 20',
-    'bg-soft': '28 28 32',
-    surface: '34 34 39',
-    'surface-raised': '44 44 50',
-    fg: '228 226 222',
-    'fg-strong': '248 247 245',
-    'fg-muted': '155 151 145',
-    line: '72 72 80',
-    scrim: '0 0 0',
-    accent: '96 170 240',
-    'accent-strong': '130 190 248',
-    'accent-fg': '16 20 26',
-    success: '74 190 130',
-    'success-soft': '22 46 34',
-    'success-fg': '12 26 18',
-    warning: '226 170 66',
-    'warning-soft': '52 42 20',
-    'warning-fg': '28 20 6',
-    danger: '240 110 110',
-    'danger-soft': '56 26 26',
-    'danger-fg': '30 12 12',
-    info: '96 170 240',
-    'info-soft': '22 38 56',
-    'info-fg': '12 20 30',
-  },
-} as const;
+export type { ChartRole, ColorRole, Theme } from './color-tokens';
+export { CHART_ROLES, COLOR_ROLES, colorTokens } from './color-tokens';
 
 export const spaceTokens = {
   '0': '0',
@@ -153,13 +70,39 @@ export const easingTokens = {
   spring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
 } as const;
 
-export const shadowTokens: Readonly<Record<Theme, Readonly<Record<string, string>>>> = {
+/**
+ * The elevation rungs, then the two accent-drawn families: `glow-*` (a halo, no offset — a focused
+ * or live edge) and `tinted-*` (a lift whose shadow carries the accent hue — coloured elevation).
+ */
+export const SHADOW_NAMES = [
+  'xs',
+  'sm',
+  'md',
+  'lg',
+  'xl',
+  'glow-sm',
+  'glow-md',
+  'glow-lg',
+  'tinted-sm',
+  'tinted-md',
+  'tinted-lg',
+] as const;
+
+export type ShadowName = (typeof SHADOW_NAMES)[number];
+
+export const shadowTokens: Readonly<Record<Theme, Readonly<Record<ShadowName, string>>>> = {
   light: {
     xs: '0 1px 2px rgb(17 15 13 / 0.06)',
     sm: '0 2px 6px rgb(17 15 13 / 0.08)',
     md: '0 4px 14px rgb(17 15 13 / 0.1)',
     lg: '0 12px 32px rgb(17 15 13 / 0.14)',
     xl: '0 24px 56px rgb(17 15 13 / 0.18)',
+    'glow-sm': '0 0 6px rgb(var(--color-accent) / 0.28)',
+    'glow-md': '0 0 14px rgb(var(--color-accent) / 0.26)',
+    'glow-lg': '0 0 28px rgb(var(--color-accent) / 0.24)',
+    'tinted-sm': '0 2px 8px rgb(var(--color-accent) / 0.14)',
+    'tinted-md': '0 6px 18px rgb(var(--color-accent) / 0.16)',
+    'tinted-lg': '0 14px 36px rgb(var(--color-accent) / 0.18)',
   },
   dark: {
     xs: '0 1px 2px rgb(0 0 0 / 0.4)',
@@ -167,9 +110,20 @@ export const shadowTokens: Readonly<Record<Theme, Readonly<Record<string, string
     md: '0 6px 20px rgb(0 0 0 / 0.56)',
     lg: '0 16px 40px rgb(0 0 0 / 0.64)',
     xl: '0 28px 64px rgb(0 0 0 / 0.72)',
+    'glow-sm': '0 0 6px rgb(var(--color-accent) / 0.45)',
+    'glow-md': '0 0 14px rgb(var(--color-accent) / 0.4)',
+    'glow-lg': '0 0 28px rgb(var(--color-accent) / 0.35)',
+    'tinted-sm': '0 2px 8px rgb(var(--color-accent) / 0.24)',
+    'tinted-md': '0 6px 18px rgb(var(--color-accent) / 0.28)',
+    'tinted-lg': '0 14px 36px rgb(var(--color-accent) / 0.32)',
   },
 } as const;
 
+/** WCAG 2.5.5's 44 CSS px, as rem so a reader's larger text grows the target with it. */
+export const touchTokens = {
+  target: '2.75rem',
+} as const;
+
 export const breakpointTokens = {
   sm: '480px',
   md: '768px',