` and exactly one `

` per rendered view — count them in the final DOM, zero and two both fail. 6. Responsive determinism — verify at 320, 390, and 1440 px before finishing: `document.documentElement.scrollWidth <= clientWidth` (no horizontal document scroll), the primary action fully inside the viewport, every interactive control ≥ 44px in its smaller dimension and horizontally unclipped. A quick DOM-math pass over the final HTML/CSS counts; skipping the check does not. 7. Evidence honesty determinism — for every datum category the brief forbids inventing (counts, prices, testimonials, logos, regulatory claims): write an explicit honest-absence sentence that NAMES the withheld category, placed where a reader would expect the datum; label every fabricated record "sample" (or "demo"/"fictional") visibly; never emit an affirmative number, price, star rating, or endorsement for a forbidden category anywhere on the page, including image alt text. 8. Foreground/background color PAIRS from the adopted tokens (never a lone accent value), decorative media `aria-hidden` and informative SVG named via `role="img"` + title/desc, then visual polish last with whatever budget remains. Before declaring the product finished, run a SELF-WALK: list every journey verb from the brief, and for each write (a) the exact keyboard path that reaches it and (b) the programmatic evidence that proves it (which attribute or role changes). Any row missing either entry is unfinished work — fix it before the mission proof, budget permitting, because a missing row scores the same as a missing page. ## Philosophy derivation chain (mandatory order) Read `references/derivation-chain.md` before any system draft. The order is PHILOSOPHY → DERIVE (decision table with D-ids and rationales) → TOKENS (with D-id back-references in comments) → COMPONENT SPECS (documented before code; select from `references/presets/INDEX.md` first and derive token slots from the decision table — never improvise from zero what the preset catalog already validates (gate GS8); `references/component-craft.md` is the floor) → LAYOUT GRAMMAR (per page, with content back-calculation — if the data cannot fill the grammar, enrich the data first, never leave wide viewports empty) → BUILD (pages consume only) → RENDER CRITIQUE → DESIGN.md carrying the philosophy and decision table so a designer can read WHY every value is what it is. A token value without a D-id rationale is an improvised value (gate GS7). ## Data discovery (good UI carries the data) A screen is only as good as the data it carries. Before designing anything, inventory the DATA TRUTH SOURCES and write `data-inventory.md` into the run directory: 1. Provided fixtures first: `data/.json`, `data/.js`, CSV, seeded stores. 2. Declared contracts next: OpenAPI/Swagger specs, GraphQL schemas, TypeScript interfaces/types, ORM models, API route handlers. 3. If neither exists and the brief implies records, the mode decides: - Guided mode: ASK the user for the data shape, or ask permission to scan the repository for data sources before proceeding. - Autonomous/benchmark mode: use only what was provided; state the absence honestly on-screen. NEVER invent fields, records, or endpoints. Then design FROM the data shape, not toward a template: - Entities and their cardinalities pick the page patterns (a 34-row entity is a table with filters, not three cards) and the density dial. - Every enum in the data (status, category, stock) becomes a system token set: one color/mark per value, defined once, legible at a glance. - Every field a user needs is on screen or one interaction away; IDs and timestamps are visible where an operator would search by them. A field in the dataset that never renders anywhere needs a reason. - Aggregates shown as KPIs are COMPUTED from the data at runtime and their definition is stated near the number (e.g. "open = pending + packed"). - When an API is the source (now or planned): the schema is the contract — per-endpoint loading/error/empty states, pagination beyond ~50 rows, and no rendering of fields the contract does not define. ## Visual quality contract (mandatory read) Before PRODUCT_BUILD, read `references/visual-quality-contract.md` in full and treat every item as a gate, not a suggestion. Non-negotiables repeated here because violating them wastes the whole run: - NEVER render developer/state switchers in the product UI; states come from real product interactions only. - NEVER ship native unstyled form controls — restyle every control from system tokens with the accessible native input underneath. - The system carries a display/body type pair with a ≥2× display step, a label role, section-air spacing steps (2.5–6rem), ONE surface genre, and accent as a small signal (≤~5% of any viewport). - The written system states its responsive behaviour and its component states as VALUES, not adjectives: Layout & Platforms names each breakpoint with the grid and type-scale change that happens there, and Components & States gives every interactive component its applicable states with the token each state actually uses. "Responsive" and "has hover/focus states" without the numbers is an unwritten section — evaluators scored exactly this gap lowest. - NEVER let a first-paint overlay (cookie banner, sheet, modal, sticky promo) cover the H1, the hero subject, or the primary action — at 390px as well as 1440px. A bottom bar or a scroll-triggered appearance is fine; a sheet over the hero is not. Hero image crops must keep the subject the brief asks for intact at mobile width. - After building, run the ONE-round self-critique from the contract (5 axes + gate sweep, System Fidelity replaces variety) and write `critique.md` into the run directory before the mission proof. ## Multi-page products When the brief asks for more than one page, the design system is the consistency contract: ONE shared stylesheet owns tokens and components (defined exactly once); every page links it and adds only page-level layout. Nav and footer are designed once and rendered identically on every page with `aria-current` on the active link. Body, heading, and primary-action styling must compute identically across pages; every internal link resolves to a real page. Build page one as the system's proof, then express the remaining pages FROM it — if page two needs a new token or component, that is a system change first, not a page-local invention. ## Motion and micro-transitions (system-owned) Motion is a design-system concern, not per-element improvisation. When the brief asks for a modern/polished feel (or names transitions), establish motion TOKENS in the system first and cite only them: - One duration scale (fast ~120ms, base ~200ms, slow ~320ms) and at most two easing curves (one enter, one exit). Every transition on the page uses a token pair — a one-off cubic-bezier is an unauthorized token. - Animate ONLY `transform` and `opacity` (compositor-friendly); never animate layout properties (width/height/top/margin) or box-shadow directly (fake elevation with a pseudo-element opacity fade). - Standard vocabulary, applied sparingly: entrance fade-up for major sections (one-time, on first reveal), hover elevation/tilt on interactive cards, pressed-state scale on buttons, focus-visible transition on CTAs. One page needs 3–5 total motion patterns, not one per element. - EVERY animation sits behind `@media (prefers-reduced-motion: reduce)` with a non-animated equivalent state — reduced-motion is a graded contract, not an afterthought. - Provided asset images get explicit width/height (no CLS) and motion applies to their container, never the raw img. ## Framework idiom projection The adopted design system is stack-neutral; the PRODUCT expresses it in the stack the brief names. Detect the stack from the brief and any provided runtime (vendored libraries in assets/), then project tokens and state semantics into that stack's native idiom — never a foreign one: - Vanilla HTML/CSS: tokens as `:root` custom properties; states as data-/aria- attributes driven by small event handlers. - React (including buildless Preact+HTM): tokens as one exported theme object AND mirrored `:root` custom properties; components as functions whose props carry state; aria attributes computed from the same props that drive the visuals (single source of truth — never a DOM query after render); lists keyed by stable record IDs; no innerHTML string templating. - Tailwind (when present): tokens declared once in the config/theme layer and referenced by utility classes; never inline arbitrary values that bypass the token scale. - The same journey states, aria semantics, and honesty rules apply identically in every stack — the projection changes syntax, never the contract. ## Design-system decision - Valid compatible root `DESIGN.md` → `reuse` without reopening it. Legacy 13/15/16-section and unmarked documents remain readable during the compatibility window; reusing one does not silently rewrite it. - Explicit or delegated authority to build a system → `establish`. - Explicit replacement of an existing system → `refresh`; legacy input must pass staged migration/check and opaque-extension preservation before replacement. - Narrow repair or explicit refusal → `surface-local-only`; never promote local choices as project facts. - Broad greenfield with no authority → ask one question: project system or local surface contract. - Exact official brand request with no authoritative source → block rather than fabricate. Reference selection happens only after this decision and only when it supplies useful verified inspiration. A reference never owns product facts. ## Evidence and unknowns Classify each consequential system decision as `prompt-fact`, `repository-fact`, `verified-reference-inspiration`, `agent-proposed-greenfield-decision`, or `unresolved`. Unknown means absent at the smallest boundary. Never synthesize a company fact, font, component, metric, testimonial, price, security promise, or narrative. Core v2 does not require placeholder facts: omit unresolved values from tokens, prescriptive prose, and code. A consequential unresolved decision may be named in Governance without a suggested fallback. ## Required run artifacts Store permanent artifacts under `.omd/runs//`: - `mission.json` - `council/decision-ledger.json` - `design-system-decision.json` - `system/proposal.md`, migration report/rollback references when applicable, and generated `system/proof.json` - `implementation.json` - `acceptance-plan.json` - `proof.json`, `repairs/round-.json`, and screenshots - `loop-trace.json` — per-round `renderIntegrity`/`critique` counts and `autoSelected[]` (the audit trail of unattended choices); an empty `rounds[]` means verification never ran and the proof cannot pass - `delivery.json` Receipts bind the original task, repository evidence, DESIGN.md, product output, consumer route, states, viewports and validator results. Missing proof is not a pass. The project-owned canonical system lives outside the run at: - `.omd/system/manifest.json` - `.omd/system/graph.json` - `.omd/system/provenance.json` - `.omd/system/coverage.json` The visible `DESIGN.md` begins with `# Design System`, contains exactly the seven neutral `design-md:section` anchors in the frozen Core order, and has no YAML/frontmatter, OmD/tool/generator/quality metadata at its top. Only an adopted, valid `profile: portable-core` manifest with exact graph/projection hashes makes the graph canonical; a migration candidate keeps its named source DESIGN.md canonical. The seven semantic `design-md:claim` declarations and every `design-md:claim-end` are compiler-owned and must not be edited after rendering. The Markdown remains a complete portable contract on its own. ## Guided-mode boundary If the user explicitly asks to review journey/system/validation checkpoints or to collaborate phase by phase, route to `omd:harness` and preserve all of its mandatory checkpoints. Do not silently switch an active guided run to Autopilot.