@3xhaust/oh-my-design 0.16.1

package/core/composition/sticky-sidebar-scroll.md

@@ -0,0 +1,219 @@
+# Sticky sidebar + scrolling content
+
+> Candidate hypothesis only. Revalidate its condition, values, and responsive transition
+> against the current composition contract; do not transfer this page recipe unchanged.
+
+A sticky sidebar remains anchored in view while the main content column scrolls past it.
+The sidebar holds content that gains from staying visible — navigation, a table of contents,
+a reference panel, a summary of options while the user reads detail. The main column holds
+the content that changes as the user scrolls. The spatial relationship between fixed and
+moving creates a reading contract: one side is the reference, the other is the subject.
+
+## When it earns its place / When it does not
+
+Condition: the sidebar content is actively useful while the main content is being read —
+not just available, but genuinely better visible than hidden. A table of contents that
+tracks the user's position, a filter panel that contextualises the results column, a
+product summary that stays visible while the user reads the long-form description, a
+step indicator during a multi-section form. The user benefits from the concurrent
+visibility; removing the sticky behaviour would require scrolling back to reorient.
+
+`core/theory/layout.md` on scan patterns: "primary navigation and key actions belong
+on the left or in the top bar" — the F-pattern's left-edge scan aligns with a left
+sidebar that provides structural context. A sticky sidebar on the right works only
+when the content scan pattern is already bidirectional (documentation-style reference
+pages where the user moves between code and explanation).
+
+Condition against: mobile viewports where the sidebar consumes horizontal real estate
+the main column cannot afford. Any sidebar whose content is not actively consulted while
+the main column is being read — if the user reads the main column without ever glancing
+at the sidebar, the sticky position is costing a column of space for no return. Short
+pages where the sidebar reaches the end of the page before the scroll distance is
+meaningful — `position: sticky` achieves nothing useful on a page under 200vh. And any
+sidebar whose content duplicates rather than contextualises the main column.
+
+## Parameters
+
+```css
+:root {
+  /* Sidebar width.
+     Fixed sidebar: typically 240–320px.
+     Proportional sidebar: 22–28% of the container — use when the content column
+     should reflow proportionally with viewport width. */
+  --sidebar-width: clamp(200px, 22%, 300px);
+
+  /* The top offset at which the sidebar sticks.
+     Match this to the height of any fixed top navigation bar.
+     If there is no fixed nav, a small offset (16–24px) prevents the sidebar
+     from jamming against the viewport top. */
+  --sidebar-sticky-top: var(--nav-height, 80px);
+
+  /* Gap between sidebar and main content column. */
+  --sidebar-gap: clamp(24px, 4vw, 48px);
+
+  /* The sidebar's maximum height before it becomes independently scrollable.
+     Set this to (100vh - var(--sidebar-sticky-top)) to allow the sidebar to
+     scroll internally if its content exceeds the viewport height. */
+  --sidebar-max-height: calc(100vh - var(--sidebar-sticky-top) - 2rem);
+}
+```
+
+## Implementation
+
+```html
+<!-- The wrapper defines the two-column layout.
+     The sidebar column holds the sticky element.
+     The main column scrolls normally. -->
+<div class="sticky-layout">
+  <aside class="sticky-layout__sidebar" aria-label="Table of contents">
+    <nav class="toc">
+      <p class="toc__heading">Contents</p>
+      <ol class="toc__list">
+        <li><a href="#section-1" class="toc__link">Discovery</a></li>
+        <li><a href="#section-2" class="toc__link">Definition</a></li>
+        <li><a href="#section-3" class="toc__link">Design</a></li>
+        <li><a href="#section-4" class="toc__link">Delivery</a></li>
+      </ol>
+    </nav>
+  </aside>
+
+  <main class="sticky-layout__main">
+    <section id="section-1">
+      <h2>Discovery</h2>
+      <!-- Long-form content that scrolls -->
+    </section>
+
+    <section id="section-2">
+      <h2>Definition</h2>
+      <!-- Long-form content that scrolls -->
+    </section>
+    <!-- ... more sections ... -->
+  </main>
+</div>
+```
+
+```css
+/* ── Two-column grid ─────────────────────────────────────────────────────── */
+.sticky-layout {
+  display: grid;
+  grid-template-columns: var(--sidebar-width) 1fr;
+  gap: var(--sidebar-gap);
+  padding-inline: var(--space-page-margin, 5vw);
+  align-items: start; /* critical: both columns align to the top; sticky works from there */
+}
+
+/* ── Sidebar: sticky within its column ───────────────────────────────────── */
+.sticky-layout__sidebar {
+  position: sticky;
+  top: var(--sidebar-sticky-top);
+  max-height: var(--sidebar-max-height);
+  overflow-y: auto; /* if sidebar content exceeds viewport height, it scrolls internally */
+  /* Subtle scrollbar styling for the sidebar when it overflows */
+  scrollbar-width: thin;
+  scrollbar-color: var(--border-subtle) transparent;
+}
+
+/* ── Main content: normal block flow ─────────────────────────────────────── */
+.sticky-layout__main {
+  min-width: 0; /* prevent grid blowout from long words or wide content */
+}
+
+.sticky-layout__main section {
+  padding-block: var(--space-section, 4rem);
+  /* A border or padding between sections helps the user perceive the scroll
+     narrative without the sidebar tracking — a visual chapter break. */
+  border-top: 1px solid var(--border-subtle, rgba(0,0,0,0.08));
+}
+
+.sticky-layout__main section:first-child {
+  border-top: none;
+  padding-top: 0;
+}
+
+/* ── Table of contents: simple, functional ─────────────────────────────── */
+.toc__heading {
+  font-size: var(--text-xs, 0.75rem);
+  font-weight: var(--weight-medium, 500);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text-secondary);
+  margin-bottom: var(--space-3, 0.75rem);
+}
+
+.toc__list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2, 0.5rem);
+}
+
+.toc__link {
+  font-size: var(--text-sm, 0.875rem);
+  color: var(--text-secondary);
+  text-decoration: none;
+  line-height: 1.4;
+  /* Active state for the current section — wired via IntersectionObserver in JS */
+}
+
+.toc__link[aria-current="true"],
+.toc__link.is-active {
+  color: var(--color-accent);
+  font-weight: var(--weight-medium, 500);
+}
+```
+
+## Responsive behavior
+
+**375px (mobile):** The sidebar cannot coexist with the main column at this width. Move
+sidebar content above the main content, or collapse it into a sticky summary bar at the
+top. Do not simply hide the sidebar — if it provides navigation, it must remain accessible.
+
+```css
+@media (max-width: 900px) {
+  .sticky-layout {
+    grid-template-columns: 1fr; /* single column */
+  }
+
+  .sticky-layout__sidebar {
+    position: static; /* remove sticky: stacks above main content */
+    max-height: none;
+    overflow-y: visible;
+    padding-bottom: var(--space-6, 1.5rem);
+    border-bottom: 1px solid var(--border-subtle);
+    margin-bottom: var(--space-6, 1.5rem);
+  }
+
+  /* Alternative: collapse to a sticky top bar on mobile.
+     Requires JavaScript to build a compact navigation from the sidebar content.
+     This pattern is documented in sticky-scene-transition.md. */
+}
+```
+
+**768px (tablet):** At 768px, `--sidebar-width: clamp(200px, 22%, 300px)` yields ~169px
+— below the 200px floor, so the floor takes effect. A 200px sidebar at 768px leaves ~520px
+for the main column, which is sufficient for body text at 50–65ch. Verify the sidebar
+content does not overflow its column at this width.
+
+**1280px (desktop):** The sidebar at `clamp(200px, 22%, 300px)` yields ~282px at 1280px.
+The main column receives ~950px minus gap and page margin. At this width consider whether
+the main column benefits from a `max-width: 72ch` constraint — a full-width main column
+at 950px produces a 120ch+ measure, which is over the research-validated readable range.
+`core/theory/layout.md` on form and text layout: 50–75ch is the validated range.
+
+## Do not combine with
+
+**editorial-index-labels.md** in the same section — both create secondary reading tracks.
+The index number (decorative, left-background) and the sidebar navigation (functional,
+left-column) compete for the same spatial zone, producing ambiguity about what the left
+side of the page means.
+
+**asymmetric-diagonal-grid.md** — the diagonal layout breaks the column contract that
+the sticky sidebar depends on. The sidebar's spatial promise (I stay while you scroll) is
+undermined when the main column is itself off-axis or overlapping the sidebar zone.
+
+**sticky-sidebar on pages under 200vh** — the sticky behaviour has no effect when the
+page is too short for meaningful scroll distance. Use a static two-column layout instead
+and reserve `position: sticky` for pages where the sidebar travels a meaningful distance
+alongside the user.

package/core/composition/typographic-hero.md

@@ -0,0 +1,100 @@
+# Typographic hero
+
+> Candidate hypothesis only. Revalidate its condition, values, and responsive transition
+> against the current composition contract; do not transfer this page recipe unchanged.
+
+A typographic hero makes a short, concept-bearing line the primary visual event. It is an
+exceptional composition, not a large-heading preset.
+Use it with the register conditions in `core/theory/expressive.md`.
+
+## When it earns its place / When it does not
+
+Use it when the actual headline is short enough to survive both target containers, the
+chosen face and weight visibly carry the concept, and the product can keep supporting
+context and the primary CTA usable. A justified huge Hangul case might use a compact
+two-to-five-word declaration whose syllable-block rhythm is itself the identity: the proof
+shows intentional wrapping, clean counters, loaded intended weights, and an immediate CTA
+at 1280x900 and 390x844.
+
+Do not use it when the headline is long, generic, or doing the work of several paragraphs.
+A giant heavy Korean sentence that wraps into a dense wall, clips at mobile, falls back to
+another face, or pushes all secondary hierarchy and action away has failed even if it looks
+dramatic in one screenshot.
+
+## Parameters
+
+The passing actual-copy specimen must supply these required custom properties:
+
+```text
+--type-proof-hero-measure
+--type-proof-hero-size
+--type-proof-hero-weight
+--type-proof-hero-leading
+--type-proof-hero-tracking
+--type-proof-hero-gap
+--type-proof-hero-padding-block
+```
+
+There are no recipe defaults. `.omd/type-proof.md` records the values produced by the
+specimen for the selected copy and container. CSS `clamp()`, container queries, media
+queries, or discrete type steps are all valid when the two rendered targets justify them.
+Letter spacing follows visible glyph anatomy; there is no universal negative limit.
+
+## Implementation
+
+Use semantic heading order and let content determine block height. Keep overflow visible
+unless a separate, evidenced visual effect owns the crop; never use clipping to hide failed
+wrapping.
+
+```css
+.hero {
+  display: grid;
+  align-content: center;
+  gap: var(--type-proof-hero-gap);
+  padding-block: var(--type-proof-hero-padding-block);
+}
+
+.hero__title {
+  max-inline-size: var(--type-proof-hero-measure);
+  margin: 0;
+  font-size: var(--type-proof-hero-size);
+  font-weight: var(--type-proof-hero-weight);
+  line-height: var(--type-proof-hero-leading);
+  letter-spacing: var(--type-proof-hero-tracking);
+  text-wrap: balance;
+  overflow: visible;
+}
+```
+
+The secondary line and primary action remain in the same reading sequence. If display type
+makes either unavailable without scrolling in the target task, reduce or restructure it.
+
+## Proof requirements
+
+Before structure, render the real headline, secondary copy, CTA, mixed Korean/Latin/numerals,
+and fallback state at 1280x900 and 390x844. Record requested and computed family/weight,
+FontFace loading status, line count, wrap points, clipping, orphan behavior, and rejected
+alternatives in `.omd/type-proof.md`.
+
+After selecting the production structure, repeat the proof in the real hero container.
+Copy, face/file, weight/axis, or container-width changes invalidate the earlier proof.
+Browser evidence does not identify the physical font used for each glyph.
+
+## Responsive behavior
+
+The required evidence is the actual-copy specimen at 390x844 and 1280x900, not a fixed
+scaling formula. At each viewport record the selected container, line count, wrap points,
+clipping, fallback behavior, and the location of secondary copy and CTA. Tablet behavior
+may interpolate or use a discrete step, but it must preserve the same reading order.
+
+## Do not combine with
+
+Avoid another dominant text event in the same opening view, such as an automatic marquee or
+equally forceful split-text entrance. One technique owns the memorable moment. Motion, if
+used, follows the motion specification and preserves the proof-clean final state.
+
+## Linter notes
+
+There is no safe huge-type threshold. Moderate type can be expressive; very large type can
+be correct. Deterministic checks may catch clipping or accessibility defects, while the
+typography proof judges concept, glyphs, loading, wrapping, and hierarchy.

package/core/composition-contract/index.ts

@@ -0,0 +1,233 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadRefs } from '../ref/store.ts';
+
+export const COMPOSITION_SECTIONS = [
+  'Input fingerprint', 'Experience spine', 'Section dependency', 'Grid and alignment',
+  'Density and visual mass', 'Focal hierarchy', 'Domain form grammar', 'Media roles',
+  'Responsive recomposition', 'Candidate axes', 'Transfer boundary',
+] as const;
+
+// Allowed-but-optional H2 headings whose row/field schema is owned by another canonical
+// validator (task evidence owns `## UX task coverage`). The composition contract only
+// recognizes the heading so it can be authored as normal LF Markdown; it never restates
+// or revalidates that section's internal schema.
+export const AUXILIARY_SECTIONS = ['UX task coverage'] as const;
+
+export interface CompositionContractFinding {
+  id: 'COMPOSITION-MISSING' | 'COMPOSITION-SECTION' | 'COMPOSITION-HASH' | 'COMPOSITION-STALE' | 'COMPOSITION-SCOUT' | 'COMPOSITION-SYNTHESIS';
+  path: string;
+  message: string;
+}
+
+export const SYNTHESIS_SECTION = 'Reference synthesis';
+export const SYNTHESIS_AXES = [
+  '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',
+] as const;
+
+const structuralAxes = new Set(SYNTHESIS_AXES.slice(0, 6));
+const synthesisPath = `.omd/composition.md#${SYNTHESIS_SECTION}`;
+const synthesisFinding = (message: string): CompositionContractFinding => ({ id: 'COMPOSITION-SYNTHESIS', path: synthesisPath, message });
+const sectionFinding = (section: string, message: string): CompositionContractFinding => ({ id: 'COMPOSITION-SECTION', path: `.omd/composition.md#${section}`, message });
+const normalize = (value: string): string => value.trim().replace(/\s+/g, ' ').toLowerCase();
+const isPlaceholder = (value: string): boolean => /^(?:n\/?a|none|unknown|unspecified|tbd|todo|placeholder|example)(?:\s|$)/i.test(value.trim());
+const substantive = (value: string): boolean => value.trim().length >= 8 && !isPlaceholder(value);
+const recordName = (kind: string, feature: string): string => `${kind} "${feature}"`;
+
+interface ParsedSections { sections: Map<string, string[]>; findings: CompositionContractFinding[]; }
+function parseSections(markdown: string): ParsedSections {
+  const sections = new Map<string, string[]>();
+  const findings: CompositionContractFinding[] = [];
+  const separator = /[\u2028\u2029\u0085\u000B\u000C]/.exec(markdown);
+  if (separator) findings.push(sectionFinding('document', `composition must not contain a Unicode line or paragraph separator (found U+${separator[0]!.codePointAt(0)!.toString(16).toUpperCase().padStart(4, '0')}); author headings with normal LF line breaks`));
+  let current: string | undefined;
+  for (const line of markdown.split(/\r?\n/)) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line);
+    if (heading) {
+      const name = heading[1]!;
+      if (![...COMPOSITION_SECTIONS, SYNTHESIS_SECTION, ...AUXILIARY_SECTIONS].includes(name as never)) findings.push(sectionFinding(name, `unknown H2 section: ${name}`));
+      else if (sections.has(name)) findings.push(sectionFinding(name, `duplicate H2 section: ${name}`));
+      else sections.set(name, []);
+      current = name;
+    } else if (current === undefined) {
+      if (line.trim() !== '') findings.push(sectionFinding('document', 'content must appear inside an allowed H2 section'));
+    } else {
+      sections.get(current)?.push(line);
+    }
+  }
+  return { sections, findings };
+}
+
+function validateFingerprint(lines: string[], inputs: CompositionContractInputs): CompositionContractFinding[] {
+  const findings: CompositionContractFinding[] = [];
+  const values = new Map<string, string>();
+  for (const line of lines) {
+    if (line.trim() === '') continue;
+    const match = /^- (Frame SHA-256|Copy deck SHA-256|Type proof SHA-256|Scout SHA-256): (.+)$/.exec(line);
+    if (!match) { findings.push({ id: 'COMPOSITION-HASH', path: '.omd/composition.md#Input fingerprint', message: 'Input fingerprint contains an unknown or malformed line' }); continue; }
+    const key = match[1]!;
+    if (values.has(key)) findings.push({ id: 'COMPOSITION-HASH', path: '.omd/composition.md#Input fingerprint', message: `${key} must appear exactly once` });
+    else values.set(key, match[2]!);
+  }
+  const required: Array<[string, string, string | undefined]> = [
+    ['Frame', 'frame.md', inputs.frame], ['Copy deck', 'copy-deck.md', inputs.copyDeck], ['Type proof', 'type-proof.md', inputs.typeProof],
+  ];
+  for (const [label, filename, actual] of required) {
+    const value = values.get(`${label} SHA-256`);
+    if (!value || !/^[0-9a-f]{64}$/.test(value)) findings.push({ id: 'COMPOSITION-HASH', path: '.omd/composition.md#Input fingerprint', message: `${label} SHA-256 must be exactly 64 lowercase hex characters` });
+    else if (actual === undefined) findings.push({ id: 'COMPOSITION-STALE', path: `.omd/${filename}`, message: `${filename} is missing; composition cannot be current` });
+    else if (value !== actual) findings.push({ id: 'COMPOSITION-STALE', path: `.omd/${filename}`, message: `${filename} changed after composition was written` });
+  }
+  const scout = values.get('Scout SHA-256');
+  if (inputs.scout !== undefined) {
+    if (!scout || !/^[0-9a-f]{64}$/.test(scout)) findings.push({ id: 'COMPOSITION-SCOUT', path: '.omd/composition.md#Input fingerprint', message: 'Scout SHA-256 must be a 64-hex hash while .omd/scout.md exists' });
+    else if (scout !== inputs.scout) findings.push({ id: 'COMPOSITION-STALE', path: '.omd/scout.md', message: 'scout.md changed after composition was written' });
+  } else if (!scout || !/^N\/A — \S.*$/.test(scout)) {
+    findings.push({ id: 'COMPOSITION-SCOUT', path: '.omd/composition.md#Input fingerprint', message: 'absent scout.md requires `N/A — <reason>` instead of a hash or empty value' });
+  }
+  return findings;
+}
+
+const featureFields = ['Origin', 'Assumption', 'Primitive', 'Source ref', 'Trust', 'Uncertainty', 'Structural rule', 'Adaptation', 'Token variation', 'Conflict resolution', 'Destination route', 'Destination selector', 'Mobile behavior'] as const;
+const declineFields = ['Origin', 'Source ref', 'Trust', 'Uncertainty', 'Reason'] as const;
+interface SynthesisResult { findings: CompositionContractFinding[]; sourceRefs: string[]; }
+
+function validRoute(value: string): boolean {
+  if (value === '/') return true;
+  if (!/^\/[A-Za-z0-9._~!$&'()*+,;=:@\/-]*$/.test(value) || value.startsWith('//')) return false;
+  const segments = value.slice(1).split('/');
+  return segments.every((segment) => segment !== '.' && segment !== '..') && !isPlaceholder(segments[0] ?? '');
+}
+function normalizedSelector(value: string): string | undefined {
+  const selector = value.trim().replace(/\s+/g, ' ');
+  if (/^\[data-[a-z][a-z0-9-]*=(?:"[^"]+"|'[^']+')\]$/.test(selector)) return selector;
+  if (/^(?:main|nav|header|footer|aside|form|table|dialog|button|input|select|textarea)(?:\[aria-(?:label|labelledby)=(?:"[^"]+"|'[^']+')\])?$/.test(selector)) return selector;
+  if (/^\[role=(?:"(?:main|navigation|dialog|search|form|region)"|'(?:main|navigation|dialog|search|form|region)')\]$/.test(selector)) return selector;
+  return undefined;
+}
+
+function validateReferenceSynthesis(lines: string[]): SynthesisResult {
+  const findings: CompositionContractFinding[] = [];
+  const sourceRefs: string[] = [];
+  const records: Array<{ kind: 'Feature' | 'Decline'; feature: string; lines: string[] }> = [];
+  let current: { kind: 'Feature' | 'Decline'; feature: string; lines: string[] } | undefined;
+  for (const line of lines) {
+    if (line.trim() === '') continue;
+    const heading = /^### (Feature|Decline):\s*(.*?)\s*$/.exec(line);
+    if (heading) { current = { kind: heading[1]! as 'Feature' | 'Decline', feature: heading[2]!, lines: [] }; records.push(current); }
+    else if (!current) findings.push(synthesisFinding('Reference synthesis may contain only Feature or Decline records'));
+    else current.lines.push(line);
+  }
+  if (records.length === 0) findings.push(synthesisFinding('non-empty Reference synthesis must use ### Feature: or ### Decline: records'));
+  const selectors = new Set<string>();
+  for (const record of records) {
+    const identity = recordName(record.kind, record.feature);
+    if (!record.feature.trim() || isPlaceholder(record.feature)) findings.push(synthesisFinding(`${identity}: feature label is missing or a placeholder`));
+    const fields = new Map<string, string>();
+    const axes: string[][] = [];
+    const expected = record.kind === 'Feature' ? featureFields : declineFields;
+    let nextField = 0;
+    let axisMode = false;
+    for (const line of record.lines) {
+      if (line === '#### Axes' && record.kind === 'Feature' && !axisMode) {
+        if (nextField !== expected.length) findings.push(synthesisFinding(`${identity}: Axes block is misplaced before required fields`));
+        axisMode = true;
+        continue;
+      }
+      if (axisMode) {
+        const columns = line.startsWith('- ') ? line.slice(2).split(' | ') : [];
+        if (columns.length !== 4) findings.push(synthesisFinding(`${identity}: malformed or stray content in Axes block`));
+        else axes.push(columns);
+        continue;
+      }
+      const field = /^- ([A-Za-z][A-Za-z ]*): (.*)$/.exec(line);
+      if (!field) { findings.push(synthesisFinding(`${identity}: malformed or stray record content`)); continue; }
+      const name = field[1]!;
+      if (!expected.includes(name as never)) { findings.push(synthesisFinding(`${identity}: unknown or misplaced field "${name}"`)); continue; }
+      if (fields.has(name)) findings.push(synthesisFinding(`${identity}: ${name} must appear exactly once`));
+      else {
+        if (expected[nextField] !== name) findings.push(synthesisFinding(`${identity}: field "${name}" is misplaced`));
+        else nextField++;
+        fields.set(name, field[2]!);
+      }
+    }
+    for (const name of expected) if (!fields.has(name) || !fields.get(name)!.trim()) findings.push(synthesisFinding(`${identity}: ${name} must appear exactly once with a non-empty value`));
+    const origin = fields.get('Origin');
+    const source = fields.get('Source ref');
+    if (source && !/^(?:ref-[0-9a-f]{16}|[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+)$/.test(source)) findings.push(synthesisFinding(`${identity}: Source ref must be a stable ref identity or scout key`));
+    else if (source) sourceRefs.push(normalize(source));
+    for (const name of ['Trust', 'Uncertainty'] as const) if (fields.has(name) && !substantive(fields.get(name)!)) findings.push(synthesisFinding(`${identity}: ${name} must be substantive`));
+    if (record.kind === 'Decline') {
+      if (origin !== 'explicit') findings.push(synthesisFinding(`${identity}: a Decline record must use Origin: explicit`));
+      if (fields.has('Reason') && !substantive(fields.get('Reason')!)) findings.push(synthesisFinding(`${identity}: Decline Reason must be substantive`));
+      continue;
+    }
+    if (origin !== 'explicit' && origin !== 'inferred') findings.push(synthesisFinding(`${identity}: Origin must be exactly explicit or inferred`));
+    const assumption = fields.get('Assumption');
+    if (origin === 'explicit' && assumption !== 'N/A') findings.push(synthesisFinding(`${identity}: explicit Origin requires Assumption: N/A`));
+    if (origin === 'inferred' && (!assumption || !substantive(assumption))) findings.push(synthesisFinding(`${identity}: inferred Origin requires a substantive Assumption`));
+    for (const name of ['Primitive', 'Structural rule', 'Adaptation', 'Token variation', 'Conflict resolution', 'Mobile behavior'] as const) if (fields.has(name) && !substantive(fields.get(name)!)) findings.push(synthesisFinding(`${identity}: ${name} must be substantive`));
+    const route = fields.get('Destination route');
+    if (route && !validRoute(route)) findings.push(synthesisFinding(`${identity}: Destination route must be a non-placeholder local route beginning with /`));
+    const selector = fields.get('Destination selector');
+    if (selector) {
+      const normalized = normalizedSelector(selector);
+      if (!normalized) findings.push(synthesisFinding(`${identity}: Destination selector must be a stable data-* or accessible semantic selector`));
+      else if (selectors.has(normalized)) findings.push(synthesisFinding(`${identity}: Destination selector "${normalized}" is duplicated`));
+      else selectors.add(normalized);
+    }
+    if (!axisMode) findings.push(synthesisFinding(`${identity}: every adopted record must contain a #### Axes block`));
+    const seen = new Set<string>();
+    for (const [axis = '', disposition = '', observed = '', adaptation = ''] of axes) {
+      if (!SYNTHESIS_AXES.includes(axis as typeof SYNTHESIS_AXES[number])) { findings.push(synthesisFinding(`${identity}: unknown axis "${axis}"`)); continue; }
+      if (seen.has(axis)) findings.push(synthesisFinding(`${identity}: axis "${axis}" must appear exactly once`));
+      seen.add(axis);
+      if (!['accept', 'adapt', 'decline', 'N/A'].includes(disposition)) findings.push(synthesisFinding(`${identity}: axis "${axis}" has invalid disposition`));
+      else if (disposition === 'N/A' ? observed !== 'N/A' || !substantive(adaptation) : !substantive(observed) || !substantive(adaptation)) findings.push(synthesisFinding(`${identity}: axis "${axis}" requires a substantive ${disposition === 'N/A' ? 'N/A reason' : 'observed rule and adaptation or decline rationale'}`));
+    }
+    for (const axis of SYNTHESIS_AXES) if (!seen.has(axis)) findings.push(synthesisFinding(`${identity}: axis "${axis}" must appear exactly once`));
+    if (!axes.some(([axis, disposition]) => structuralAxes.has(axis as typeof SYNTHESIS_AXES[number]) && (disposition === 'accept' || disposition === 'adapt'))) findings.push(synthesisFinding(`${identity}: adopted records cannot be interaction-only or token-only`));
+  }
+  return { findings, sourceRefs };
+}
+
+function sha256(path: string): string { return createHash('sha256').update(readFileSync(path)).digest('hex'); }
+
+export interface CompositionContractInputs {
+  contract?: string; frame?: string; copyDeck?: string; typeProof?: string; scout?: string;
+  /** Exact normalized Source ref identities for user-origin refs, not host labels. */
+  userRefLabels?: string[];
+}
+
+export function validateCompositionContractSource(inputs: CompositionContractInputs): CompositionContractFinding[] {
+  if (inputs.contract === undefined) return [{ id: 'COMPOSITION-MISSING', path: '.omd/composition.md', message: 'composition contract is missing' }];
+  const parsed = parseSections(inputs.contract);
+  const findings = [...parsed.findings];
+  for (const section of COMPOSITION_SECTIONS) if (!parsed.sections.get(section)?.join('\n').trim()) findings.push(sectionFinding(section, `required section is missing or empty: ${section}`));
+  findings.push(...validateFingerprint(parsed.sections.get('Input fingerprint') ?? [], inputs));
+  const synthesisLines = parsed.sections.get(SYNTHESIS_SECTION);
+  const synthesis = synthesisLines?.join('\n').trim() ?? '';
+  const result = synthesis ? validateReferenceSynthesis(synthesisLines!) : { findings: [], sourceRefs: [] };
+  findings.push(...result.findings);
+  const userRefs = inputs.userRefLabels ?? [];
+  if (userRefs.length > 0 && !synthesis) findings.push(synthesisFinding(`user-provided references exist but the ${SYNTHESIS_SECTION} section is missing or empty`));
+  else for (const ref of userRefs) if (!result.sourceRefs.includes(normalize(ref))) findings.push(synthesisFinding(`user reference "${ref}" is not mapped by an exact Source ref field in ${SYNTHESIS_SECTION}`));
+  return findings.sort((a, b) => a.path.localeCompare(b.path) || a.id.localeCompare(b.id) || a.message.localeCompare(b.message));
+}
+
+/** Stable authoring identity: deterministic, safe, and distinct for same-host references. */
+function refIdentity(source: string, component: string): string {
+  return `ref-${createHash('sha256').update(`${source}\0${component}`).digest('hex').slice(0, 16)}`;
+}
+
+export function validateCompositionContract(root: string): CompositionContractFinding[] {
+  const omd = join(root, '.omd');
+  const readHash = (filename: string): string | undefined => { const path = join(omd, filename); return existsSync(path) ? sha256(path) : undefined; };
+  const contractPath = join(omd, 'composition.md');
+  const frame = readHash('frame.md'); const copyDeck = readHash('copy-deck.md'); const typeProof = readHash('type-proof.md'); const scout = readHash('scout.md');
+  const userRefLabels = loadRefs(root).filter((ref) => ref.origin === 'user').map((ref) => refIdentity(ref.source, ref.component)).sort();
+  return validateCompositionContractSource({ ...(existsSync(contractPath) ? { contract: readFileSync(contractPath, 'utf8') } : {}), ...(frame ? { frame } : {}), ...(copyDeck ? { copyDeck } : {}), ...(typeProof ? { typeProof } : {}), ...(scout ? { scout } : {}), ...(userRefLabels.length ? { userRefLabels } : {}) });
+}

package/core/composition-contract/visual-richness.ts

@@ -0,0 +1,101 @@
+/**
+ * Shadow-only, advisory-only. Never gates: findings from this module carry no
+ * exit-code weight and are not wired into the CLI or `validateCompositionContract`.
+ * Scope note (doc == code): a per-section carrier-presence heuristic. It checks,
+ * section by section, whether a content section names a purposeful visual carrier,
+ * and references the `## Focal hierarchy` visual-mass budget only as framing in the
+ * advisory message. It does NOT yet compute a cross-section visual-mass budget, so
+ * it cannot exempt a deliberately quiet supporting section that spends its mass
+ * elsewhere; real cross-section budget subordination is a follow-up required before
+ * this advisory is promoted toward gating.
+ */
+
+export type VisualRichnessRegister = 'quiet' | 'confident' | 'showpiece';
+
+export interface VisualRichnessFinding {
+  id: 'CARRIER-ADVISORY';
+  section: string;
+  message: string;
+  severity: 'advisory';
+}
+
+export interface VisualRichnessInputs {
+  contract: string;
+  register?: VisualRichnessRegister;
+}
+
+/** Copied parsing convention from `core/composition-contract/index.ts` (`## ` H2 sections). */
+function sections(markdown: string): Map<string, string> {
+  const result = new Map<string, string>();
+  const matches = [...markdown.matchAll(/^##\s+(.+?)\s*$/gm)];
+  for (let i = 0; i < matches.length; i++) {
+    const match = matches[i]!;
+    const start = match.index! + match[0].length;
+    const end = matches[i + 1]?.index ?? markdown.length;
+    result.set(match[1]!.trim(), markdown.slice(start, end).trim());
+  }
+  return result;
+}
+
+/**
+ * Sections whose subject matter is where a purposeful visual carrier would be
+ * declared. `Input fingerprint`, `Experience spine`, `Section dependency`,
+ * `Candidate axes`, and `Transfer boundary` are structural/process sections
+ * with no visual-carrier claim to make, so they are out of scope here.
+ */
+const CONTENT_SECTIONS = [
+  'Grid and alignment',
+  'Density and visual mass',
+  'Focal hierarchy',
+  'Domain form grammar',
+  'Media roles',
+  'Responsive recomposition',
+] as const;
+
+/** Broad carrier vocabulary: any purposeful non-decorative visual/alternate carrier. */
+const BROAD_CARRIER = /typographic|concept-bearing|\bpattern\b|\bgradient\b|\bphoto|\bgraphic|illustration|\bchart|\bdiagram|\bicon|imagery|\bmedia\b|animation|\bmotion\b|data\s*visuali[sz]ation|infographic/i;
+
+/**
+ * Stricter carrier vocabulary used for `showpiece`: excludes the bare word
+ * "media" (which trivially appears in the fixed `## Media roles` heading and
+ * its boilerplate prompt) and requires a specific, named carrier.
+ */
+const STRICT_CARRIER = /typographic|concept-bearing|\bpattern\b|\bgradient\b|\bphoto|\bgraphic|illustration|\bchart|\bdiagram|\bicon|imagery|animation|\bmotion\b|data\s*visuali[sz]ation|infographic/i;
+
+function inferRegister(parsed: Map<string, string>): VisualRichnessRegister {
+  const text = `${parsed.get('Density and visual mass') ?? ''} ${parsed.get('Focal hierarchy') ?? ''}`;
+  if (/\bshowpiece\b/i.test(text)) return 'showpiece';
+  if (/\bquiet\b/i.test(text)) return 'quiet';
+  return 'confident';
+}
+
+/**
+ * Pure, advisory-only evaluation: for each content section present in the
+ * contract, check whether it declares a purposeful visual carrier (a
+ * typographic block, a concept-bearing line, a pattern/gradient, real media,
+ * or an explicit alternate carrier). `quiet` registers are deliberately
+ * carrier-light by design and are not advised against; `showpiece` requires a
+ * specifically named carrier rather than the generic word "media".
+ */
+export function evaluateVisualRichness(inputs: VisualRichnessInputs): VisualRichnessFinding[] {
+  const parsed = sections(inputs.contract);
+  const register = inputs.register ?? inferRegister(parsed);
+
+  if (register === 'quiet') return [];
+
+  const carrierPattern = register === 'showpiece' ? STRICT_CARRIER : BROAD_CARRIER;
+  const findings: VisualRichnessFinding[] = [];
+  for (const section of CONTENT_SECTIONS) {
+    const body = parsed.get(section);
+    if (!body) continue;
+    if (!carrierPattern.test(body)) {
+      findings.push({
+        id: 'CARRIER-ADVISORY',
+        section,
+        message: `within the visual-mass budget set by Focal hierarchy, "${section}" does not yet name a purposeful visual carrier (typographic block, concept-bearing line, pattern/gradient, media, or an explicit alternate carrier)`,
+        severity: 'advisory',
+      });
+    }
+  }
+  return findings;
+}