@3xhaust/oh-my-design 0.16.1

package/core/motion/recipes/view-transitions.md

@@ -0,0 +1,239 @@
+# View transitions
+
+The View Transitions API (`document.startViewTransition()`) enables animated transitions
+between page states or between full pages — fading, sliding, morphing — with the browser
+capturing before and after snapshots and interpolating between them. Named transitions
+allow specific elements to be tracked: a card thumbnail that expands into a detail page,
+a heading that persists across a route change.
+
+## When it earns its place / When it does not
+
+Condition: a multi-page site or SPA where navigating between pages currently produces
+an abrupt content swap. View transitions convert the abrupt swap into a continuous
+spatial move — the user always understands where they came from and where they went.
+Particularly effective for: image-detail expansions (thumbnail → full page), list-to-
+detail navigations (article index → article), and route changes where a persistent
+element (the site header, a product image) should appear to carry across.
+
+Condition against: pages where navigation is rare and the content replacement is self-
+explanatory — a settings page, a dashboard tab switch that is already instant. Also:
+applications with complex, frequent state changes (a real-time data feed, a drag-and-
+drop interface) where capturing before/after snapshots introduces visible latency. The
+API captures a screenshot of the leaving state; on content-heavy pages this screenshot
+capture is measurable and should be profiled before committing.
+
+The technique is progressive enhancement: browsers without View Transitions API support
+navigate normally without any animation. Never block navigation on this feature.
+
+## Parameters
+
+```css
+/* View transition durations are set as ::view-transition-* pseudo-element rules,
+   not as custom properties on :root. But document the values here for the hand
+   to wire from the board's motion invariants. */
+
+:root {
+  /* Duration for the default cross-fade (root view transition). */
+  --vt-duration: 280ms;
+
+  /* Duration for named element transitions (e.g., card → detail morph). */
+  --vt-named-duration: 380ms;
+
+  /* Easing for entering elements. */
+  --vt-enter-ease: var(--ease-out-expo);
+
+  /* Easing for exiting elements. */
+  --vt-exit-ease: var(--ease-in-quint);
+}
+```
+
+## Implementation
+
+```css
+/* ── Default cross-fade (applies to the entire page swap) ─────────────────── */
+
+/* The browser's built-in view-transition cross-fade animates opacity from 1→0
+   (old) and 0→1 (new). Override duration and easing; the opacity animation is
+   provided by the UA stylesheet and runs as a compositor-only operation. */
+::view-transition-old(root) {
+  animation-duration: var(--vt-duration);
+  animation-timing-function: var(--vt-exit-ease);
+  /* Explicit declaration for clarity — matches the UA default: */
+  animation-name: -ua-view-transition-fade-out;
+}
+
+::view-transition-new(root) {
+  animation-duration: var(--vt-duration);
+  animation-timing-function: var(--vt-enter-ease);
+  animation-name: -ua-view-transition-fade-in;
+}
+
+/* Custom fade-out / fade-in keyframes for full control over opacity. */
+@keyframes vt-fade-out {
+  from { opacity: 1; }
+  to   { opacity: 0; }
+}
+
+@keyframes vt-fade-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+
+/* Apply custom keyframes instead of UA defaults when you need explicit control: */
+/* ::view-transition-old(root) { animation-name: vt-fade-out; } */
+/* ::view-transition-new(root) { animation-name: vt-fade-in;  } */
+
+/* ── Named transition: card thumbnail → detail hero ───────────────────────── */
+
+/* On the list page: mark the card image as a named participant. */
+.card-image[data-vt-id] {
+  view-transition-name: attr(data-vt-id); /* set dynamically per item */
+}
+
+/* On the detail page: the hero image carries the same view-transition-name. */
+.detail-hero-image {
+  view-transition-name: card-detail-hero; /* set via JS to match the source */
+}
+
+/* Customise the named element's transition independently from the page fade. */
+::view-transition-old(card-detail-hero),
+::view-transition-new(card-detail-hero) {
+  animation-duration: var(--vt-named-duration);
+  animation-timing-function: var(--vt-enter-ease);
+}
+
+::view-transition-group(card-detail-hero) {
+  /* The group animation is the morph between source and target positions/sizes.
+     Browser handles the interpolation; we set the duration and easing. */
+  animation-duration: var(--vt-named-duration);
+  animation-timing-function: var(--vt-enter-ease);
+}
+```
+
+```js
+// Multi-page (MPA) view transitions — triggered on link click.
+// The `@view-transition { navigation: auto; }` CSS rule handles this in supporting
+// browsers automatically. Add the rule and the browser does the rest.
+
+// For programmatic control or SPA route changes:
+async function navigateWithTransition(url) {
+  if (!document.startViewTransition) {
+    // Fallback: navigate normally.
+    window.location.href = url;
+    return;
+  }
+
+  // Set the named view-transition-name on the element that will morph.
+  // (Example: clicked card sets its image's view-transition-name before the transition.)
+  const transition = document.startViewTransition(async () => {
+    // Swap the DOM content (fetch new page, update router, etc.)
+    await fetch(url).then(/* ... update DOM ... */);
+  });
+
+  // Handle transition completion for cleanup.
+  await transition.finished;
+}
+
+// For MPA with CSS-only activation:
+// Add this to your CSS and the browser handles it without JavaScript:
+```
+
+```css
+/* MPA automatic view transitions (Chrome 126+, no JS required): */
+@view-transition {
+  navigation: auto;
+}
+```
+
+## React
+
+```tsx
+// React Router 6.28+ has built-in View Transitions support via unstable_viewTransition.
+// For earlier versions or custom implementations:
+
+import { useNavigate } from 'react-router-dom';
+import { useCallback } from 'react';
+
+function useViewTransitionNavigate() {
+  const navigate = useNavigate();
+
+  return useCallback((to: string, options?: Parameters<typeof navigate>[1]) => {
+    if (!document.startViewTransition) {
+      navigate(to, options);
+      return;
+    }
+
+    document.startViewTransition(() => {
+      navigate(to, options);
+    });
+  }, [navigate]);
+}
+
+// Usage: assign view-transition-name on the element that should morph.
+function CardItem({ id, image, title }: { id: string; image: string; title: string }) {
+  const navigate = useViewTransitionNavigate();
+
+  return (
+    <article
+      onClick={() => navigate(`/work/${id}`)}
+      style={{ cursor: 'pointer' }}
+    >
+      <img
+        src={image}
+        alt={title}
+        // The name links this element to its counterpart on the detail page.
+        style={{ viewTransitionName: `card-image-${id}` }}
+      />
+    </article>
+  );
+}
+
+// On the detail page:
+function WorkDetail({ id }: { id: string }) {
+  return (
+    <img
+      src={`/images/${id}-hero.jpg`}
+      alt=""
+      style={{ viewTransitionName: `card-image-${id}` }}
+    />
+  );
+}
+```
+
+## Reduced-motion variant
+
+When `prefers-reduced-motion: reduce` is active, the view transition should use an
+instant switch or a very short cross-fade — not the full animated morph.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation-duration: 0.01ms !important;
+    animation-delay: 0ms !important;
+  }
+}
+```
+
+This preserves the API's before/after snapshot mechanism (which prevents content flash
+during SPA navigation) while removing the perceptible animation. Users get a fast,
+clean swap without motion.
+
+## Performance note
+
+`document.startViewTransition()` captures a screenshot of the current page state before
+making changes. On content-heavy pages, this screenshot capture is measurable — profile
+it before committing. The transition itself (the CSS animation between old and new
+states) runs off the main thread for elements with composited properties.
+
+Named transitions (`view-transition-name`) promote an element to its own compositor
+layer during the transition. This is correct behaviour — the element needs to animate
+independently from the page content around it. Remove or clear `view-transition-name`
+on elements that are not currently transitioning; permanently promoted layers consume
+GPU memory without benefit.
+
+Unique `view-transition-name` values are required across all simultaneously visible
+named elements. Two elements with the same `view-transition-name` produce undefined
+behaviour. When setting names dynamically (e.g., per-card IDs), ensure the ID is stable
+and unique across the page.

package/core/probe/index.ts

@@ -0,0 +1,186 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+type Expectation =
+  | { type: 'visible' | 'hidden'; selector: string }
+  | { type: 'text'; selector: string; value: string }
+  | { type: 'url'; value: string }
+  | { type: 'attribute'; selector: string; name: string; value: string };
+type Step = { action: 'click' | 'fill' | 'press'; selector?: string; value?: string; key?: string; expect?: Expectation[] };
+export interface ProbePlan {
+  name: string;
+  destructive: false;
+  expectedTabOrder?: string[];
+  steps: Step[];
+}
+export interface ProbeWarning { id: 'PROBE-TAB-DISORDER' | 'PROBE-DEAD-CONTROL'; severity: 'warn'; message: string }
+export interface ProbeResult {
+  name: string;
+  target: string;
+  viewport: { width: number; height: number };
+  steps: Array<{
+    action: 'click' | 'fill' | 'press';
+    selector?: string;
+    key?: string;
+    ok: boolean;
+    expectations: Array<{ type: Expectation['type']; selector?: string; name?: string; value?: string; ok: boolean }>;
+  }>;
+  warnings: ProbeWarning[];
+  tabOrder?: string[];
+}
+
+const PRESS_KEYS = new Set([
+  'Tab', 'Shift+Tab', 'Enter', 'Space', 'Escape',
+  'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown',
+]);
+const CREDENTIAL_SELECTOR = /password|token|secret|credential|auth/i;
+
+function localUrl(target: string): string {
+  if (!/^https?:\/\//.test(target)) {
+    const path = resolve(target);
+    if (!existsSync(path)) throw new Error(`no such page: ${target}`);
+    return pathToFileURL(path).href;
+  }
+  const url = new URL(target);
+  if (!['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) throw new Error('probe refuses remote targets');
+  if (url.username || url.password) throw new Error('probe refuses authenticated targets');
+  return url.href;
+}
+
+export function validateProbePlan(input: unknown): ProbePlan {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('probe plan requires name, destructive:false, and steps[]');
+  }
+  const raw = input as Record<string, unknown>;
+  if (typeof raw['name'] !== 'string' || !raw['name'].trim() || raw['destructive'] !== false || !Array.isArray(raw['steps'])) {
+    throw new Error('probe plan requires name, destructive:false, and steps[]');
+  }
+  const planKeys = new Set(['name', 'destructive', 'expectedTabOrder', 'steps']);
+  if (Object.keys(raw).some((key) => !planKeys.has(key))) {
+    throw new Error('probe refuses authenticated plans');
+  }
+  const tabOrder = raw['expectedTabOrder'];
+  if (tabOrder !== undefined && (!Array.isArray(tabOrder) || tabOrder.some((s) => typeof s !== 'string' || !s.trim()))) {
+    throw new Error('expectedTabOrder must contain selectors');
+  }
+  for (const value of raw['steps']) {
+    const step = value as Record<string, unknown>;
+    if (!step || typeof step !== 'object' || Object.keys(step).some((key) => !['action', 'selector', 'value', 'key', 'expect'].includes(key))) {
+      throw new Error('probe step contains unsupported or authenticated fields');
+    }
+    const action = step['action'];
+    if (typeof action !== 'string' || !['click', 'fill', 'press'].includes(action)) throw new Error(`unsafe probe action: ${String(action)}`);
+    const selector = step['selector'];
+    if (action !== 'press' && (typeof selector !== 'string' || !selector.trim())) throw new Error(`${action} requires selector`);
+    if (selector !== undefined && (typeof selector !== 'string' || !selector.trim())) throw new Error('probe selector must be non-empty');
+    if (action === 'click' && (step['value'] !== undefined || step['key'] !== undefined)) throw new Error('click contains unsupported fields');
+    if (action === 'fill') {
+      if (typeof step['value'] !== 'string' || !step['value'] || CREDENTIAL_SELECTOR.test(String(selector))) {
+        throw new Error('probe refuses credential or empty fills');
+      }
+      if (step['key'] !== undefined) throw new Error('fill contains unsupported fields');
+    }
+    if (action === 'press') {
+      if (typeof step['key'] !== 'string' || !PRESS_KEYS.has(step['key'])) throw new Error('press key is not in the safe navigation/activation allowlist');
+      if (step['value'] !== undefined) throw new Error('press contains unsupported fields');
+    }
+    const expects = step['expect'];
+    if (!Array.isArray(expects) || expects.length === 0) throw new Error('every probe action requires at least one declared expectation');
+    for (const value of expects) {
+      if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('unsupported probe expectation');
+      const exp = value as Record<string, unknown>;
+      const type = exp['type'];
+      if (typeof type !== 'string' || !['visible', 'hidden', 'text', 'url', 'attribute'].includes(type)) {
+        throw new Error('unsupported probe expectation');
+      }
+      const allowed = type === 'url' ? ['type', 'value']
+        : type === 'attribute' ? ['type', 'selector', 'name', 'value']
+          : type === 'text' ? ['type', 'selector', 'value'] : ['type', 'selector'];
+      if (Object.keys(exp).some((key) => !allowed.includes(key))) throw new Error('invalid probe expectation fields');
+      if (type !== 'url' && (typeof exp['selector'] !== 'string' || !exp['selector'].trim())) throw new Error('expectation requires selector');
+      if (['text', 'url', 'attribute'].includes(type) && (typeof exp['value'] !== 'string' || (type !== 'attribute' && !exp['value']))) throw new Error('expectation requires value');
+      if (type === 'attribute' && (typeof exp['name'] !== 'string' || !exp['name'].trim())) throw new Error('attribute expectation requires name');
+    }
+  }
+  return input as ProbePlan;
+}
+
+export function readProbePlan(path: string): ProbePlan {
+  return validateProbePlan(JSON.parse(readFileSync(path, 'utf8')) as unknown);
+}
+
+async function checkExpectation(page: import('playwright').Page, exp: Expectation): Promise<boolean> {
+  if (exp.type === 'url') return page.url().includes(exp.value);
+  const el = page.locator(exp.selector).first();
+  if (exp.type === 'visible') return el.isVisible().catch(() => false);
+  if (exp.type === 'hidden') return el.isHidden().catch(() => false);
+  if (exp.type === 'text') return (await el.textContent().catch(() => null))?.includes(exp.value) ?? false;
+  if (exp.type === 'attribute') {
+    const actual = exp.name === 'value'
+      ? await el.inputValue().catch(() => null)
+      : await el.getAttribute(exp.name).catch(() => null);
+    return actual === exp.value;
+  }
+  return false;
+}
+
+export async function runProbe(target: string, plan: ProbePlan, viewport = { width: 390, height: 844 }): Promise<ProbeResult> {
+  const validated = validateProbePlan(plan);
+  const url = localUrl(target);
+  const { chromium } = await import('playwright');
+  // Always headless — OMD never opens a visible browser window in any situation.
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const page = await browser.newPage({ viewport });
+    await page.goto(url, { waitUntil: 'networkidle' });
+    const result: ProbeResult = { name: validated.name, target: url, viewport: { ...viewport }, steps: [], warnings: [] };
+
+    if (validated.expectedTabOrder) {
+      const actual: string[] = [];
+      const matches: boolean[] = [];
+      await page.evaluate(() => (document.activeElement as HTMLElement | null)?.blur());
+      for (let i = 0; i < validated.expectedTabOrder.length; i += 1) {
+        await page.keyboard.press('Tab');
+        const observed = await page.evaluate((expected) => {
+          const el = document.activeElement as HTMLElement | null;
+          const label = el?.id ? `#${el.id}` : el?.getAttribute('data-testid') ? `[data-testid="${el.getAttribute('data-testid')}"]` : el?.tagName.toLowerCase() ?? '';
+          return { label, matches: el?.matches(expected) ?? false };
+        }, validated.expectedTabOrder[i]!);
+        actual.push(observed.label);
+        matches.push(observed.matches);
+      }
+      result.tabOrder = actual;
+      if (matches.some((match) => !match)) {
+        result.warnings.push({ id: 'PROBE-TAB-DISORDER', severity: 'warn', message: `expected ${validated.expectedTabOrder.join(' -> ')}, got ${actual.join(' -> ')}` });
+      }
+    }
+
+    for (const step of validated.steps) {
+      let actionOk = true;
+      try {
+        if (step.action === 'click') await page.locator(step.selector!).click();
+        else if (step.action === 'fill') await page.locator(step.selector!).fill(step.value!);
+        else if (step.selector) await page.locator(step.selector).press(step.key!);
+        else await page.keyboard.press(step.key!);
+      } catch { actionOk = false; }
+      const expectations: ProbeResult['steps'][number]['expectations'] = [];
+      for (const exp of step.expect ?? []) {
+        expectations.push({ ...exp, ok: await checkExpectation(page, exp) });
+      }
+      result.steps.push({ action: step.action, ...(step.selector ? { selector: step.selector } : {}), ...(step.key ? { key: step.key } : {}), ok: actionOk, expectations });
+      if (step.expect?.length && (!actionOk || expectations.some((expectation) => !expectation.ok))) {
+        result.warnings.push({ id: 'PROBE-DEAD-CONTROL', severity: 'warn', message: `${step.action} failed a declared expectation` });
+      }
+    }
+    return result;
+  } finally {
+    await browser.close();
+  }
+}
+
+export function writeProbeResult(path: string, result: ProbeResult): string {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(result, null, 2)}\n`);
+  return path;
+}

package/core/probe/schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "OMD safe probe plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "destructive", "steps"],
+  "properties": {
+    "name": { "type": "string", "minLength": 1 },
+    "destructive": { "const": false },
+    "expectedTabOrder": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["action"],
+        "properties": {
+          "action": { "enum": ["click", "fill", "press"] },
+          "selector": { "type": "string", "minLength": 1 },
+          "value": { "type": "string" },
+          "key": {
+            "enum": ["Tab", "Shift+Tab", "Enter", "Space", "Escape", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown"]
+          },
+          "expect": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["type"],
+              "properties": {
+                "type": { "enum": ["visible", "hidden", "text", "url", "attribute"] },
+                "selector": { "type": "string", "minLength": 1 },
+                "value": { "type": "string" },
+                "name": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/core/protocol/composition-contract.md

@@ -0,0 +1,192 @@
+# Composition contract protocol
+
+`.omd/composition.md` is the durable bridge between research and isolated structural
+sketches. `omd-composer` owns it. The artifact records composition decisions; it does not
+copy a reference page or prescribe one visual answer.
+
+The composer receives a sanitized frame/concept, clean copy deck, sanitized approved type
+contract, and the scout's distilled transferable principles/invariants with source trust.
+It does not receive or reproduce screenshots, assets, pixels, literal tokens, copied text,
+full-page descriptions, or a source page's complete sequence. Read `theory/layout.md` and
+`theory/ux.md` exactly before writing.
+
+Use these H2 sections exactly and keep each non-empty. When the project has user-provided
+references (`omd ref add --from-user`), the additional `## Reference synthesis` section is
+required as well; `omd composition --check` enforces it.
+
+Before writing any section, read the frame's `uxSurface` classification. It selects the
+grammar (see `theory/ux.md` §Surface types): a `marketing` surface composes as a message
+ladder; a `product` work surface composes as a task loop over screen regions; `editorial`
+composes as a reading sequence; `mixed` names which screens follow which grammar. The
+section names below stay the same across grammars — what changes is what a "section" is:
+on a product surface it is a screen region or reachable state with a job in the task
+loop, not a scroll chapter.
+
+## Input fingerprint
+
+Record exactly one line for each input:
+
+```text
+- Frame SHA-256: <64 lowercase hex>
+- Copy deck SHA-256: <64 lowercase hex>
+- Type proof SHA-256: <64 lowercase hex>
+- Scout SHA-256: <64 lowercase hex>
+```
+
+Hashes cover `.omd/frame.md`, `.omd/copy-deck.md`, `.omd/type-proof.md`, and
+`.omd/scout.md`. When `.omd/scout.md` does not exist, the scout line is instead
+`- Scout SHA-256: N/A — <specific reason>`. Never invent a scout hash. Any frame, copy,
+type-proof, or scout-summary change invalidates the contract; rerun composer and the check.
+
+## Experience spine
+
+For a `marketing` or `editorial` surface: for every section, record the entering user
+question, exactly what new answer/evidence this section adds, its primary action, and why
+the next section depends on it. This is a message ladder, not a list of fashionable
+section names.
+
+For a `product` surface: write the spine as the task loop — orient → locate → act →
+feedback → next/recover. For every screen region (shell/navigation, work object, supporting
+panels, state surfaces), record which loop step it serves, the frequent action it carries,
+and why the region's position follows task order. Include the reachable states (loading,
+empty first-run, filtered-to-zero, error/recovery, success) as spine entries with their
+copy source; a work surface without designed states has an incomplete spine. Do not write
+a persuasion ladder for a tool: a hero section above a queue is a grammar defect, not a
+style choice.
+
+## Section dependency
+
+Run the reorder/removal test. If adjacent sections can swap or disappear without weakening
+meaning, revise their dependency or record the evidence-backed reason independence is useful.
+
+## Grid and alignment
+
+Define the shared alignment/grid skeleton and the limited, intentional breaks that express
+meaning. Do not choose a break because a reference used it.
+
+## Density and visual mass
+
+Describe how density, visual mass, and negative space progress across the whole experience.
+Relate every change to attention, evidence, action, or recovery.
+
+## Focal hierarchy
+
+Define one dominant anchor in the first viewport and its visual-mass budget relative to the
+value statement, proof, and visible primary CTA. On a `product` surface the dominant anchor
+is the work object itself — the table, queue, canvas, form, or data view the task loop
+operates on, at representative data density — and the "value statement" is at most one line
+of orientation; a display-scale headline or decorative hero claiming the first viewport of
+a work surface is a rejection condition, not an anchor. The CTA plus a predictable completion path
+satisfies task reach; the terminal form or control surface does not have to appear in the
+first viewport and earns no credit merely for being visible there. State a visible rejection
+condition for a candidate whose anchor loses dominance, crowds the task cue, or becomes
+detached from the concept.
+
+The anchor may be lawful product/evidence media, an explanatory graphic, real interaction or
+data, or concept-bearing typography. A photo is never mandatory. Do not invent product facts,
+assets, or evidence to manufacture an anchor.
+
+## Domain form grammar
+
+Derive recurring relational properties from the product's mechanism, material, or workflow.
+Assign them to functional UI roles and state their limits. A metaphor that becomes decorative
+shape instead of useful relationship fails this section.
+
+## Media roles
+
+For each section, assign media one job: evidence, explanation, orientation, or action. When
+the domain mechanism, material, or workflow is central, assign a lawful carrier for it or
+name an explicit alternate non-media mental-model carrier and its limitation. `none because
+no approved photo` is insufficient: a photo is not required, and absent assets do not excuse
+an absent mental model. Do not invent product facts/assets or weaken the clean-room transfer
+boundary.
+
+## Responsive recomposition
+
+Use a desktop/mobile table. Preserve semantic DOM and focus order, the anchor's morphology
+and relationship to value/proof/CTA, and an uninterrupted primary-task cue and completion
+path while explaining how each relationship reframes. Do not write only `stack` or `hide`.
+The full form need not occupy the first viewport. Account for reflow at 320 CSS px, while
+production evidence still renders 1280x900 and 390x844.
+
+## Candidate axes
+
+Define at least two genuinely different structural axes that can satisfy the same spine,
+copy, type, and acceptance criteria. Axes vary spatial relationships, not content truth.
+
+## Transfer boundary
+
+Permitted transfer: attributed relationships, measured invariants, and principles abstracted
+from trusted evidence. Forbidden transfer: source identity in shipped UI, copy, assets,
+literal tokens, full section order, pixels, recognizable silhouette, or unique interaction
+and motion. An exact transplant is allowed only when the user explicitly requested that
+specific transplant; record the request and attribution.
+
+## Reference synthesis
+
+Required when user-origin references exist, and structurally validated whenever it is non-empty.
+`omd composition --check` parses this section as a closed Markdown ABI: prose, headings,
+fields, or axis rows outside the forms below are rejected.
+
+An adopted transfer is one `### Feature: <specific feature>` record:
+
+```md
+### Feature: Inbox triage workspace
+- Origin: explicit
+- Assumption: N/A
+- Primitive: Triage and inspect a queue item
+- Source ref: ref-<first 16 lowercase hex of SHA-256(source + NUL + component)>
+- Trust: Directly observed stable reference
+- Uncertainty: Content changes may alter exact density.
+- Structural rule: Queue and detail panels remain visible together.
+- Adaptation: Fit that relationship to the current task flow.
+- Token variation: Use destination tokens, not source values.
+- Conflict resolution: Task, accessibility, mobile, then one destination system win.
+- Destination route: /inbox
+- Destination selector: [data-region="inbox"]
+- Mobile behavior: Recompose into a focused drill-in flow.
+#### Axes
+- Information architecture/navigation | adapt | Queue navigation exposes current work. | Fit it to destination routes.
+- Macro layout and panel/region geometry | adapt | Queue and detail remain paired. | Preserve the relationship at the work surface.
+- Content density | N/A | N/A | The source has no usable density evidence.
+- Typography/hierarchy | N/A | N/A | The source has no usable type evidence.
+- Spacing/rhythm | N/A | N/A | The source has no usable rhythm evidence.
+- Component anatomy | N/A | N/A | The source has no reusable anatomy evidence.
+- Interaction/state/feedback | adapt | Selecting an item updates detail. | Use destination state vocabulary.
+- Responsive/mobile recomposition | adapt | Detail becomes focused on narrow screens. | Preserve return to the queue.
+- Motion/transition | N/A | N/A | The source has no transferable motion evidence.
+```
+
+Use every axis exactly once: information architecture/navigation; macro layout and panel/region
+geometry; content density; typography/hierarchy; spacing/rhythm; component anatomy;
+interaction/state/feedback; responsive/mobile recomposition; motion/transition. Disposition is
+exactly `accept`, `adapt`, `decline`, or `N/A`. Applicable axes require a substantive observed
+rule and adaptation or decline rationale. `N/A` uses `N/A` as its observed rule and a substantive
+reason. An adopted record must accept or adapt at least one structural or visual-system axis
+(the first six); interaction-only or token-only transfer is invalid.
+
+`Source ref` is the exact stable reference identity, not a hostname or prose mention. For a stored
+user reference it is `ref-` plus the first 16 lowercase hexadecimal characters of
+`SHA-256(source + NUL + component)`. This preserves two user references from the same host as
+separate obligations. The checker compares normalized `Source ref` field values only; text
+elsewhere in the section never satisfies reference coverage. A scout-origin reference instead
+uses an uppercase hyphenated key matching `[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+`; hostnames and
+free-form prose are invalid identities. Feature labels may be short when
+specific; explanatory fields need substantive content. Destination routes must be non-placeholder
+local routes beginning with `/` (including `/` itself). Destination selectors must be unique after
+whitespace normalization and use only a stable `[data-*="…"]` selector or an accessible semantic
+element/role selector.
+
+A whole explicit feature may instead be declined without pretending it is an adopted transfer:
+
+```md
+### Decline: Document density
+- Origin: explicit
+- Source ref: ref-<first 16 lowercase hex of SHA-256(source + NUL + component)>
+- Trust: User supplied reference
+- Uncertainty: Scope is limited to the supplied page.
+- Reason: Document density conflicts with rapid queue scanning.
+```
+
+`omd composition --check` validates this ABI, section structure, fingerprint format, freshness,
+and every user-reference mention. It does not score taste or aesthetics.