@3xhaust/oh-my-design 0.16.1

package/core/rules/builtin/spacing.yaml

@@ -0,0 +1,9 @@
+id: SPACING-001
+layer: 1
+category: system
+severity: warn
+when: "Boolean(node.layout && node.layout.padding)"
+value: "node.layout.padding"
+assert: "value.every((v) => v % 8 === 0 || v === 4)"
+message: "Padding {value} is off the 8pt grid (4 excepted)"
+fix: normalize-spacing

package/core/rules/builtin/system.yaml

@@ -0,0 +1,42 @@
+# System-level correctness rules that do not fit the existing per-category files.
+# Category 'system' means something is measurably wrong in the implementation — not a
+# design-mean convergence failure (slop), not a user-facing access barrier (a11y), and not
+# an animation craft defect (motion).
+
+# SYS-TEXT-CLIP: detects a text node whose rendered layout box extends below its parent's
+# bottom edge when the parent clips overflow (overflow: hidden or clip). The canonical case
+# is a clamp()-sized display heading whose last-line descender is cut off at the container.
+#
+# Measurement basis: getBoundingClientRect() returns the full CSS layout rect of the text
+# element, not the visually clipped rect — so node.box.h reflects the unclipped text height
+# even when the parent hides it. If text.box.bottom > parent.box.bottom + 4px and the
+# parent clips, the descender IS visually cut off and the user sees incomplete text.
+#
+# Guard on overflow value:
+#   overflow: hidden / clip  → clips without a scroll escape → rule fires
+#   overflow: visible        → text bleeds out intentionally → silent (not stored, treated as absent)
+#   overflow: scroll / auto  → clips but provides a scrollbar → silent (content accessible)
+#
+# Vertical-only check: only bottom-edge overflow is tested. Horizontal overflow is excluded
+# to avoid false positives from marquee tracks, which extend rightward inside an
+# overflow: hidden container by design (see core/motion/recipes/marquee.md).
+#
+# Threshold: 4px. Sub-pixel rounding and browser differences can produce 1–2px mismatches
+# on legitimate layouts; 4px filters those without masking real descender clips (which
+# are typically 8–20px depending on font and size).
+#
+# Known limitation: position: absolute / fixed children that legitimately overflow a
+# clipping ancestor will false-positive here. If the false-positive rate proves significant
+# in practice, extend dom.ts to capture cs.position on each node and add the guard:
+#   !node.position || (node.position !== 'absolute' && node.position !== 'fixed')
+#
+# Positive test:  text.box.y + text.box.h > parent.box.y + parent.box.h + 4, parent.overflow === 'hidden' → fires
+# Negative tests: parent.overflow absent (visible default) → silent; overflow within threshold → silent
+- id: SYS-TEXT-CLIP
+  layer: 1
+  category: system
+  severity: warn
+  when: "Boolean(node.text) && node.parent !== null"
+  value: "(() => { const parent = ir.nodes.find(n => n.id === node.parent); if (!parent) return null; if (parent.overflow !== 'hidden' && parent.overflow !== 'clip') return null; const overflowPx = (node.box.y + node.box.h) - (parent.box.y + parent.box.h); return overflowPx > 4 ? overflowPx : null; })()"
+  assert: "value === null"
+  message: "Text overflows its clipping parent by {value}px (bottom edge). The parent has overflow: hidden — the descender or last line is visually cut off. Fix: remove the explicit height from the parent and let it size to its content, add padding-bottom to accommodate the text at the smallest clamp() value, or verify that the clamp() minimum renders without clipping at 375px viewport width."

package/core/rules/builtin/token.yaml

@@ -0,0 +1,8 @@
+id: TOKEN-003
+layer: 1
+category: system
+severity: warn
+when: "Boolean(node.fill) && !node.fill.inherited && node.fill.authored !== false"
+value: "node.fill.token"
+assert: "value !== null"
+message: "Fill is not tokenised (got {value})"

package/core/rules/builtin/ux.yaml

@@ -0,0 +1,125 @@
+# UX rules — task-first structural correctness.
+#
+# These rules target measurable UX violations detectable from the IR alone.
+# They do NOT require viewport height, motion probes, or any runtime state
+# beyond the static IR snapshot.
+#
+# Category 'slop' is used here because UX convergence-to-the-mean (two identical
+# primary buttons, no exits from error states) is in the same family as visual
+# convergence-to-the-mean — correct, competent, anonymously generated. Each rule
+# is a warning; a deliberate choice can be overridden with an omd decision record.
+#
+# Candidate studied and dropped:
+#   UX-ACTION-BELOW-FOLD — the IR records node.box.y but does NOT store the
+#   viewport height at check time (ir.meta has motion and interaction probe data
+#   but no viewport dimensions). Without a reliable viewport-height anchor the
+#   threshold is undefined and the false-positive rate is unacceptable. The
+#   eye agent's task-first UX pass walks this check visually instead.
+#
+# Candidate retained:
+#   UX-TWO-PRIMARIES — two or more sibling interactive buttons sharing the same
+#   authored fill colour in the same parent container. This pattern cancels the
+#   hierarchy signal: the user cannot determine which action the design recommends.
+#   Measurable because: node.computed.isInteractive (set by the DOM reader),
+#   node.fill.authored (explicitly set by the author, not inherited), node.fill.value
+#   (computed hex), node.box.h >= 36 (button-sized, excludes icon buttons and inline
+#   links), node.parent (sibling grouping — only fires when the competing buttons
+#   share a container, not when the same colour CTA repeats across different sections).
+#
+# Theory basis: theory/ux.md §Task-first framing; theory/components.md §Buttons.
+# Material Design and Carbon Design System both specify single primary-per-view as an
+# explicit constraint, not a preference.
+
+# UX-ACTION-BELOW-FOLD
+#
+# Fires on the root node when the page has interactive controls but NONE of them are
+# within the first viewport at mobile dimensions. "Within the first viewport" means the
+# element's top edge (box.y) is less than viewportHeight — at least the top of the
+# control is visible without scrolling.
+#
+# Revived from the candidate-dropped list now that dom.ts captures scrollHeight and
+# viewportHeight in ir.meta. The earlier drop reason ("viewport height undefined,
+# threshold unanchored") is eliminated: viewportHeight is the actual window height
+# measured at capture time, so the fold is the real browser fold, not an assumed constant.
+#
+# False-positive guard: "long content pages legitimately push a CTA down."
+# The rule fires ONLY when there is NO interactive element within the first viewport.
+# A page with a nav link at y=20 and a CTA at y=1200 does not fire (nav is interactive
+# and within fold). Only a page where every control — including nav items — is below
+# the fold triggers the rule. That condition is never a deliberate choice; it is always
+# a layout bug or a missed mobile viewport regression.
+#
+# Positive test:  one interactive element at box.y=900 with viewportHeight=812 → fires
+# Negative tests:
+#   — interactive element at box.y=100 (within fold at 812) → silent
+#   — no interactive elements at all                         → silent (when guard)
+#   — interactive at y=900 AND nav at y=0 (two elements)    → silent (nav is in fold)
+#
+# The rule reads ir.meta.viewportHeight (set by dom.ts). On IRs captured without it
+# (before dom.ts was updated) the when condition is false and the rule is silent —
+# backward compatible.
+- id: UX-ACTION-BELOW-FOLD
+  layer: 1
+  category: ux
+  severity: warn
+  when: "node.parent === null && typeof (ir.meta && ir.meta.viewportHeight) === 'number' && ir.nodes.some(n => n.computed.isInteractive)"
+  value: "(() => { const vh = Number(ir.meta.viewportHeight); return ir.nodes.filter(n => n.computed.isInteractive && n.box.y < vh).length; })()"
+  assert: "value > 0"
+  message: "No interactive element is visible within the first viewport (viewportHeight={value}px measured at capture). The primary action is entirely below the fold. Place at least one interactive control — a primary button, a nav item, or a search field — within the first screen of content. See theory/ux.md §Task-first framing."
+
+# UX-NO-KEYBOARD-PATH
+#
+# Fires on the root node when the page has interactive controls but every one of them
+# has been explicitly removed from the tab order with tabindex="-1". A page in this
+# state is not keyboard-navigable: no interactive element is reachable by pressing Tab.
+#
+# Data source: node.focusable captured by dom.ts from el.tabIndex per node.
+#   true  — element is in the tab order (tabIndex >= 0)
+#   false — element is interactive but carries tabindex="-1" (removed)
+#   absent — static element, no focusability data
+#
+# Guard on when: the rule fires only when at least one interactive node has a recorded
+# focusable field. On pages where no focusable data was captured at all (old IRs, or
+# pages where the extractor produced no interactive nodes with focusable set), the when
+# condition is false and the rule is silent — preventing false positives from missing data.
+#
+# Deliberate exemption: pages that implement custom focus management (e.g., a single-page
+# app routed with a focus trap) will use tabindex="-1" on most elements intentionally.
+# This rule fires a warning; override with `omd decision` and document the focus management
+# strategy. A page with zero keyboard-reachable interactive controls is always worth
+# flagging even if the custom management turns out to be correctly implemented.
+#
+# Positive test:  button with focusable:false (tabindex="-1"), no other interactive nodes → fires
+# Negative tests:
+#   — button with focusable:true → silent
+#   — no interactive elements at all → silent (when guard)
+#   — mix: one focusable:false, one focusable:true → silent (one keyboard path exists)
+- id: UX-NO-KEYBOARD-PATH
+  layer: 1
+  category: ux
+  severity: warn
+  when: "node.parent === null && ir.nodes.some(n => n.computed.isInteractive && typeof n.focusable === 'boolean')"
+  value: "ir.nodes.filter(n => n.computed.isInteractive && n.focusable !== false).length"
+  assert: "value > 0"
+  message: "Every interactive control on this page has been removed from the keyboard tab order (tabindex=\"-1\"). Users who navigate by keyboard cannot reach any interactive element. Either remove the tabindex=\"-1\" attribute to restore native focus, or implement and document a custom keyboard focus strategy. WCAG 2.1 §2.1.1 requires all functionality to be keyboard-operable. See theory/ux.md §Accessibility as a UX floor."
+
+# UX-TWO-PRIMARIES
+#
+# Fires on the root node when any parent container has 2+ interactive, button-sized
+# children with the same authored fill colour. The value is the count of competing
+# sibling groups (1+ means at least one container has this problem).
+#
+# Positive test:  two <button> siblings with identical background-color → fires
+# Negative tests:
+#   — one primary + one secondary (different fill/no-fill) → silent
+#   — two primaries in different parent containers            → silent
+#   — two small icon buttons (h < 36) with same fill         → silent
+#   — two buttons where fill.authored is false (inherited)   → silent
+- id: UX-TWO-PRIMARIES
+  layer: 1
+  category: slop
+  severity: warn
+  when: "node.parent === null"
+  value: "(() => { const grouped = {}; ir.nodes.filter(n => n.computed.isInteractive && n.fill && n.fill.authored && n.box.h >= 36).forEach(n => { const key = (n.parent ?? 'root') + ':' + String(n.fill.value); grouped[key] = (grouped[key] || 0) + 1; }); return Object.entries(grouped).filter(([,c]) => c >= 2).length; })()"
+  assert: "value === 0"
+  message: "{value} container(s) on this page have two or more interactive buttons sharing the same primary fill colour. Two filled buttons of equal visual weight cancel the hierarchy signal — the user cannot determine which action the design recommends. Demote one to secondary (outlined) or tertiary (text-only) per view. See theory/ux.md and theory/components.md."

package/core/rules/engine.ts

@@ -0,0 +1,88 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import type { Category, Ir, Layer, Node, Rule, RuleValue, Violation } from '../types.ts';
+
+export function loadRules(dirPath: string): Rule[] {
+  const rules: Rule[] = [];
+  const seen = new Set<string>();
+
+  for (const file of readdirSync(dirPath).filter((f) => f.endsWith('.yaml'))) {
+    const parsed: unknown = parse(readFileSync(join(dirPath, file), 'utf8'));
+    for (const rule of (Array.isArray(parsed) ? parsed : [parsed]) as Rule[]) {
+      if (seen.has(rule.id)) throw new Error(`duplicate rule id "${rule.id}" found in ${file}`);
+      seen.add(rule.id);
+      if (!rule.category) throw new Error(`rule "${rule.id}" is missing category`);
+      rules.push(rule);
+    }
+  }
+  return rules;
+}
+
+type Compiled = (node: Node, ir: Ir, value: RuleValue) => unknown;
+
+const cache = new Map<string, Compiled>();
+
+function compile(ruleId: string, expr: string): Compiled {
+  const key = `${ruleId} ${expr}`;
+  let fn = cache.get(key);
+  if (!fn) {
+    // Rules are local, authored files, not user input.
+    fn = new Function('node', 'ir', 'value', `return (${expr})`) as Compiled;
+    cache.set(key, fn);
+  }
+  return fn;
+}
+
+function evalExpr(ruleId: string, expr: string, node: Node, ir: Ir, value: RuleValue): unknown {
+  try {
+    return compile(ruleId, expr)(node, ir, value);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`rule ${ruleId}: error evaluating "${expr}": ${message}`);
+  }
+}
+
+function formatValue(v: unknown): string {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'number') return Number.isInteger(v) ? String(v) : v.toFixed(2);
+  if (typeof v === 'object') return JSON.stringify(v);
+  return String(v);
+}
+
+function interpolate(template: string, ctx: Record<string, unknown>): string {
+  return template.replace(/\{(\w+)\}/g, (_, key: string) => formatValue(ctx[key]));
+}
+
+export function check(ir: Ir, rules: Rule[], opts: { layers?: Layer[]; categories?: Category[] } = {}): Violation[] {
+  const violations: Violation[] = [];
+
+  for (const rule of rules) {
+    if (opts.layers && !opts.layers.includes(rule.layer)) continue;
+    if (opts.categories && !opts.categories.includes(rule.category)) continue;
+
+    for (const node of ir.nodes) {
+      if (!evalExpr(rule.id, rule.when, node, ir, null)) continue;
+
+      const value = (rule.value ? evalExpr(rule.id, rule.value, node, ir, null) : null) as RuleValue;
+      if (evalExpr(rule.id, rule.assert, node, ir, value)) continue;
+
+      violations.push({
+        id: rule.id,
+        severity: rule.severity,
+        layer: rule.layer,
+        category: rule.category,
+        nodeId: node.id,
+        path: node.path,
+        value,
+        message: interpolate(rule.message, { id: rule.id, value }),
+      });
+    }
+  }
+
+  // Code-unit order, not localeCompare: the same rules must yield byte-identical output
+  // under any ICU locale, on any host. That equivalence is the product.
+  const cmp = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+  violations.sort((a, b) => cmp(a.path, b.path) || cmp(a.id, b.id));
+  return violations;
+}

package/core/rules/leakage.ts

@@ -0,0 +1,72 @@
+import type { Ir, Violation } from '../types.ts';
+
+const MIN_NODE_TOKENS = 6;
+const WINDOW = 5;
+
+/**
+ * Lowercase, strip markdown/frontmatter punctuation, collapse whitespace, tokenize on
+ * whitespace. Korean uses spaces between words, so whitespace tokenization still works —
+ * a CJK source with no spaces (e.g. Chinese) would need character n-grams instead; that
+ * case is out of scope here.
+ *
+ * F4: the leading YAML frontmatter block (`---\n...\n---`) is stripped entirely before
+ * tokenizing — previously only its `---` fences were removed by the punctuation strip
+ * below, leaving frontmatter keys (`why:`, `generator:`) and values as live grams. The
+ * body text (which conventionally repeats the same rationale in prose) still matches.
+ */
+function tokenize(text: string): string[] {
+  return text
+    .replace(/^---\n[\s\S]*?\n---\n?/, '')
+    .toLowerCase()
+    .replace(/[#*`>|-]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .split(' ')
+    .filter(Boolean);
+}
+
+function windows(tokens: string[], size: number): string[] {
+  const out: string[] = [];
+  for (let i = 0; i + size <= tokens.length; i++) out.push(tokens.slice(i, i + size).join(' '));
+  return out;
+}
+
+/**
+ * Design rationale belongs in .omd/, never in the shipped copy. This is the deterministic
+ * subset of that failure: a node's text quotes five or more consecutive tokens verbatim
+ * from a frame/decision record. Paraphrase is fine — only literal overlap fires, checked
+ * against a precomputed Set of record 5-grams so the whole scan stays O(text + records)
+ * rather than comparing every node window against every record window.
+ */
+export function findLeakedRationale(ir: Ir, records: string[]): Violation[] {
+  const recordGrams = new Set<string>();
+  for (const record of records) {
+    if (!record) continue;
+    const tokens = tokenize(record);
+    for (const w of windows(tokens, WINDOW)) recordGrams.add(w);
+  }
+  if (recordGrams.size === 0) return [];
+
+  const violations: Violation[] = [];
+  for (const node of ir.nodes) {
+    if (!node.text) continue;
+    const tokens = tokenize(node.text);
+    if (tokens.length < MIN_NODE_TOKENS) continue;
+
+    for (const w of windows(tokens, WINDOW)) {
+      if (!recordGrams.has(w)) continue;
+      violations.push({
+        id: 'SLOP-LEAKED-RATIONALE',
+        severity: 'warn',
+        layer: 1,
+        category: 'slop',
+        nodeId: node.id,
+        path: node.path,
+        value: w,
+        message: `Design rationale leaked into shipped copy: "${w}". The frame explains the work; the page must never quote it.`,
+      });
+      break; // one violation per node — first match
+    }
+  }
+  return violations;
+}

package/core/rules/motion-spec.ts

@@ -0,0 +1,204 @@
+import type { EnergyCurve, Ir, Violation } from '../types.ts';
+
+// ── Motion spec parser ───────────────────────────────────────────────────────
+//
+// motion-spec.md format (written by omd-hand before the build):
+//
+//   ## Scene name
+//   - trigger: load | scroll | hover
+//   - target: .selector
+//   - properties: opacity, transform
+//   - duration: 400ms (ref: motion-study-1)
+//   - easing: cubic-bezier(0.2,0,0,1)
+//   - stagger: 40ms between .card siblings   ← optional
+//
+// The parser splits on ## headers, then looks for `trigger:` in each section.
+
+type Trigger = 'load' | 'scroll' | 'hover' | 'unknown';
+
+interface SpecScene {
+  name: string;
+  trigger: Trigger;
+  hasStagger: boolean;
+}
+
+function parseMotionSpec(md: string): SpecScene[] {
+  // Split on h2 headers; slice(1) discards any preamble before the first ##.
+  const sections = md.split(/^##\s+/m).slice(1);
+  const scenes: SpecScene[] = [];
+
+  for (const section of sections) {
+    const lines = section.split('\n');
+    const name = lines[0]?.trim() ?? '';
+    if (!name) continue;
+
+    let trigger: Trigger = 'unknown';
+    const m = /(?:^|\s)trigger\s*:\s*(load|scroll|hover)/im.exec(section);
+    if (m) trigger = m[1]!.toLowerCase() as 'load' | 'scroll' | 'hover';
+
+    const hasStagger = /stagger/i.test(section);
+    scenes.push({ name, trigger, hasStagger });
+  }
+
+  return scenes;
+}
+
+function isShowpiece(frameMd: string | null): boolean {
+  if (!frameMd) return false;
+  return /showpiece/i.test(frameMd);
+}
+
+// ── Rule implementations ─────────────────────────────────────────────────────
+//
+// MOTION-SPEC-DRIFT
+//   Fires when the spec and the live probe disagree about whether motion exists:
+//   (a) spec describes load/scroll scenes → probe detected nothing, OR
+//   (b) probe detected animations → spec has no scenes.
+//   Rationale: the spec is a contract ("build will contain exactly these animations");
+//   a gap between spec and reality means either an unimplemented scene or an
+//   undocumented animation.
+//
+//   GSAP note: getAnimations() cannot see rAF-driven motion (GSAP, Anime.js). A
+//   GSAP-only page may legitimately appear as "probe detected nothing" even when the
+//   filmstrip energy curve shows motion. When energyCurve is present and peakEnergy > 0,
+//   it is used as a fallback signal for probe detection.
+//
+// MOTION-NO-ENTRANCE
+//   Fires only when: (1) frame.md commits to showpiece register, AND (2) motion-spec
+//   has at least one load-triggered scene, AND (3) neither the probe nor the energy
+//   curve detected any entrance animation. Rationale: a showpiece page that promised
+//   an entrance scene and delivered nothing is a broken contract between spec and build.
+//
+// MOTION-NO-STAGGER (dropped — unmeasurable with current probe data)
+//   Plan v2 M5 specified: fires when spec names a stagger but probe start-times of
+//   the scene's siblings are identical. DROPPED: the motion snapshots (t=0/500/1500ms)
+//   record animation count, duration, easing, and properties — but NOT per-element start
+//   times or delays. Without individual element start times there is no deterministic path
+//   to distinguish simultaneous-fire from staggered-fire. Implement when per-element
+//   start times become available from the probe.
+
+/**
+ * Compare `.omd/motion-spec.md` against live probe + energy data and return any
+ * MOTION-SPEC-DRIFT or MOTION-NO-ENTRANCE violations.
+ *
+ * Only called when `.omd/motion-spec.md` exists (the caller guards that).
+ *
+ * @param ir           Normalized IR from the current check run, with ir.meta.motion
+ *                     populated when the check ran against a live page target.
+ * @param motionSpecMd Content of .omd/motion-spec.md.
+ * @param frameMd      Content of .omd/frame.md, or null if absent.
+ * @param energyCurve  Energy curve from .omd/.cache/*-energy.json, or null if absent.
+ *                     Used as a fallback signal when getAnimations() cannot see the
+ *                     motion library in use (e.g. GSAP).
+ */
+export function checkMotionSpec(
+  ir: Ir,
+  motionSpecMd: string,
+  frameMd: string | null,
+  energyCurve: EnergyCurve | null,
+): Violation[] {
+  const violations: Violation[] = [];
+  const scenes = parseMotionSpec(motionSpecMd);
+
+  // Probe data may be absent (pre-probe IRs, or check run without a live page target).
+  // Skip all spec-vs-probe comparisons when it is: a ghost probe would produce false
+  // positives against any spec.
+  const motionProbe = ir.meta?.['motion'] as
+    | {
+        snapshots?: Array<{ t: number; animations: unknown[] }>;
+        animatedProperties?: string[];
+        scrollChoreography?: Array<{ step: number; fired: number; entered: number }>;
+      }
+    | null
+    | undefined;
+
+  if (!motionProbe) return violations;
+
+  // ── Whether the probe/energy detected any motion ─────────────────────────
+
+  const hasProbeAnimations = (motionProbe.animatedProperties?.length ?? 0) > 0;
+  const hasScrollFired = (motionProbe.scrollChoreography ?? []).some((s) => s.fired > 0);
+  // Energy > 0.5% pixel change: a negligible anti-alias flicker stays below this floor.
+  const hasEnergyMotion = energyCurve !== null && energyCurve.peakEnergy > 0.005;
+  const probeDetectedMotion = hasProbeAnimations || hasScrollFired || hasEnergyMotion;
+
+  // ── MOTION-SPEC-DRIFT ────────────────────────────────────────────────────
+
+  const loadScrollScenes = scenes.filter((s) => s.trigger === 'load' || s.trigger === 'scroll');
+
+  if (loadScrollScenes.length > 0 && !probeDetectedMotion) {
+    violations.push({
+      id: 'MOTION-SPEC-DRIFT',
+      severity: 'warn',
+      layer: 1,
+      category: 'motion',
+      nodeId: 'page',
+      path: 'motion-spec',
+      value: `spec:${loadScrollScenes.length},probe:0`,
+      message:
+        `motion-spec.md describes ${loadScrollScenes.length} load/scroll scene`
+        + `${loadScrollScenes.length === 1 ? '' : 's'} but the live probe detected no`
+        + ` animations (getAnimations returned nothing; filmstrip energy also absent or zero).`
+        + ` Either the scenes were not implemented, or they use GSAP/rAF which is invisible`
+        + ` to getAnimations() — run \`omd render --filmstrip\` and check the energy curve.`,
+    });
+  }
+
+  if (scenes.length === 0 && probeDetectedMotion) {
+    violations.push({
+      id: 'MOTION-SPEC-DRIFT',
+      severity: 'warn',
+      layer: 1,
+      category: 'motion',
+      nodeId: 'page',
+      path: 'motion-spec',
+      value: 'spec:0,probe:detected',
+      message:
+        'The live probe detected animations but motion-spec.md describes no scenes.'
+        + ' Animations not in the spec were not planned — add a scene entry for every'
+        + ' animation in the build, or remove the unplanned animations.',
+    });
+  }
+
+  // ── MOTION-NO-ENTRANCE ───────────────────────────────────────────────────
+
+  // Only fires when the page committed to showpiece AND the spec promised an entrance.
+  const hasEntranceScene = scenes.some((s) => s.trigger === 'load');
+  const showpiece = isShowpiece(frameMd);
+
+  if (showpiece && hasEntranceScene) {
+    // Probe snapshots at t=0ms and t=500ms cover the entrance window.
+    const snap0Anims = motionProbe.snapshots?.[0]?.animations.length ?? 0;
+    const snap500Anims = motionProbe.snapshots?.[1]?.animations.length ?? 0;
+    const probeEntranceDetected = snap0Anims > 0 || snap500Anims > 0;
+
+    // Energy from the first frame pair (t=0→t+interval) covers the same window.
+    const entranceEnergy = energyCurve !== null && energyCurve.pairs.length > 0
+      ? energyCurve.pairs[0]!.changedFraction
+      : null;
+    const energyEntranceDetected = entranceEnergy !== null && entranceEnergy > 0.005;
+
+    const entranceMeasured = probeEntranceDetected || energyEntranceDetected;
+
+    if (!entranceMeasured) {
+      violations.push({
+        id: 'MOTION-NO-ENTRANCE',
+        severity: 'warn',
+        layer: 1,
+        category: 'motion',
+        nodeId: 'page',
+        path: 'motion-spec',
+        value: 'showpiece+entrance-spec+no-measured-entrance',
+        message:
+          'This page commits to the showpiece register and motion-spec.md describes a'
+          + ' load-triggered entrance scene, but no entrance animation was detected'
+          + ' (getAnimations reported zero at t=0 and t=500ms; filmstrip energy is also'
+          + ' absent or zero). Either the entrance animation is not running, or it uses'
+          + ' GSAP/rAF — in that case run `omd render --filmstrip` to confirm via the'
+          + ' energy curve.',
+      });
+    }
+  }
+
+  return violations;
+}

package/core/site/index.ts

@@ -0,0 +1,100 @@
+import type { Invariants } from '../types.ts';
+
+/**
+ * A cross-page consistency finding. Not a per-node violation — these have no
+ * single node to anchor to. The `pages` array names every page involved.
+ */
+export interface SiteViolation {
+  id: 'SITE-TOKEN-DRIFT' | 'SITE-LADDER-DRIFT';
+  severity: 'warn';
+  /** All page paths involved in the comparison. */
+  pages: string[];
+  message: string;
+}
+
+/**
+ * One page's extracted data for site-level comparison.
+ *
+ * `invariants` must already be extracted (via extractInvariants in
+ * core/ref/invariants.ts). Keeping the comparison logic pure — no Ir, no
+ * browser — lets it be tested against synthetic fixtures without Playwright.
+ *
+ * `tokens` is the raw token map from RawIr.tokens (CSS custom property names
+ * → values). Absent for pages loaded from pre-computed IR files that pre-date
+ * the tokens field; treated as an empty set in that case.
+ */
+export interface SitePage {
+  path: string;
+  invariants: Invariants;
+  tokens?: Record<string, string>;
+}
+
+/**
+ * Cross-page consistency check. Pure function: no filesystem, no browser.
+ *
+ * SITE-LADDER-DRIFT fires when any of the three design ladders (type scale,
+ * spacing, radius) has a step count that differs by more than one across pages.
+ * A difference of one step is tolerated — a detail page may legitimately use
+ * one fewer text size than the index. A difference of two or more means the
+ * pages were built from different scales.
+ *
+ * SITE-TOKEN-DRIFT fires when token coverage varies by more than 0.3 across
+ * pages. Token coverage is the fraction of tokenable nodes (fill, radius) that
+ * cite a CSS custom property rather than an inline value. A page at 0.9 and
+ * another at 0.1 were built from different design-system disciplines.
+ *
+ * Returns an empty array for a single page — a site has no cross-page
+ * comparison to make.
+ */
+export function checkSite(pages: SitePage[]): SiteViolation[] {
+  if (pages.length < 2) return [];
+
+  const violations: SiteViolation[] = [];
+  const allPaths = pages.map((p) => p.path);
+
+  // ── Ladder drift ────────────────────────────────────────────────────────────
+
+  const ladderChecks: Array<{ name: string; get: (inv: Invariants) => number[] }> = [
+    { name: 'type scale', get: (inv) => inv.typeScale },
+    { name: 'spacing ladder', get: (inv) => inv.spacingLadder },
+    { name: 'radius ladder', get: (inv) => inv.radiusLadder },
+  ];
+
+  for (const { name, get } of ladderChecks) {
+    const entries = pages.map((p) => ({ path: p.path, steps: get(p.invariants).length }));
+    const stepCounts = entries.map((e) => e.steps);
+    const min = Math.min(...stepCounts);
+    const max = Math.max(...stepCounts);
+
+    if (max - min > 1) {
+      const detail = entries.map((e) => `${e.path}: ${e.steps}`).join(', ');
+      violations.push({
+        id: 'SITE-LADDER-DRIFT',
+        severity: 'warn',
+        pages: allPaths,
+        message: `${name} step count disagrees across pages (${detail})`,
+      });
+    }
+  }
+
+  // ── Token-coverage drift ────────────────────────────────────────────────────
+
+  const coverages = pages.map((p) => p.invariants.tokenCoverage);
+  const minCoverage = Math.min(...coverages);
+  const maxCoverage = Math.max(...coverages);
+
+  // Round to 4dp before comparing to avoid 0.9 - 0.6 = 0.30000000000000004 false-positives.
+  if (Math.round((maxCoverage - minCoverage) * 10000) / 10000 > 0.3) {
+    const detail = pages
+      .map((p) => `${p.path}: ${p.invariants.tokenCoverage.toFixed(2)}`)
+      .join(', ');
+    violations.push({
+      id: 'SITE-TOKEN-DRIFT',
+      severity: 'warn',
+      pages: allPaths,
+      message: `token coverage varies by ${(maxCoverage - minCoverage).toFixed(2)} across pages (${detail})`,
+    });
+  }
+
+  return violations;
+}