@3xhaust/oh-my-design 0.16.1

package/core/ir/dom.ts

@@ -0,0 +1,352 @@
+import type { RawIr } from '../types.ts';
+
+/**
+ * Runs inside the page. Stringified and injected, so it must stay self-contained:
+ * no imports, no closure over module scope, and nothing that survives type stripping
+ * as a runtime construct.
+ */
+export function extractInPage(maxNodes: number, selector?: string | null): RawIr {
+  const toHex = (css: string): string | null => {
+    const m = /^rgba?\(([^)]+)\)$/.exec(css);
+    if (!m || !m[1]) return null;
+    const parts = m[1].split(',').map((v) => parseFloat(v));
+    const [r, g, b, a] = parts as [number, number, number, number?];
+    if (a === 0) return null;
+    const h = (n: number): string => Math.round(n).toString(16).padStart(2, '0');
+    return `#${h(r)}${h(g)}${h(b)}`.toUpperCase();
+  };
+
+  // A design token is a CSS custom property on :root. Inverting value -> name is what
+  // lets us tell `background: var(--surface)` apart from a hand-typed #FEFEFE.
+  const tokenByValue: Record<string, string> = {};
+  const rootStyle = getComputedStyle(document.documentElement);
+  for (const prop of Array.from(rootStyle)) {
+    if (!prop.startsWith('--')) continue;
+    const raw = rootStyle.getPropertyValue(prop).trim();
+    const value = raw.startsWith('rgb') ? toHex(raw) : raw.toUpperCase();
+    if (value && !(value in tokenByValue)) tokenByValue[prop.slice(2)] = value;
+  }
+  const nameOf = (value: string): string | null =>
+    Object.keys(tokenByValue).find((k) => tokenByValue[k] === value) ?? null;
+
+  // A browser's default button padding is 1px 6px. Reporting that as an off-grid defect
+  // is noise: nobody wrote it. Only properties the author actually declared count as
+  // design decisions.
+  const authorRules: CSSStyleRule[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRule[];
+    try {
+      rules = Array.from(sheet.cssRules);
+    } catch {
+      continue;
+    }
+    for (const rule of rules) {
+      const styleRule = rule as CSSStyleRule;
+      if (styleRule.selectorText && styleRule.style) authorRules.push(styleRule);
+    }
+  }
+  const authoredProps = (el: Element): Set<string> => {
+    const props = new Set<string>();
+    for (const rule of authorRules) {
+      let matches = false;
+      try {
+        matches = el.matches(rule.selectorText);
+      } catch {
+        matches = false;
+      }
+      if (matches) for (const p of Array.from(rule.style)) props.add(p);
+    }
+    for (const p of Array.from((el as HTMLElement).style)) props.add(p);
+    return props;
+  };
+  const declares = (props: Set<string>, prefix: string): boolean =>
+    Array.from(props).some((p) => p.startsWith(prefix));
+
+  const INTERACTIVE = new Set(['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY']);
+  const isInteractive = (el: Element): boolean =>
+    INTERACTIVE.has(el.tagName) || el.getAttribute('role') === 'button' || el.hasAttribute('onclick');
+
+  // NATIVELY_FOCUSABLE: elements whose default tabIndex is 0 (in tab order by spec).
+  // <a> without href is NOT focusable by default; <a href="..."> is. We check tabIndex
+  // directly rather than duplicating the browser's focusability rules.
+  const NATIVELY_FOCUSABLE = new Set(['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY', 'DETAILS']);
+
+  /**
+   * Returns the focusable state for an element:
+   *   true  — in the tab order (tabIndex >= 0, either natively or via tabindex attr)
+   *   false — interactive but explicitly removed with tabindex="-1"
+   *   null  — static element, no focusability data to record
+   *
+   * Cannot capture: dynamic tabindex mutations via JS, focus() calls, or CSS :focus-visible
+   * ring visibility (that is measured by the interaction probe in core/render/).
+   */
+  const focusableState = (el: Element): boolean | null => {
+    const htmlEl = el as HTMLElement;
+    const tabIdx = htmlEl.tabIndex;
+    if (tabIdx >= 0) return true;
+    // tabIndex < 0 — only flag as false when the element is otherwise interactive,
+    // so we don't record false on every non-interactive div that has no tabindex.
+    if (isInteractive(el) || NATIVELY_FOCUSABLE.has(el.tagName)) return false;
+    return null;
+  };
+
+  const hasOwnText = (el: Element): boolean =>
+    Array.from(el.childNodes).some((n) => n.nodeType === 3 && (n.textContent ?? '').trim().length > 0);
+
+  // Own text only — a container's descendants speak for themselves as their own nodes.
+  const ownText = (el: Element): string | undefined => {
+    const joined = Array.from(el.childNodes)
+      .filter((n) => n.nodeType === 3)
+      .map((n) => n.textContent ?? '')
+      .join(' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+    return joined ? joined.slice(0, 200) : undefined;
+  };
+
+  const HEADING_RE = /^H([1-6])$/;
+  const headingOf = (el: Element): number | undefined => {
+    const m = HEADING_RE.exec(el.tagName);
+    return m && m[1] ? Number(m[1]) : undefined;
+  };
+
+  const px = (v: string): number => Math.round(parseFloat(v) || 0);
+
+  const pathOf = (el: Element): string => {
+    const parts: string[] = [];
+    for (let n: Element | null = el; n && n !== document.documentElement; n = n.parentElement) {
+      const cls = n.classList[0] ? `.${n.classList[0]}` : '';
+      parts.unshift(`${n.tagName.toLowerCase()}${cls}`);
+    }
+    return parts.join('/');
+  };
+
+  const nodes: RawIr['nodes'] = [];
+  const walk = (el: Element, parentId: string | null): void => {
+    if (nodes.length >= maxNodes) return;
+    const rect = el.getBoundingClientRect();
+    const cs = getComputedStyle(el);
+    if (rect.width === 0 || rect.height === 0 || cs.display === 'none' || cs.visibility === 'hidden') return;
+
+    const id = `n${nodes.length}`;
+    const bg = toHex(cs.backgroundColor);
+    const radius = px(cs.borderTopLeftRadius);
+    const isText = hasOwnText(el);
+    const authored = authoredProps(el);
+
+    const node: RawIr['nodes'][number] = {
+      id,
+      name: el.tagName.toLowerCase() + (el.classList[0] ? `.${el.classList[0]}` : ''),
+      type: isText ? 'TEXT' : 'FRAME',
+      path: pathOf(el),
+      parent: parentId,
+      box: { x: Math.round(rect.x), y: Math.round(rect.y), w: Math.round(rect.width), h: Math.round(rect.height) },
+      children: [],
+    };
+
+    if (bg) node.fill = { value: bg, token: nameOf(bg), authored: declares(authored, 'background') };
+    if (isText) {
+      const color = toHex(cs.color);
+      if (color) node.color = color;
+    }
+    if (radius > 0) node.radius = { value: radius, token: nameOf(String(radius)) };
+    if (isInteractive(el)) node.interactive = true;
+    if (cs.display === 'inline') node.inline = true;
+
+    // Focusability — tab-order membership, one DOM read per node.
+    const fs = focusableState(el);
+    if (fs !== null) node.focusable = fs;
+
+    // Explicit ARIA role attribute. Only the declared attribute value — implicit roles
+    // derived from tag semantics (e.g. <input> → role='textbox') are NOT captured here.
+    const explicitRole = el.getAttribute('role');
+    if (explicitRole) node.role = explicitRole;
+
+    // aria-invalid: present and not "false" → field is in an error state per ARIA spec.
+    const ariaInvalid = el.getAttribute('aria-invalid');
+    if (ariaInvalid && ariaInvalid !== 'false') node.ariaInvalid = true;
+
+    if (isText) {
+      const family = cs.fontFamily.split(',')[0]?.trim().replace(/^["']|["']$/g, '').toLowerCase();
+      if (family) node.fontFamily = family;
+      node.fontSize = px(cs.fontSize);
+      node.fontWeight = Number(cs.fontWeight) || 0;
+      const fontSize = parseFloat(cs.fontSize) || 0;
+      if (cs.lineHeight === 'normal') {
+        node.lineHeight = 1.2;
+      } else {
+        const lh = parseFloat(cs.lineHeight);
+        node.lineHeight = fontSize > 0 && !Number.isNaN(lh) ? Math.round((lh / fontSize) * 100) / 100 : 1.2;
+      }
+      // word-break is well-supported; always capture on text nodes.
+      if (cs.wordBreak) node.wordBreak = cs.wordBreak;
+      // text-wrap (CSS text-wrap shorthand) landed in Chrome 114 / Firefox 121.
+      // Access via bracket notation to avoid TypeScript complaints on older lib versions.
+      const tw = (cs as unknown as Record<string, string>)['textWrap'];
+      if (tw) node.textWrap = tw;
+    }
+    // Capture overflow when non-default so SYS-TEXT-CLIP can identify clipping parents.
+    // Skip 'visible' (the CSS default) to keep the IR sparse.
+    if (cs.overflow && cs.overflow !== 'visible') node.overflow = cs.overflow;
+
+    // Motion: non-zero transition-durations, non-zero animation-durations, and any named
+    // animation. `transition-duration`/`transition-timing-function` and
+    // `animation-duration`/`animation-timing-function` are each parallel comma-separated
+    // lists per the spec. Both duration kinds land in one list — a page's motion rhythm
+    // does not care whether a duration came from `transition` or `@keyframes`.
+    //
+    // The duration and timing-function lists are parallel by index (cycling the shorter
+    // one per spec), so a timing function is only "in play" when its own transition's
+    // duration survives the >0 filter — a `transition: a .3s, b 0s` must not credit the
+    // page with `b`'s easing when `b` never actually transitions (F6).
+    const transitionDurationsRaw = cs.transitionDuration
+      .split(',')
+      .map((v) => Math.round((parseFloat(v) || 0) * 1000));
+    const transitionDurations = transitionDurationsRaw.filter((ms) => ms > 0);
+    const timingFns = cs.transitionTimingFunction.split(',').map((v) => v.trim()).filter((v) => v.length > 0);
+    const transitionEasings = timingFns.length > 0
+      ? transitionDurationsRaw
+        .map((ms, i) => (ms > 0 ? (timingFns[i % timingFns.length] ?? null) : null))
+        .filter((v): v is string => v !== null && v.length > 0)
+      : [];
+    // CSS properties being transitioned, indexed parallel to transitionDurationsRaw.
+    // 'all' and 'none' are excluded so MOTION-LAYOUT-THRASH can match named layout
+    // properties (width/height/top/left/margin) without false-positives from 'all'.
+    const transitionPropsRaw = cs.transitionProperty
+      .split(',')
+      .map((v) => v.trim())
+      .filter((v) => v.length > 0 && v !== 'none' && v !== 'all');
+    const transitionProperties = transitionPropsRaw.length > 0
+      ? transitionDurationsRaw
+        .map((ms, i) => (ms > 0 ? (transitionPropsRaw[i % transitionPropsRaw.length] ?? null) : null))
+        .filter((v): v is string => v !== null && v.length > 0)
+      : [];
+    const animationNames = cs.animationName
+      .split(',')
+      .map((v) => v.trim())
+      .filter((v) => v.length > 0 && v !== 'none');
+    const animationDurations = animationNames.length > 0
+      ? cs.animationDuration.split(',').map((v) => Math.round((parseFloat(v) || 0) * 1000)).filter((ms) => ms > 0)
+      : [];
+    const animationEasings = animationNames.length > 0
+      ? cs.animationTimingFunction.split(',').map((v) => v.trim()).filter((v) => v.length > 0)
+      : [];
+    const allDurations = [...transitionDurations, ...animationDurations];
+    const easings = Array.from(new Set([
+      ...transitionEasings,
+      ...animationEasings,
+    ]));
+    if (allDurations.length > 0 || animationNames.length > 0) {
+      // Renamed from `transitionDurations` (F5): this list holds animation durations too.
+      node.motion = {
+        durations: allDurations,
+        animationNames,
+        easings,
+        ...(transitionProperties.length > 0 ? { properties: transitionProperties } : {}),
+      };
+    }
+
+    const text = ownText(el);
+    if (text) node.text = text;
+    const heading = headingOf(el);
+    if (heading) node.heading = heading;
+    if (cs.boxShadow && cs.boxShadow !== 'none') node.shadow = { value: cs.boxShadow, token: nameOf(cs.boxShadow) };
+    if (cs.backgroundImage && cs.backgroundImage.includes('gradient')) {
+      // The browser reports stops as rgb(); normalise to hex so a rule can read the colour
+      // instead of parsing two notations, and so the IR stays byte-stable across engines.
+      node.gradient = cs.backgroundImage.replace(/rgba?\([^)]+\)/g, (m) => toHex(m) ?? m);
+    }
+    // background-clip: text is the gradient-text tell. The browser may prefix this as
+    // -webkit-background-clip in some engines; check both. Only set when a gradient is also
+    // present — a clipped solid colour is a different pattern entirely.
+    const bgClip = cs.backgroundClip || (cs as unknown as Record<string, string>)['webkitBackgroundClip'];
+    if (node.gradient && (bgClip === 'text' || bgClip === '-webkit-text')) node.clipText = true;
+
+    // backdrop-filter is the glassmorphism tell: blur + translucent surface. The browser
+    // may prefix this as -webkit-backdrop-filter. Absent when 'none' or not declared.
+    const bf = cs.backdropFilter || (cs as unknown as Record<string, string>)['webkitBackdropFilter'];
+    if (bf && bf !== 'none') node.backdropFilter = bf;
+    if (cs.textAlign === 'left' || cs.textAlign === 'center' || cs.textAlign === 'right' || cs.textAlign === 'justify') {
+      node.textAlign = cs.textAlign;
+    }
+
+    const isFlex = cs.display.includes('flex') || cs.display.includes('grid');
+    if (isFlex || declares(authored, 'padding')) {
+      node.layout = {
+        mode: cs.flexDirection === 'column' ? 'VERTICAL' : 'HORIZONTAL',
+        gap: px(cs.rowGap === 'normal' ? '0' : cs.rowGap),
+        padding: [px(cs.paddingTop), px(cs.paddingRight), px(cs.paddingBottom), px(cs.paddingLeft)],
+      };
+    }
+
+    nodes.push(node);
+    if (parentId) nodes.find((n) => n.id === parentId)?.children.push(id);
+    for (const child of Array.from(el.children)) walk(child, id);
+  };
+
+  let root: Element = document.body;
+  if (selector) {
+    const found = document.querySelector(selector);
+    if (!found) throw new Error(`no element matches selector: ${selector}`);
+    root = found;
+  }
+  walk(root, null);
+
+  // Contrast needs a real backdrop, not `transparent`. Inherit the nearest painted fill.
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  for (const node of nodes) {
+    if (node.fill) continue;
+    for (let p = node.parent; p; p = byId.get(p)?.parent ?? null) {
+      const ancestor = byId.get(p);
+      if (ancestor?.fill) {
+        node.fill = { ...ancestor.fill, inherited: true };
+        break;
+      }
+    }
+    if (!node.fill) {
+      // The captured root itself may have no painted fill within the walk (it's
+      // transparent, or a scoped selector cut it off from the page's own background).
+      // Defaulting to white would poison contrast math with a backdrop nobody painted;
+      // walk the root's live-DOM ancestors (its own parent up through documentElement,
+      // same climb the whole-page path always used since root there IS document.body)
+      // for the first actually-painted backgroundColor.
+      let paintedHex: string | null = null;
+      for (let anc: Element | null = root.parentElement; anc; anc = anc.parentElement) {
+        const ancBg = toHex(getComputedStyle(anc).backgroundColor);
+        if (ancBg) {
+          paintedHex = ancBg;
+          break;
+        }
+      }
+      node.fill = paintedHex
+        ? { value: paintedHex, token: nameOf(paintedHex), inherited: true }
+        : { value: '#FFFFFF', token: null, inherited: true };
+    }
+  }
+
+  // Page-level scroll/viewport dimensions. scrollHeight is the total scrollable height
+  // of the document (including content below the fold). viewportHeight is the current
+  // window inner height — together they let rules determine whether elements are above
+  // or below the fold without needing to know the URL or viewport preset.
+  //
+  // Cannot capture: viewport dimensions when the page is rendered inside an iframe
+  // (window.innerHeight reflects the frame, not the outer viewport). The capture is
+  // correct for top-level documents, which is the only case omd check operates on.
+  const scrollHeight = document.documentElement.scrollHeight;
+  const viewportHeight = window.innerHeight;
+  const fontFaces = Array.from(document.fonts).map((face) => ({
+    family: face.family,
+    status: face.status,
+    style: face.style,
+    weight: face.weight,
+    stretch: face.stretch,
+    source: null,
+    glyphIdentity: null,
+  }));
+
+  return {
+    meta: { source: 'dom', url: location.href, scrollHeight, viewportHeight, fontFaces },
+    tokens: tokenByValue,
+    nodes,
+  };
+}

package/core/ir/normalize.ts

@@ -0,0 +1,177 @@
+import type { Computed, Hex, Ir, Node, RawIr, RawNode, Stats } from '../types.ts';
+
+type Padding = [number, number, number, number];
+
+export function contrastRatio(hexA: Hex, hexB: Hex): number {
+  const luminance = (hex: Hex): number => {
+    const clean = hex.replace('#', '');
+    const f = (c: number): number => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+    const [r, g, b] = [0, 2, 4].map((i) => f(parseInt(clean.slice(i, i + 2), 16) / 255)) as [number, number, number];
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  };
+  const la = luminance(hexA);
+  const lb = luminance(hexB);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+type Index = Map<string, RawNode>;
+
+function depthOf(node: RawNode, byId: Index): number {
+  let depth = 0;
+  let current = node;
+  while (current.parent) {
+    const parent = byId.get(current.parent);
+    if (!parent) break;
+    current = parent;
+    depth += 1;
+  }
+  return depth;
+}
+
+function contrastWithParent(node: RawNode, byId: Index): number | null {
+  if (!node.parent) return null;
+  const parentFill = byId.get(node.parent)?.fill?.value;
+
+  // Text sits on whatever surface it declares, falling back to the parent's. A container
+  // is always measured against its parent — measuring it against its own fill would
+  // silently return 1.0 and hide a dark card on a dark page.
+  const [self, background] =
+    node.type === 'TEXT'
+      ? [node.color ?? node.fill?.value, node.fill?.value ?? parentFill]
+      : [node.fill?.value, parentFill];
+
+  if (typeof self !== 'string' || typeof background !== 'string') return null;
+  return contrastRatio(self, background);
+}
+
+function modeOf(values: number[]): number {
+  const counts = new Map<number, number>();
+  for (const v of values) counts.set(v, (counts.get(v) ?? 0) + 1);
+  let best = values[0] ?? 0;
+  let bestCount = -1;
+  for (const [v, c] of counts) {
+    if (c > bestCount || (c === bestCount && v < best)) {
+      best = v;
+      bestCount = c;
+    }
+  }
+  return best;
+}
+
+function siblingPaddingMode(node: RawNode, byId: Index, childrenOf: Map<string, string[]>): Padding | null {
+  const own = node.layout?.padding;
+  if (!own) return null;
+
+  const siblings = (node.parent ? childrenOf.get(node.parent) ?? [] : [])
+    .map((id) => byId.get(id))
+    .filter((s): s is RawNode => Boolean(s) && s!.id !== node.id && Boolean(s!.layout?.padding));
+
+  if (siblings.length === 0) return null;
+  return own.map((_, i) => modeOf(siblings.map((s) => s.layout!.padding[i] ?? 0))) as Padding;
+}
+
+const TOKENABLE = ['fill', 'radius'] as const;
+
+function tokenCoverage(node: RawNode): number {
+  const present = TOKENABLE.filter((p) => node[p] != null);
+  if (present.length === 0) return 1;
+  return present.filter((p) => node[p]!.token != null).length / present.length;
+}
+
+// Same tag(-ish) name, same child count, same radius, same shadow — the feature-card grid
+// every generated landing page reaches for when nobody decided what matters most.
+function shapeSignature(node: RawNode): string {
+  const name = node.name.split('.')[0];
+  return `${name}|${node.children.length}|${node.radius?.value ?? 'none'}|${node.shadow?.value ?? 'none'}`;
+}
+
+function identicalSiblings(node: RawNode, childrenOf: Map<string, string[]>, byId: Index): number {
+  if (!node.parent) return 0;
+  const sibIds = childrenOf.get(node.parent) ?? [];
+  const mySig = shapeSignature(node);
+  let count = 0;
+  for (const id of sibIds) {
+    const sibling = byId.get(id);
+    if (sibling && shapeSignature(sibling) === mySig) count += 1;
+  }
+  return count;
+}
+
+function computeStats(nodes: RawNode[]): Stats {
+  const spacingHistogram: Record<string, number> = {};
+  const colorHistogram: Record<string, number> = {};
+  const componentReuse: Record<string, number> = {};
+  const radiusHistogram: Record<string, number> = {};
+  const shadowHistogram: Record<string, number> = {};
+  const bump = (bag: Record<string, number>, key: string | number): void => {
+    bag[key] = (bag[key] ?? 0) + 1;
+  };
+
+  const gradients: string[] = [];
+  const seenGradients = new Set<string>();
+  let textNodes = 0;
+  let centeredTextNodes = 0;
+
+  for (const node of nodes) {
+    if (node.layout?.padding) for (const v of node.layout.padding) bump(spacingHistogram, v);
+    if (node.layout?.gap != null) bump(spacingHistogram, node.layout.gap);
+    if (node.fill) bump(colorHistogram, String(node.fill.value));
+    bump(componentReuse, node.name);
+    if (node.radius) bump(radiusHistogram, node.radius.value);
+    if (node.shadow) bump(shadowHistogram, node.shadow.value);
+    if (node.gradient && !seenGradients.has(node.gradient)) {
+      seenGradients.add(node.gradient);
+      gradients.push(node.gradient);
+    }
+    if (node.text) {
+      textNodes += 1;
+      if (node.textAlign === 'center') centeredTextNodes += 1;
+    }
+  }
+
+  const orphanStyles = Object.entries(colorHistogram)
+    .filter(([, count]) => count === 1)
+    .map(([value]) => value)
+    .sort();
+
+  const centeredTextRatio = textNodes === 0 ? 0 : Math.round((centeredTextNodes / textNodes) * 10000) / 10000;
+
+  return {
+    spacingHistogram,
+    colorHistogram,
+    orphanStyles,
+    componentReuse,
+    radiusHistogram,
+    shadowHistogram,
+    centeredTextRatio,
+    gradients,
+  };
+}
+
+export function normalize(rawIr: RawIr): Ir {
+  const clone = structuredClone(rawIr);
+  const byId: Index = new Map(clone.nodes.map((n) => [n.id, n]));
+
+  const childrenOf = new Map<string, string[]>();
+  for (const n of clone.nodes) {
+    if (!n.parent) continue;
+    const bucket = childrenOf.get(n.parent);
+    if (bucket) bucket.push(n.id);
+    else childrenOf.set(n.parent, [n.id]);
+  }
+
+  const nodes: Node[] = clone.nodes.map((node) => {
+    const computed: Computed = {
+      depth: depthOf(node, byId),
+      contrastWithParent: contrastWithParent(node, byId),
+      siblingPaddingMode: siblingPaddingMode(node, byId, childrenOf),
+      tokenCoverage: tokenCoverage(node),
+      hitArea: { w: node.box.w, h: node.box.h },
+      isInteractive: Boolean(node.interactive),
+      identicalSiblings: identicalSiblings(node, childrenOf, byId),
+    };
+    return { ...node, computed };
+  });
+
+  return { ...clone, nodes, stats: computeStats(clone.nodes) };
+}

package/core/motion/easing.md

@@ -0,0 +1,151 @@
+# Easing vocabulary — curated token set
+
+The keyword easings shipped in CSS (`ease`, `ease-in`, `ease-out`, `ease-in-out`) are
+not a vocabulary — they are placeholders. A design system that stops there has one word
+for every kind of change. This file establishes the curated set this system uses, with
+the semantic reasoning for each curve and the register it belongs to.
+
+Cross-reference: `core/theory/motion.md` explains the semantics of ease-out vs. ease-in
+vs. ease-in-out in detail. The tokens below are the *specific curves* — the parameterised
+forms — that belong to each semantic slot. Recipes reference these tokens directly;
+hardcoding cubic-bezier values in a component is the same defect as a hardcoded hex colour.
+
+---
+
+## The token set
+
+### Arrivals (ease-out family)
+
+```css
+:root {
+  /* Expo: fast onset, long tail. The object arrives with authority and settles precisely.
+     Reads as: the system heard you immediately. Use for: hero entrances, overlay opens,
+     drawer slides, any element arriving from outside the viewport.
+     Register: showpiece, confident. The snappiest of the out-curves.
+     Antonym of 500ms ease-in-out: where that reads generated, this reads decided. */
+  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+
+  /* Quint: softer onset than expo, same long tail. Slightly less authoritative,
+     slightly more graceful. Use for: content reveals, card entrances, scroll-triggered
+     elements that should arrive without demanding attention.
+     Register: confident, showpiece. */
+  --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);
+
+  /* Back: overshoots the target, rebounds to rest. The object lands with a bounce.
+     Use for: playful UI, game-adjacent contexts, elements whose concept includes
+     elasticity. Not appropriate for utility UI — the overshoot reads as imprecision in
+     a product the user came to operate.
+     Register: showpiece only. Use sparingly — one element per page that earns a bounce. */
+  --ease-out-back: cubic-bezier(0.34, 1.56, 0.64, 1);
+
+  /* Circ: extremely crisp deceleration. Starts near-linear, stops hard.
+     Use for: elements that need to read as controlled — mechanical precision, technical
+     brand registers, UI where snap is a feature.
+     Register: confident, quiet (for micro-interactions). */
+  --ease-out-circ: cubic-bezier(0, 0.55, 0.45, 1);
+}
+```
+
+### Departures (ease-in family)
+
+```css
+:root {
+  /* Expo: slow pickup, fast exit. The object leaves with finality.
+     Use for: dismissals, modals closing, elements exiting the viewport.
+     Almost never correct for entrances — a slow start reads as latency.
+     See core/theory/motion.md: "ease-in (gradual start, fast finish): an object leaving." */
+  --ease-in-expo: cubic-bezier(0.7, 0, 0.84, 0);
+
+  /* Quint: softer ease-in. Use for exits that should feel deliberate without being
+     dramatic — a panel sliding away, a tooltip disappearing.
+     Register: confident. */
+  --ease-in-quint: cubic-bezier(0.64, 0, 0.78, 0);
+}
+```
+
+### State transitions (ease-in-out family)
+
+```css
+:root {
+  /* Quint in-out: symmetrical, both ends deeply decelerated. For elements moving
+     between two significant states — a position change, a layout shift — where
+     the before-state and after-state both carry meaning. Neither arrival nor
+     departure dominates; the motion reads as a measured pivot.
+     Register: quiet, confident. Not for fast micro-interactions. */
+  --ease-in-out-quint: cubic-bezier(0.83, 0, 0.17, 1);
+
+  /* Standard: the Material Design standard easing. Less pronounced deceleration
+     than quint in-out. Use for UI state changes that need to feel native and
+     predictable — tabs switching, accordion expanding, toggle switching.
+     Register: quiet, confident. */
+  --ease-standard: cubic-bezier(0.2, 0, 0, 1);
+}
+```
+
+### Spring approximation
+
+```css
+:root {
+  /* Spring via linear(): a physics-approximated spring using the CSS linear()
+     function. Produces an overshoot-and-settle that reads as weight and momentum
+     rather than the geometric bounce of ease-out-back.
+     Fallback: --ease-out-back for browsers without linear() support (check via
+     @supports (animation-timing-function: linear(0, 1))).
+     Use for: elements whose register is "physical" — draggable cards, shelf items,
+     anything that should feel like it has mass.
+     Register: showpiece. */
+  --ease-spring: linear(
+    0, 0.009, 0.035 2.1%, 0.141, 0.281 6.7%, 0.723 12.9%, 0.938 16.7%,
+    1.017, 1.077, 1.121, 1.149 24.3%, 1.159, 1.163, 1.161, 1.154 29.9%,
+    1.129 33.8%, 1.051 39.6%, 1.017 43.1%, 0.991, 0.977 51%, 0.974 53.8%,
+    0.975 57.1%, 0.997 69.8%, 1.003 76.9%, 1.004 83.8%, 1
+  );
+}
+```
+
+### Constant-velocity (linear)
+
+```css
+:root {
+  /* Linear is not a fallback — it is a semantic choice.
+     Use for: opacity changes on hover states (eased opacity on hover feels
+     sluggish; linear matches the perceived snap of pointer movement);
+     looping animations (spinners, progress bars, marquees) where acceleration
+     and deceleration would produce visible stuttering on each cycle.
+     See core/theory/motion.md: "linear: no easing. Use for opacity changes on
+     hover states only." */
+  --ease-linear: linear;
+}
+```
+
+---
+
+## Which register uses which curve
+
+| Curve | Register | Canonical use |
+|---|---|---|
+| `--ease-out-expo` | showpiece, confident | Hero entrance, overlay, drawer |
+| `--ease-out-quint` | confident, showpiece | Scroll reveal, card entrance |
+| `--ease-out-back` | showpiece (sparing) | Playful bounce, elastic arrival |
+| `--ease-out-circ` | confident, quiet | Mechanical snap, micro-interaction |
+| `--ease-in-expo` | any | Exit, dismissal, departure |
+| `--ease-in-quint` | confident | Soft exit, panel away |
+| `--ease-in-out-quint` | quiet, confident | State pivot, position change |
+| `--ease-standard` | quiet, confident | Tab switch, toggle, accordion |
+| `--ease-spring` | showpiece | Physical element, draggable, weighty |
+| `--ease-linear` | any | Hover opacity, looping motion |
+
+---
+
+## The 500ms ease-in-out problem
+
+`transition: all 500ms ease-in-out` is the single most common signature of generated
+work. It is wrong for three independent reasons (see `core/theory/motion.md`): too slow
+for micro-interactions, too fast for meaningful spatial motion, and the uniform easing
+removes semantic distinction between different kinds of change. The token set above
+provides the antidote: distinct curves for arrivals, departures, pivots, and physical
+motion, each at the duration that earns it.
+
+When a hand reaches for `ease-in-out`, the question is: is this an arrival, a departure,
+or a pivot? Arrivals use an out-curve. Departures use an in-curve. Pivots — and only
+pivots — use in-out.