@ultimat3/ui 1.0.0 → 1.1.0

package/src/theme/brand.ts

@@ -0,0 +1,155 @@
+// The ONE way to restyle the design system without forking it: `defineTheme()` validates a set of
+// token overrides and renders the custom properties that beat `theme.scss` at every specificity
+// level it emits. There is deliberately no SCSS `@use ... with ()` seam — two ways to change the
+// accent colour is the ambiguity axiom 1 exists to delete.
+
+import { invalidBrandTokenError, unknownTokenError } from '../errors';
+import { parseChannels } from '../tokens/contrast';
+import {
+  COLOR_ROLES,
+  type ColorRole,
+  type RadiusName,
+  radiusTokens,
+  type Theme,
+} from '../tokens/tokens';
+
+/** The two font slots `_typography.scss` emits. */
+export const FONT_SLOTS = ['sans', 'mono'] as const;
+export type FontSlot = (typeof FONT_SLOTS)[number];
+
+export interface BrandInput {
+  /** Channel overrides per theme. Omit a theme to leave it at the shipped palette. */
+  colors?: Partial<Record<Theme, Partial<Record<ColorRole, string>>>> | undefined;
+  radius?: Partial<Record<RadiusName, string>> | undefined;
+  font?: Partial<Record<FontSlot, string>> | undefined;
+}
+
+export interface Brand {
+  /** The stylesheet text. Ship it in a `<style>` after `global.scss`, or write it to a file. */
+  readonly css: string;
+}
+
+/** `0` or a number with a CSS length unit. No `calc()`, no `var()` — a scale rung is a value. */
+const LENGTH_PATTERN = /^(0|\d+(\.\d+)?(px|rem|em|ch|%))$/;
+
+/** Family names, quotes and separators only: everything a `font-family` list legitimately needs. */
+const FONT_STACK_PATTERN = /^[\w\s,'"-]{1,200}$/;
+
+const LENGTH_EXPECTED = 'a bare CSS length such as "0.5rem", "4px" or "0"';
+const STACK_EXPECTED = 'a font-family list such as "Inter, system-ui, sans-serif"';
+const CHANNELS_EXPECTED = 'space-separated RGB channels such as "31 110 178"';
+
+/**
+ * Validate and freeze a brand. Every value is checked here rather than at render time, so a bad
+ * override fails at the app's entry point with the role that broke it named — not as a silently
+ * dropped declaration a human has to spot in devtools.
+ */
+export function defineTheme(input: BrandInput): Brand {
+  const blocks: string[] = [];
+  const light = colorDeclarations(input.colors?.light, 'colors.light');
+  const dark = colorDeclarations(input.colors?.dark, 'colors.dark');
+  const root: string[] = [
+    ...light,
+    ...radiusDeclarations(input.radius),
+    ...fontDeclarations(input.font),
+  ];
+  if (root.length > 0) blocks.push(rule(':root', root));
+
+  // `theme.scss` emits light at `:root`, dark behind the media query, and BOTH again under
+  // `html[data-theme]`. A brand that only wrote `:root` would lose to those attribute rules on
+  // specificity, so every level it emits is answered here, in the same order.
+  if (light.length > 0) blocks.push(rule("html[data-theme='light']", light));
+  if (dark.length > 0) {
+    blocks.push(`@media (prefers-color-scheme: dark) {\n${indent(rule(':root', dark))}\n}`);
+    blocks.push(rule("html[data-theme='dark']", dark));
+  }
+
+  return Object.freeze({ css: blocks.join('\n\n') });
+}
+
+/** The exact tag to inline, after `global.scss` so the overrides land later in the cascade. */
+export function brandStyleTag(brand: Brand): string {
+  return `<style>${brand.css}</style>`;
+}
+
+function rule(selector: string, declarations: readonly string[]): string {
+  return `${selector} {\n${declarations.map((line) => `  ${line}`).join('\n')}\n}`;
+}
+
+function indent(block: string): string {
+  return block
+    .split('\n')
+    .map((line) => `  ${line}`)
+    .join('\n');
+}
+
+/**
+ * Ordered by the canonical role list, not by the caller's object — a brand file rendered twice
+ * must be byte-identical, or every consumer's CSP hash and diff churns for nothing.
+ */
+function colorDeclarations(
+  overrides: Partial<Record<ColorRole, string>> | undefined,
+  scope: string,
+): string[] {
+  if (overrides === undefined) return [];
+  for (const role of Object.keys(overrides)) {
+    if (!(COLOR_ROLES as readonly string[]).includes(role)) {
+      throw unknownTokenError('color', role, COLOR_ROLES);
+    }
+  }
+  const out: string[] = [];
+  for (const role of COLOR_ROLES) {
+    const value = overrides[role];
+    if (value === undefined) continue;
+    assertChannels(scope, role, value);
+    out.push(`--color-${role}: ${value};`);
+  }
+  return out;
+}
+
+function radiusDeclarations(overrides: Partial<Record<RadiusName, string>> | undefined): string[] {
+  if (overrides === undefined) return [];
+  const known = Object.keys(radiusTokens) as RadiusName[];
+  for (const name of Object.keys(overrides)) {
+    if (!(known as readonly string[]).includes(name)) {
+      throw unknownTokenError('radius', name, known, '_radius.scss');
+    }
+  }
+  const out: string[] = [];
+  for (const name of known) {
+    const value = overrides[name];
+    if (value === undefined) continue;
+    if (!LENGTH_PATTERN.test(value)) {
+      throw invalidBrandTokenError('radius', name, value, LENGTH_EXPECTED);
+    }
+    out.push(`--radius-${name}: ${value};`);
+  }
+  return out;
+}
+
+function fontDeclarations(overrides: Partial<Record<FontSlot, string>> | undefined): string[] {
+  if (overrides === undefined) return [];
+  for (const slot of Object.keys(overrides)) {
+    if (!(FONT_SLOTS as readonly string[]).includes(slot)) {
+      throw unknownTokenError('font', slot, FONT_SLOTS, '_typography.scss');
+    }
+  }
+  const out: string[] = [];
+  for (const slot of FONT_SLOTS) {
+    const value = overrides[slot];
+    if (value === undefined) continue;
+    if (!FONT_STACK_PATTERN.test(value)) {
+      throw invalidBrandTokenError('font', slot, value, STACK_EXPECTED);
+    }
+    out.push(`--font-${slot}: ${value};`);
+  }
+  return out;
+}
+
+function assertChannels(scope: string, role: string, value: string): void {
+  try {
+    parseChannels(value);
+  } catch {
+    throw invalidBrandTokenError(scope, role, value, CHANNELS_EXPECTED);
+  }
+}

package/src/tokens/_colors.scss

@@ -10,21 +10,21 @@ $light: (
   fg: 38 34 31,
   fg-strong: 17 15 13,
   fg-muted: 110 102 94,
-  line: 224 216 208,
+  line: 208 198 188,
   scrim: 17 15 13,
-  accent: 34 122 197,
+  accent: 31 110 178,
   accent-strong: 21 92 152,
   accent-fg: 255 255 255,
-  success: 22 128 84,
+  success: 21 123 80,
   success-soft: 222 244 232,
   success-fg: 255 255 255,
-  warning: 176 106 8,
+  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: 34 122 197,
+  info: 31 110 178,
   info-soft: 224 239 252,
   info-fg: 255 255 255,
 );
@@ -36,8 +36,8 @@ $dark: (
   surface-raised: 44 44 50,
   fg: 228 226 222,
   fg-strong: 248 247 245,
-  fg-muted: 150 146 140,
-  line: 54 54 60,
+  fg-muted: 155 151 145,
+  line: 72 72 80,
   scrim: 0 0 0,
   accent: 96 170 240,
   accent-strong: 130 190 248,
@@ -56,6 +56,10 @@ $dark: (
   info-fg: 12 20 30,
 );
 
+/// The tone vocabulary, in the order components expose it. Mirrors `TONES` in
+/// `components/variants.ts`; `variants.test.ts` fails if the two drift.
+$tones: (neutral, accent, success, warning, danger, info);
+
 /// Emit one theme's channels as custom properties.
 @mixin channels($map) {
   @each $role, $channels in $map {

package/src/tokens/_mixins.scss

@@ -151,6 +151,90 @@
   }
 }
 
+/// The inert state, spelled once. Both selectors, because a `<button disabled>` and a
+/// `[aria-disabled='true']` div are the same state to a reader and must look the same.
+@mixin disabled($opacity: 0.55) {
+  &:disabled,
+  &[aria-disabled='true'] {
+    opacity: $opacity;
+    cursor: not-allowed;
+  }
+}
+
+/// The `::backdrop` behind a `<dialog>`. Blur is opt-in — it costs a compositor layer.
+@mixin scrim-backdrop($alpha: 0.45, $blur: 0) {
+  &::backdrop {
+    background: colors.role('scrim', $alpha);
+
+    @if $blur != 0 {
+      backdrop-filter: blur($blur);
+    }
+  }
+}
+
+/// Inline run of items on one baseline — a toolbar, a header, an icon beside a label.
+@mixin row($gap: var(--space-3), $align: center, $justify: flex-start) {
+  display: flex;
+  flex-direction: row;
+  align-items: $align;
+  justify-content: $justify;
+  gap: $gap;
+}
+
+/// Vertical run. Paired with `row` so no component writes `flex-direction` by hand.
+@mixin column($gap: var(--space-3), $align: stretch) {
+  display: flex;
+  flex-direction: column;
+  align-items: $align;
+  gap: $gap;
+}
+
+// --- tones -------------------------------------------------------------------
+// One tone class set, generated. Button and IconButton each carried a hand-written copy of the
+// same six blocks; a seventh tone meant editing both, and they had already drifted.
+
+/// The four custom properties every toned component reads.
+@mixin tone-vars($base, $strong, $on, $soft) {
+  --tone: #{$base};
+  --tone-strong: #{$strong};
+  --tone-fg: #{$on};
+  --tone-soft: #{$soft};
+}
+
+/// Emits `.tone-<name>` for every rung of `colors.$tones`. Include once, at the top level of a
+/// component module, then read `var(--tone)` / `var(--tone-strong)` / `--tone-fg` / `--tone-soft`.
+@mixin tone-classes {
+  .tone-neutral {
+    @include tone-vars(
+      colors.role('fg-strong'),
+      colors.role('fg'),
+      colors.role('bg'),
+      colors.role('bg-soft')
+    );
+  }
+
+  .tone-accent {
+    // The one tone with no `-soft` token: accent tints composite off the same channels.
+    @include tone-vars(
+      colors.role('accent'),
+      colors.role('accent-strong'),
+      colors.role('accent-fg'),
+      colors.role('accent', 0.12)
+    );
+  }
+
+  @each $tone in (success, warning, danger, info) {
+    .tone-#{$tone} {
+      @include tone-vars(
+        colors.role($tone),
+        colors.role($tone),
+        colors.role('#{$tone}-fg'),
+        colors.role('#{$tone}-soft')
+      );
+    }
+  }
+}
+
 /// Shared shape for every text-ish form control so Input/Textarea/Select match.
 @mixin control {
   @include focus-ring;

package/src/tokens/contrast.ts

@@ -0,0 +1,63 @@
+// WCAG 2.2 relative luminance and contrast ratio over the canonical channel
+// tokens. Here rather than in a review checklist: a palette pairing that fails
+// AA is a failing test (`contrast.test.ts`), and a brand override is measured
+// with the same function before it ships.
+
+import { invalidValueError } from '../errors';
+import { type ColorRole, colorTokens, type Theme } from './tokens';
+
+/** Minimum ratio for body text — WCAG 2.2 AA, 1.4.3. */
+export const AA_TEXT = 4.5;
+
+/** Minimum ratio for large text and non-text UI — WCAG 2.2 AA, 1.4.3 / 1.4.11. */
+export const AA_LARGE = 3;
+
+/** `R G B`, each 0–255. The only channel spelling the token layer accepts. */
+export const CHANNELS_PATTERN = /^\d{1,3} \d{1,3} \d{1,3}$/;
+
+export type Channels = readonly [number, number, number];
+
+/** Parse `"31 110 178"`. Throws `X_UI_INVALID_VALUE` on anything else. */
+export function parseChannels(value: string): Channels {
+  if (!CHANNELS_PATTERN.test(value)) {
+    throw invalidValueError('colour channels', value, 'three space-separated 0–255 integers');
+  }
+  const parts = value.split(' ').map(Number);
+  const [r = 0, g = 0, b = 0] = parts;
+  if (r > 255 || g > 255 || b > 255) {
+    throw invalidValueError('colour channels', value, 'three space-separated 0–255 integers');
+  }
+  return [r, g, b];
+}
+
+// sRGB → linear, then the ITU-R BT.709 luma weights WCAG specifies.
+function linearize(channel: number): number {
+  const v = channel / 255;
+  return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+}
+
+export function relativeLuminance(channels: string): number {
+  const [r, g, b] = parseChannels(channels);
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+
+/** Symmetric — order of the two colours does not change the ratio. */
+export function contrastRatio(a: string, b: string): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/** The ratio between two semantic roles as resolved in one theme. */
+export function roleContrast(theme: Theme, fg: ColorRole, bg: ColorRole): number {
+  return contrastRatio(colorTokens[theme][fg], colorTokens[theme][bg]);
+}
+
+export function meetsContrast(
+  theme: Theme,
+  fg: ColorRole,
+  bg: ColorRole,
+  minimum: number = AA_TEXT,
+): boolean {
+  return roleContrast(theme, fg, bg) >= minimum;
+}

package/src/tokens/tokens.ts

@@ -47,21 +47,21 @@ export const colorTokens: Readonly<Record<Theme, Readonly<Record<ColorRole, stri
     fg: '38 34 31',
     'fg-strong': '17 15 13',
     'fg-muted': '110 102 94',
-    line: '224 216 208',
+    line: '208 198 188',
     scrim: '17 15 13',
-    accent: '34 122 197',
+    accent: '31 110 178',
     'accent-strong': '21 92 152',
     'accent-fg': '255 255 255',
-    success: '22 128 84',
+    success: '21 123 80',
     'success-soft': '222 244 232',
     'success-fg': '255 255 255',
-    warning: '176 106 8',
+    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: '34 122 197',
+    info: '31 110 178',
     'info-soft': '224 239 252',
     'info-fg': '255 255 255',
   },
@@ -72,8 +72,8 @@ export const colorTokens: Readonly<Record<Theme, Readonly<Record<ColorRole, stri
     'surface-raised': '44 44 50',
     fg: '228 226 222',
     'fg-strong': '248 247 245',
-    'fg-muted': '150 146 140',
-    line: '54 54 60',
+    'fg-muted': '155 151 145',
+    line: '72 72 80',
     scrim: '0 0 0',
     accent: '96 170 240',
     'accent-strong': '130 190 248',
@@ -117,6 +117,8 @@ export const radiusTokens = {
   full: '50%',
 } as const;
 
+export type RadiusName = keyof typeof radiusTokens;
+
 export const zTokens = {
   base: '0',
   raised: '10',