@alacris/ui 0.0.0 → 0.1.0

package/src/tokens/color.js

@@ -0,0 +1,237 @@
+// Color engine — dependency-free tonal palettes in OKLCH.
+//
+// Material's color system is built on tonal palettes: thirteen-plus tones of a
+// single hue/chroma, indexed by perceptual lightness 0–100, with semantic roles
+// (primary, on-primary, surface-container, …) mapped onto specific tones per
+// scheme. Google derives palettes in HCT; we get an equivalent result with
+// OKLab/OKLCH: hold hue and chroma from the seed, target each tone's CIE
+// luminance, and gamut-map by walking chroma down until the color fits sRGB.
+//
+// Everything here is pure math on hex strings — no DOM, usable in a worker or
+// at build time to pregenerate a static theme.
+
+// ---------------------------------------------------------------- sRGB <-> hex
+
+const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+
+export function hexToRgb(hex) {
+  let h = hex.replace('#', '').trim();
+  if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+  const n = parseInt(h, 16);
+  if (h.length !== 6 || Number.isNaN(n)) throw new Error(`invalid hex color: ${hex}`);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+export function rgbToHex([r, g, b]) {
+  const to = (v) => Math.round(clamp01(v / 255) * 255).toString(16).padStart(2, '0');
+  return '#' + to(r) + to(g) + to(b);
+}
+
+const srgbToLinear = (c) => {
+  const v = c / 255;
+  return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+};
+
+const linearToSrgb = (v) => {
+  const c = v <= 0.0031308 ? v * 12.92 : 1.055 * Math.pow(v, 1 / 2.4) - 0.055;
+  return clamp01(c) * 255;
+};
+
+// ---------------------------------------------------------------- OKLab/OKLCH
+
+function linearToOklab(r, g, b) {
+  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,
+  ];
+}
+
+function oklabToLinear(L, a, b) {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
+  ];
+}
+
+/** hex → { l, c, h } (OKLCH; h in degrees, 0 for achromatic). */
+export function oklchFromHex(hex) {
+  const [r, g, b] = hexToRgb(hex);
+  const [L, a, bb] = linearToOklab(srgbToLinear(r), srgbToLinear(g), srgbToLinear(b));
+  const c = Math.hypot(a, bb);
+  const h = c < 1e-6 ? 0 : ((Math.atan2(bb, a) * 180) / Math.PI + 360) % 360;
+  return { l: L, c, h };
+}
+
+const inGamut = ([r, g, b]) =>
+  r >= -1e-4 && r <= 1 + 1e-4 && g >= -1e-4 && g <= 1 + 1e-4 && b >= -1e-4 && b <= 1 + 1e-4;
+
+/**
+ * { l, c, h } → hex. If the color is outside sRGB, chroma is reduced (binary
+ * search) until it fits — hue and lightness are preserved, which is what keeps
+ * a tonal ramp looking like one hue.
+ */
+export function hexFromOklch({ l, c, h }) {
+  const rad = (h * Math.PI) / 180;
+  const attempt = (cc) => oklabToLinear(l, cc * Math.cos(rad), cc * Math.sin(rad));
+  let rgb = attempt(c);
+  if (!inGamut(rgb)) {
+    let lo = 0, hi = c;
+    for (let i = 0; i < 20; i++) {
+      const mid = (lo + hi) / 2;
+      if (inGamut(attempt(mid))) lo = mid;
+      else hi = mid;
+    }
+    rgb = attempt(lo);
+  }
+  return rgbToHex(rgb.map(linearToSrgb));
+}
+
+// ------------------------------------------------------------------- tones
+
+// Material tone T is CIE L* — convert to luminance Y, and for near-neutral
+// colors OKLab lightness is exactly cbrt(Y), which anchors the ramp so that
+// tone 100 is white, tone 0 is black, and tone 50 is mid-gray to the eye.
+const toneToOklabL = (tone) => {
+  const L = tone;
+  const Y = L > 8 ? Math.pow((L + 16) / 116, 3) : L / 903.2962962;
+  return Math.cbrt(Y);
+};
+
+/** The tone steps Material's schemes draw from. */
+export const TONES = [0, 4, 6, 10, 12, 17, 20, 22, 24, 30, 40, 50, 60, 70, 80, 87, 90, 92, 94, 95, 96, 98, 99, 100];
+
+/**
+ * A full tonal palette from one hue/chroma.
+ * Returns { 0: '#000000', …, 100: '#ffffff' } over TONES.
+ */
+export function tonalPalette(hue, chroma) {
+  const out = {};
+  for (const tone of TONES) {
+    out[tone] =
+      tone === 0 ? '#000000'
+      : tone === 100 ? '#ffffff'
+      : hexFromOklch({ l: toneToOklabL(tone), c: chroma, h: hue });
+  }
+  return out;
+}
+
+// -------------------------------------------------------------- key palettes
+
+// Fixed seeds for the status hues (Material error, plus the MUI-style
+// success/warning/info set). Each can be overridden via createTheme colors.
+export const DEFAULT_SEED = '#e8ad18';
+const STATUS_SEEDS = { error: '#b3261e', success: '#1e8e3e', warning: '#e37400', info: '#0b57d0' };
+
+// Chroma floors/targets in OKLCH units (roughly HCT chroma / 350).
+const MIN_VIVID = 0.09;
+
+/**
+ * Build the key tonal palettes from a seed (or explicit per-palette seeds).
+ *
+ *   makePalettes({ seed: '#e8ad18' })
+ *   makePalettes({ colors: { primary: '#0b57d0', tertiary: '#00695c' } })
+ *
+ * Returns { primary, secondary, tertiary, neutral, neutralVariant,
+ *           error, success, warning, info } — each a tonal palette.
+ */
+export function makePalettes({ seed = DEFAULT_SEED, colors = {} } = {}) {
+  const base = oklchFromHex(colors.primary || seed);
+  const c = Math.max(base.c, MIN_VIVID);
+  const from = (name, fallbackHue, fallbackChroma) => {
+    if (colors[name]) {
+      const k = oklchFromHex(colors[name]);
+      return tonalPalette(k.h, Math.max(k.c, name.startsWith('neutral') ? k.c : MIN_VIVID * 0.6));
+    }
+    return tonalPalette(fallbackHue, fallbackChroma);
+  };
+  return {
+    primary: from('primary', base.h, c),
+    secondary: from('secondary', base.h, c / 3),
+    tertiary: from('tertiary', (base.h + 60) % 360, c / 2),
+    neutral: from('neutral', base.h, 0.012),
+    neutralVariant: from('neutralVariant', base.h, 0.024),
+    error: from('error', ...seedHC(colors.error || STATUS_SEEDS.error)),
+    success: from('success', ...seedHC(colors.success || STATUS_SEEDS.success)),
+    warning: from('warning', ...seedHC(colors.warning || STATUS_SEEDS.warning)),
+    info: from('info', ...seedHC(colors.info || STATUS_SEEDS.info)),
+  };
+}
+
+const seedHC = (hex) => {
+  const k = oklchFromHex(hex);
+  return [k.h, Math.max(k.c, MIN_VIVID)];
+};
+
+// ------------------------------------------------------------------ schemes
+
+// Role → [palette, lightTone, darkTone]. This is the Material scheme mapping,
+// extended with success/warning/info role sets.
+const ROLES = {
+  primary: ['primary', 40, 80],
+  onPrimary: ['primary', 100, 20],
+  primaryContainer: ['primary', 90, 30],
+  onPrimaryContainer: ['primary', 10, 90],
+  secondary: ['secondary', 40, 80],
+  onSecondary: ['secondary', 100, 20],
+  secondaryContainer: ['secondary', 90, 30],
+  onSecondaryContainer: ['secondary', 10, 90],
+  tertiary: ['tertiary', 40, 80],
+  onTertiary: ['tertiary', 100, 20],
+  tertiaryContainer: ['tertiary', 90, 30],
+  onTertiaryContainer: ['tertiary', 10, 90],
+  error: ['error', 40, 80],
+  onError: ['error', 100, 20],
+  errorContainer: ['error', 90, 30],
+  onErrorContainer: ['error', 10, 90],
+  success: ['success', 40, 80],
+  onSuccess: ['success', 100, 20],
+  successContainer: ['success', 90, 30],
+  onSuccessContainer: ['success', 10, 90],
+  warning: ['warning', 40, 80],
+  onWarning: ['warning', 100, 20],
+  warningContainer: ['warning', 90, 30],
+  onWarningContainer: ['warning', 10, 90],
+  info: ['info', 40, 80],
+  onInfo: ['info', 100, 20],
+  infoContainer: ['info', 90, 30],
+  onInfoContainer: ['info', 10, 90],
+  surface: ['neutral', 98, 6],
+  surfaceDim: ['neutral', 87, 6],
+  surfaceBright: ['neutral', 98, 24],
+  surfaceContainerLowest: ['neutral', 100, 4],
+  surfaceContainerLow: ['neutral', 96, 10],
+  surfaceContainer: ['neutral', 94, 12],
+  surfaceContainerHigh: ['neutral', 92, 17],
+  surfaceContainerHighest: ['neutral', 90, 22],
+  onSurface: ['neutral', 10, 90],
+  surfaceVariant: ['neutralVariant', 90, 30],
+  onSurfaceVariant: ['neutralVariant', 30, 80],
+  outline: ['neutralVariant', 50, 60],
+  outlineVariant: ['neutralVariant', 80, 30],
+  inverseSurface: ['neutral', 20, 90],
+  inverseOnSurface: ['neutral', 95, 20],
+  inversePrimary: ['primary', 80, 40],
+  scrim: ['neutral', 0, 0],
+  shadow: ['neutral', 0, 0],
+};
+
+export const COLOR_ROLES = Object.keys(ROLES);
+
+/** Map palettes to the semantic color roles for one scheme. */
+export function makeScheme(palettes, scheme /* 'light' | 'dark' */) {
+  const dark = scheme === 'dark';
+  const out = {};
+  for (const role of COLOR_ROLES) {
+    const [palette, light, darkTone] = ROLES[role];
+    out[role] = palettes[palette][dark ? darkTone : light];
+  }
+  return out;
+}

package/src/tokens/index.js

@@ -0,0 +1,14 @@
+export { sys, typeRule } from './sys.js';
+export {
+  makePalettes, makeScheme, tonalPalette, oklchFromHex, hexFromOklch,
+  COLOR_ROLES, TONES, DEFAULT_SEED,
+} from './color.js';
+export {
+  typographyTokens, resolveTypography, googleFontsHref, firstFamily,
+  TYPE_ROLES, FONT_STACKS, FONT_PRESETS, DEFAULT_FONT_PRESET,
+} from './typography.js';
+export {
+  shapeTokens, elevationTokens, motionTokens, spacingTokens, stateTokens,
+  focusTokens, zTokens, densityTokens, RADIUS_KEYS, ELEVATION_LEVELS,
+  DURATIONS, EASINGS, SPACE_STEPS,
+} from './system.js';

package/src/tokens/sys.js

@@ -0,0 +1,76 @@
+// `sys` — how components reference system tokens.
+//
+// Every value is a `var(--ui-…)` string for interpolation into `css`
+// templates. Components never write raw `var(--ui-…)` literals; going through
+// `sys` keeps the token names in one place and makes a typo a visible
+// `undefined` in the stylesheet instead of a silently-inert custom property.
+//
+//   css`:host { color: ${sys.color.onSurface}; font: ${sys.type.bodyMd}; }`
+
+import { COLOR_ROLES } from './color.js';
+import { TYPE_ROLES } from './typography.js';
+import { RADIUS_KEYS, ELEVATION_LEVELS, DURATIONS, EASINGS } from './system.js';
+
+const kebab = (s) => s.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+const camel = (s) => s.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+const v = (name) => `var(--ui-${name})`;
+
+const color = {};
+for (const role of COLOR_ROLES) color[role] = v(`color-${kebab(role)}`);
+
+const radius = {};
+for (const k of RADIUS_KEYS) radius[k] = v(`radius-${k}`);
+
+const elevation = {};
+for (const lvl of ELEVATION_LEVELS) elevation[lvl] = v(`elevation-${lvl}`);
+
+const duration = {};
+for (const k in DURATIONS) duration[camel(k)] = v(`duration-${k}`);
+
+const easing = {};
+for (const k in EASINGS) easing[camel(k)] = v(`easing-${k}`);
+
+const type = {};
+const tracking = {};
+for (const role of TYPE_ROLES) {
+  type[camel(role)] = v(`type-${role}`);
+  tracking[camel(role)] = v(`type-${role}-tracking`);
+}
+
+export const sys = {
+  color,
+  radius,
+  elevation,
+  duration,
+  easing,
+  type,
+  tracking,
+  font: { brand: v('font-brand'), plain: v('font-plain'), code: v('font-code') },
+  space: (n) => v(`space-${n}`),
+  state: {
+    hover: v('state-hover'),
+    focus: v('state-focus'),
+    pressed: v('state-pressed'),
+    dragged: v('state-dragged'),
+    disabledContent: v('state-disabled-content'),
+    disabledContainer: v('state-disabled-container'),
+  },
+  focus: {
+    ring: v('focus-ring'),
+    ringWidth: v('focus-ring-width'),
+    ringOffset: v('focus-ring-offset'),
+    ringColor: v('focus-ring-color'),
+  },
+  z: {
+    appBar: v('z-app-bar'),
+    drawer: v('z-drawer'),
+    modal: v('z-modal'),
+    snackbar: v('z-snackbar'),
+    tooltip: v('z-tooltip'),
+  },
+  density: 'var(--ui-density, 0)',
+};
+
+/** `font` + `letter-spacing` for a type role, ready to drop into a rule. */
+export const typeRule = (role) =>
+  `font: ${type[camel(role)] || type[role]}; letter-spacing: ${tracking[camel(role)] || tracking[role]};`;

package/src/tokens/system.js

@@ -0,0 +1,114 @@
+// Non-color, non-type system tokens: shape, elevation, motion, spacing,
+// state layers, focus ring, z-index. Each builder returns a flat map of
+// token name (without the leading `--ui-`) → value.
+
+// ------------------------------------------------------------------- shape
+
+const RADII = { none: '0', xs: 4, sm: 8, md: 12, lg: 16, xl: 28, full: 9999 };
+export const RADIUS_KEYS = Object.keys(RADII);
+
+/** config: { radius: multiplier } — `radius: 0` squares every corner. */
+export function shapeTokens({ radius = 1 } = {}) {
+  const out = {};
+  for (const k of RADIUS_KEYS) {
+    const v = RADII[k];
+    out[`radius-${k}`] = v === '0' ? '0' : k === 'full' ? '9999px' : `${Math.round(v * radius)}px`;
+  }
+  return out;
+}
+
+// --------------------------------------------------------------- elevation
+
+// Material's five elevation levels as key+ambient shadow pairs, built on a
+// themable shadow color channel so dark schemes can deepen them.
+export const ELEVATION_LEVELS = [0, 1, 2, 3, 4, 5];
+
+export function elevationTokens() {
+  const c1 = 'rgb(var(--ui-shadow-rgb) / 0.3)';
+  const c2 = 'rgb(var(--ui-shadow-rgb) / 0.15)';
+  return {
+    'shadow-rgb': '0 0 0',
+    'elevation-0': 'none',
+    'elevation-1': `0 1px 2px ${c1}, 0 1px 3px 1px ${c2}`,
+    'elevation-2': `0 1px 2px ${c1}, 0 2px 6px 2px ${c2}`,
+    'elevation-3': `0 1px 3px ${c1}, 0 4px 8px 3px ${c2}`,
+    'elevation-4': `0 2px 3px ${c1}, 0 6px 10px 4px ${c2}`,
+    'elevation-5': `0 4px 4px ${c1}, 0 8px 12px 6px ${c2}`,
+  };
+}
+
+// ------------------------------------------------------------------ motion
+
+export const DURATIONS = {
+  'short-1': 50, 'short-2': 100, 'short-3': 150, 'short-4': 200,
+  'medium-1': 250, 'medium-2': 300, 'medium-3': 350, 'medium-4': 400,
+  'long-1': 450, 'long-2': 500, 'long-3': 550, 'long-4': 600,
+  'extra-long-1': 700, 'extra-long-2': 800, 'extra-long-3': 900, 'extra-long-4': 1000,
+};
+
+export const EASINGS = {
+  standard: 'cubic-bezier(0.2, 0, 0, 1)',
+  'standard-accelerate': 'cubic-bezier(0.3, 0, 1, 1)',
+  'standard-decelerate': 'cubic-bezier(0, 0, 0, 1)',
+  emphasized: 'cubic-bezier(0.2, 0, 0, 1)',
+  'emphasized-accelerate': 'cubic-bezier(0.3, 0, 0.8, 0.15)',
+  'emphasized-decelerate': 'cubic-bezier(0.05, 0.7, 0.1, 1)',
+  // Switch-handle overshoot — the MD3 track/handle settle (not a generic curve).
+  'emphasized-overshoot': 'cubic-bezier(0.175, 0.885, 0.32, 1.275)',
+  linear: 'linear',
+};
+
+/** config: { scale } — 0 disables durations, 2 doubles them. */
+export function motionTokens({ scale = 1 } = {}) {
+  const out = {};
+  for (const k in DURATIONS) out[`duration-${k}`] = `${Math.round(DURATIONS[k] * scale)}ms`;
+  for (const k in EASINGS) out[`easing-${k}`] = EASINGS[k];
+  return out;
+}
+
+// ----------------------------------------------------------------- spacing
+
+export const SPACE_STEPS = [1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 16, 18, 20, 24];
+
+export function spacingTokens() {
+  const out = {};
+  for (const s of SPACE_STEPS) out[`space-${s}`] = `${s * 4}px`;
+  return out;
+}
+
+// ---------------------------------------------------- state / focus / z
+
+export function stateTokens() {
+  return {
+    'state-hover': '0.08',
+    'state-focus': '0.1',
+    'state-pressed': '0.1',
+    'state-dragged': '0.16',
+    'state-disabled-content': '0.38',
+    'state-disabled-container': '0.12',
+  };
+}
+
+export function focusTokens() {
+  return {
+    'focus-ring-width': '2px',
+    'focus-ring-offset': '2px',
+    'focus-ring-color': 'var(--ui-color-primary)',
+    'focus-ring': 'var(--ui-focus-ring-width) solid var(--ui-focus-ring-color)',
+  };
+}
+
+export function zTokens() {
+  return {
+    'z-app-bar': '1100',
+    'z-drawer': '1200',
+    'z-modal': '1300',
+    'z-snackbar': '1400',
+    'z-tooltip': '1500',
+  };
+}
+
+/** config: { density } — 0 (default) … -2; each step removes 4px of control height. */
+export function densityTokens({ density = 0 } = {}) {
+  return { density: String(Math.max(-2, Math.min(0, density))) };
+}

package/src/tokens/typography.js

@@ -0,0 +1,189 @@
+// Typography tokens — the Material type scale.
+//
+// Fifteen roles (display/headline/title/body/label × lg/md/sm), each emitted
+// as granular tokens plus a `font` shorthand so a component can write
+// `font: var(--ui-type-body-md)` and get weight, size, line-height and family
+// in one declaration. Letter-spacing cannot ride the shorthand, so tracking is
+// its own token.
+//
+// Faces are system tokens (`--ui-font-brand/plain/code`). The default is
+// Google Sans Flex — the typeface Google's own Material 3 surfaces use —
+// with Google Sans as the installed-on-device fallback. Swap the whole
+// product with a preset name, a single `family`, or explicit stacks; every
+// component follows because they consume `sys.type.*` / `sys.font.*` only.
+
+const SYSTEM_SANS = "system-ui, -apple-system, 'Segoe UI', sans-serif";
+const SYSTEM_MONO = "ui-monospace, 'SF Mono', Menlo, Consolas, monospace";
+const GF = 'https://fonts.googleapis.com/css2?';
+
+const sansStack = (...names) =>
+  names.map((n) => `'${n}'`).join(', ') + ', ' + SYSTEM_SANS;
+
+/** Google Fonts CSS2 queries keyed by the CSS family name they load. */
+const GF_QUERY = {
+  'Google Sans Flex': 'Google+Sans+Flex:opsz,wght@6..144,400..700',
+  'Google Sans': 'Google+Sans:wght@400;500;700',
+  Roboto: 'Roboto:wght@400;500;700',
+  'Roboto Flex': 'Roboto+Flex:opsz,wght@8..144,400..700',
+};
+
+/**
+ * Named typeface packages. A preset is the one-liner for `createTheme`:
+ * `typography: 'google-sans'` (or `{ preset: 'google-sans' }`).
+ */
+export const FONT_PRESETS = {
+  'google-sans-flex': {
+    brand: sansStack('Google Sans Flex', 'Google Sans'),
+    plain: sansStack('Google Sans Flex', 'Google Sans'),
+    href: GF + 'family=Google+Sans+Flex:opsz,wght@6..144,400..700&display=swap',
+  },
+  'google-sans': {
+    brand: sansStack('Google Sans', 'Google Sans Flex'),
+    plain: sansStack('Google Sans', 'Google Sans Flex'),
+    href: GF + 'family=Google+Sans:wght@400;500;700&display=swap',
+  },
+  roboto: {
+    brand: sansStack('Roboto'),
+    plain: sansStack('Roboto'),
+    href: GF + 'family=Roboto:wght@400;500;700&display=swap',
+  },
+  system: {
+    brand: SYSTEM_SANS,
+    plain: SYSTEM_SANS,
+    href: null,
+  },
+};
+
+export const DEFAULT_FONT_PRESET = 'google-sans-flex';
+
+/** Default stacks — what `typographyTokens()` emits with no config. */
+export const FONT_STACKS = {
+  brand: FONT_PRESETS[DEFAULT_FONT_PRESET].brand,
+  plain: FONT_PRESETS[DEFAULT_FONT_PRESET].plain,
+  code: SYSTEM_MONO,
+};
+
+// role: [sizePx, lineHeightPx, weight, trackingPx, family]
+const SCALE = {
+  'display-lg': [57, 64, 400, -0.25, 'brand'],
+  'display-md': [45, 52, 400, 0, 'brand'],
+  'display-sm': [36, 44, 400, 0, 'brand'],
+  'headline-lg': [32, 40, 400, 0, 'brand'],
+  'headline-md': [28, 36, 400, 0, 'brand'],
+  'headline-sm': [24, 32, 400, 0, 'brand'],
+  'title-lg': [22, 28, 400, 0, 'brand'],
+  'title-md': [16, 24, 500, 0.15, 'plain'],
+  'title-sm': [14, 20, 500, 0.1, 'plain'],
+  'body-lg': [16, 24, 400, 0.5, 'plain'],
+  'body-md': [14, 20, 400, 0.25, 'plain'],
+  'body-sm': [12, 16, 400, 0.4, 'plain'],
+  'label-lg': [14, 20, 500, 0.1, 'plain'],
+  'label-md': [12, 16, 500, 0.5, 'plain'],
+  'label-sm': [11, 16, 500, 0.5, 'plain'],
+};
+
+export const TYPE_ROLES = Object.keys(SCALE);
+
+const rem = (px) => `${+(px / 16).toFixed(4)}rem`;
+
+const GENERIC = new Set([
+  'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy', 'system-ui',
+  'ui-sans-serif', 'ui-serif', 'ui-monospace', 'ui-rounded', 'emoji', 'math',
+  'fangsong', '-apple-system', 'blinkmacsystemfont', 'segoe ui', 'arial',
+  'helvetica neue', 'helvetica',
+]);
+
+const stripQuote = (s) => s.replace(/^['"]|['"]$/g, '');
+
+/** First family name in a CSS font-family stack. */
+export function firstFamily(stack) {
+  return stripQuote((stack || '').split(',')[0].trim());
+}
+
+/**
+ * A CSS stack from either a family name (`'Inter'`) or an already-complete
+ * stack (`Inter, system-ui, sans-serif`). Names are quoted; stacks pass through.
+ */
+function asStack(value, fallback) {
+  if (!value) return null;
+  const v = String(value).trim();
+  if (v.includes(',')) return v;
+  return `'${stripQuote(v)}', ${fallback}`;
+}
+
+/** Google Fonts stylesheet URL for the given CSS family names / stacks. */
+export function googleFontsHref(names) {
+  const families = [];
+  const seen = new Set();
+  for (const n of names) {
+    const fam = firstFamily(n);
+    if (!fam || GENERIC.has(fam.toLowerCase()) || seen.has(fam)) continue;
+    seen.add(fam);
+    families.push(fam);
+  }
+  if (!families.length) return null;
+  const params = families.map((fam) => 'family=' + (GF_QUERY[fam] || `${fam.replace(/ /g, '+')}:wght@400;500;700`));
+  return GF + params.join('&') + '&display=swap';
+}
+
+/**
+ * Normalize `createTheme({ typography })` into stacks + a stylesheet href.
+ *
+ * Accepts:
+ *   'google-sans-flex' | 'google-sans' | 'roboto' | 'system'
+ *   { preset, family, brand, plain, code, scale, load }
+ *
+ * `family` sets brand and plain together. `load` is a Google Fonts (or any)
+ * stylesheet URL, `true` (default — derive from the faces), or `false`
+ * (tokens only; you host the files).
+ */
+export function resolveTypography(config = {}) {
+  if (typeof config === 'string') config = { preset: config };
+
+  const presetName = config.preset
+    || (config.family || config.brand || config.plain ? null : DEFAULT_FONT_PRESET);
+  if (presetName && !FONT_PRESETS[presetName]) {
+    throw new Error(
+      `Unknown font preset "${presetName}". Use one of: ${Object.keys(FONT_PRESETS).join(', ')}`);
+  }
+  const preset = presetName ? FONT_PRESETS[presetName] : null;
+  const familyStack = asStack(config.family, SYSTEM_SANS);
+
+  const brand = asStack(config.brand, SYSTEM_SANS) || familyStack || preset?.brand || FONT_STACKS.brand;
+  const plain = asStack(config.plain, SYSTEM_SANS) || familyStack || preset?.plain || FONT_STACKS.plain;
+  const code = asStack(config.code, SYSTEM_MONO) || FONT_STACKS.code;
+  const scale = config.scale ?? 1;
+
+  let href = null;
+  if (config.load === false) href = null;
+  else if (typeof config.load === 'string') href = config.load;
+  else href = preset?.href ?? googleFontsHref([brand, plain]);
+
+  return { brand, plain, code, scale, href, preset: presetName };
+}
+
+/**
+ * Build the typography token map.
+ *
+ * config: a preset name, or { preset, family, brand, plain, code, scale, load }
+ */
+export function typographyTokens(config = {}) {
+  const { brand, plain, code, scale } = resolveTypography(config);
+  const out = {
+    'font-brand': brand,
+    'font-plain': plain,
+    'font-code': code,
+  };
+  for (const role of TYPE_ROLES) {
+    const [size, line, weight, tracking, family] = SCALE[role];
+    const fam = `var(--ui-font-${family})`;
+    out[`type-${role}-size`] = rem(size * scale);
+    out[`type-${role}-line`] = rem(line * scale);
+    out[`type-${role}-weight`] = String(weight);
+    out[`type-${role}-tracking`] = tracking ? `${tracking * scale}px` : '0';
+    out[`type-${role}-font`] = fam;
+    out[`type-${role}`] =
+      `var(--ui-type-${role}-weight) var(--ui-type-${role}-size) / var(--ui-type-${role}-line) var(--ui-type-${role}-font)`;
+  }
+  return out;
+}