@3xhaust/oh-my-design 0.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/LICENSE +21 -0
  2. package/README.ko.md +282 -0
  3. package/README.md +282 -0
  4. package/adapters/build.ts +184 -0
  5. package/adapters/claude.ts +111 -0
  6. package/adapters/codex.ts +68 -0
  7. package/adapters/tokens.ts +21 -0
  8. package/adapters/tool-map.json +7 -0
  9. package/bin/omd-install.ts +76 -0
  10. package/bin/omd.ts +1774 -0
  11. package/core/asset-sourcing/index.ts +187 -0
  12. package/core/coach/index.ts +98 -0
  13. package/core/composition/app-shell-workbench.md +168 -0
  14. package/core/composition/asymmetric-diagonal-grid.md +178 -0
  15. package/core/composition/bento-grid.md +223 -0
  16. package/core/composition/editorial-index-labels.md +173 -0
  17. package/core/composition/form-wizard-stepper.md +132 -0
  18. package/core/composition/master-detail-flow.md +129 -0
  19. package/core/composition/section-inversion.md +182 -0
  20. package/core/composition/sidebar-margin-annotation.md +184 -0
  21. package/core/composition/split-screen-hero.md +224 -0
  22. package/core/composition/sticky-sidebar-scroll.md +219 -0
  23. package/core/composition/typographic-hero.md +100 -0
  24. package/core/composition-contract/index.ts +233 -0
  25. package/core/composition-contract/visual-richness.ts +101 -0
  26. package/core/config/index.ts +27 -0
  27. package/core/copy/index.ts +296 -0
  28. package/core/craft/finish-pass.md +356 -0
  29. package/core/craft/index.ts +33 -0
  30. package/core/design/index.ts +581 -0
  31. package/core/design/interaction-states.ts +189 -0
  32. package/core/eval-harness/index.ts +225 -0
  33. package/core/evidence/final.ts +444 -0
  34. package/core/evidence/task.ts +459 -0
  35. package/core/figma/client.ts +312 -0
  36. package/core/figma/diff.ts +261 -0
  37. package/core/figma/responsive.ts +310 -0
  38. package/core/figma/system.ts +466 -0
  39. package/core/figma/types.ts +185 -0
  40. package/core/frame/check-ux.ts +180 -0
  41. package/core/frame/index.ts +39 -0
  42. package/core/frame/write.ts +168 -0
  43. package/core/graphics/css-illustration-primitives.md +189 -0
  44. package/core/graphics/duotone-image-presets.md +173 -0
  45. package/core/graphics/gradient-mesh.md +178 -0
  46. package/core/graphics/noise-grain-texture.md +150 -0
  47. package/core/graphics/placeholder-policy.md +185 -0
  48. package/core/graphics/svg-geometric-patterns.md +145 -0
  49. package/core/history/index.ts +39 -0
  50. package/core/install/detect.ts +32 -0
  51. package/core/install/install.ts +321 -0
  52. package/core/install/patch-claude.ts +109 -0
  53. package/core/install/patch-codex.ts +82 -0
  54. package/core/interaction/index.ts +101 -0
  55. package/core/interaction/recipes/signature-lighting.md +203 -0
  56. package/core/ir/dom.ts +352 -0
  57. package/core/ir/normalize.ts +177 -0
  58. package/core/motion/easing.md +151 -0
  59. package/core/motion/energy.ts +188 -0
  60. package/core/motion/recipes/image-hover-distortion.md +198 -0
  61. package/core/motion/recipes/magnetic-hover.md +229 -0
  62. package/core/motion/recipes/marquee.md +202 -0
  63. package/core/motion/recipes/number-counter.md +242 -0
  64. package/core/motion/recipes/page-loader.md +240 -0
  65. package/core/motion/recipes/parallax.md +233 -0
  66. package/core/motion/recipes/scroll-reveal.md +210 -0
  67. package/core/motion/recipes/section-color-inversion.md +217 -0
  68. package/core/motion/recipes/split-text-entrance.md +222 -0
  69. package/core/motion/recipes/stagger-orchestrator.md +227 -0
  70. package/core/motion/recipes/sticky-scene-transition.md +246 -0
  71. package/core/motion/recipes/view-transitions.md +239 -0
  72. package/core/probe/index.ts +186 -0
  73. package/core/probe/schema.json +46 -0
  74. package/core/protocol/composition-contract.md +192 -0
  75. package/core/protocol/copy-deck.md +96 -0
  76. package/core/protocol/human-design-loop.md +447 -0
  77. package/core/protocol/slop-review.md +71 -0
  78. package/core/ref/batch.ts +94 -0
  79. package/core/ref/blueprint.ts +199 -0
  80. package/core/ref/distance.ts +225 -0
  81. package/core/ref/invariants.ts +162 -0
  82. package/core/ref/signal.ts +37 -0
  83. package/core/ref/store.ts +122 -0
  84. package/core/render/index.ts +607 -0
  85. package/core/rules/attribution.ts +159 -0
  86. package/core/rules/builtin/contrast.yaml +8 -0
  87. package/core/rules/builtin/focus.yaml +8 -0
  88. package/core/rules/builtin/hit-area.yaml +8 -0
  89. package/core/rules/builtin/ko.yaml +6 -0
  90. package/core/rules/builtin/motion.yaml +80 -0
  91. package/core/rules/builtin/slop.yaml +365 -0
  92. package/core/rules/builtin/spacing.yaml +9 -0
  93. package/core/rules/builtin/system.yaml +42 -0
  94. package/core/rules/builtin/token.yaml +8 -0
  95. package/core/rules/builtin/ux.yaml +125 -0
  96. package/core/rules/engine.ts +88 -0
  97. package/core/rules/leakage.ts +72 -0
  98. package/core/rules/motion-spec.ts +204 -0
  99. package/core/site/index.ts +100 -0
  100. package/core/slop/index.ts +427 -0
  101. package/core/slop/text-slop.ts +220 -0
  102. package/core/source-seal/index.ts +174 -0
  103. package/core/stack/index.ts +53 -0
  104. package/core/target/index.ts +183 -0
  105. package/core/theory/color.md +285 -0
  106. package/core/theory/components.md +272 -0
  107. package/core/theory/craft.md +270 -0
  108. package/core/theory/expressive.md +213 -0
  109. package/core/theory/imagegen.md +105 -0
  110. package/core/theory/layout.md +159 -0
  111. package/core/theory/motion.md +283 -0
  112. package/core/theory/typography.md +134 -0
  113. package/core/theory/ux.md +580 -0
  114. package/core/theory/voice.md +595 -0
  115. package/core/types.ts +684 -0
  116. package/package.json +40 -0
  117. package/src/agents/composer.agent.yaml +174 -0
  118. package/src/agents/eye.agent.yaml +208 -0
  119. package/src/agents/framer.agent.yaml +52 -0
  120. package/src/agents/glance.agent.yaml +19 -0
  121. package/src/agents/hand.agent.yaml +200 -0
  122. package/src/agents/scout.agent.yaml +71 -0
  123. package/src/agents/sketch.agent.yaml +64 -0
  124. package/src/agents/typesetter.agent.yaml +52 -0
  125. package/src/agents/writer.agent.yaml +63 -0
  126. package/src/skills/omd-coach/SKILL.md +40 -0
  127. package/src/skills/omd-critique/SKILL.md +77 -0
  128. package/src/skills/omd-figma/SKILL.md +256 -0
  129. package/src/skills/omd-humanize/SKILL.md +160 -0
  130. package/src/skills/omd-scout/SKILL.md +77 -0
  131. package/src/skills/omd-ultradesign/SKILL.md +521 -0
@@ -0,0 +1,521 @@
1
+ ---
2
+ name: omd-ultradesign
3
+ description: >-
4
+ Design and build an interface through a human design loop: interrogate the brief,
5
+ research evidence, write real copy first, compose deliberately, compare isolated structural sketches, build
6
+ reflectively, test hierarchy and interaction, critique blind, reframe, and ship.
7
+ Use for UI, page, app, dashboard, blog, landing-page, and redesign requests.
8
+ ---
9
+
10
+ # Ultradesign
11
+
12
+ > **Figma structural-bypass route**: a figma.com link selects one partial graph, not a terminal handoff:
13
+ > retain preflight, framing/task coverage, copy, typography proof, production build, craft
14
+ > checkpoints, safe probes, glance, sharp critique/refinement, and ship; use `omd-figma` for supplied
15
+ > structure and skip only concept hypothesis, scout/reference synthesis, composition authoring, and
16
+ > independent sketch divergence/blind selection. Record the retained/skipped phases and the supplied
17
+ > structure evidence. Do not run the normal structural graph as a second path.
18
+
19
+ Give the user the working interface they asked for. Do not expose internal quotas or ask
20
+ them to operate the harness. Run host-native agents in fresh contexts; do not create a
21
+ workflow engine, queue, model router, or session runtime.
22
+
23
+ Read `protocol/human-design-loop.md` from `omd pack dir` first. It owns phase order, state,
24
+ evidence precedence, blindness, isolation, checkpoints, and probe safety. Use the relevant
25
+ theory/cookbook files (`theory/`, `composition/`, `graphics/`, `motion/`, `craft/`) instead
26
+ of duplicating their rules here. `.omd/` records are English; the interface and handback use
27
+ the user's language.
28
+
29
+ ## 0. Preflight and routing
30
+
31
+ Run `omd doctor`. Stop on a failed prerequisite. Pin the absolute working directory first. A Figma
32
+ frame or exact visual target uses the single Figma structural-bypass route declared above; it retains
33
+ content, craft, glance, probe, critique, and all UX evidence rather than handing the run off or
34
+ terminating this loop.
35
+
36
+ Apply stack precedence exactly: explicit user request > existing repository stack/toolchain
37
+ (including existing vanilla HTML) > React + Vite + TypeScript only for a truly blank
38
+ greenfield. Plain HTML greenfield requires an explicit user request; there is no autonomous
39
+ single-static-surface exception. Preserve and investigate unrecognised package/toolchain
40
+ evidence instead of replacing it with React. Greenfield scaffold dependencies are allowed;
41
+ existing projects receive no unnecessary dependencies.
42
+ Plain HTML/CSS/JS for a blank greenfield requires the explicit user request quoted verbatim in the
43
+ stack `omd decision`. Absent a matching verbatim user quote, a truly blank greenfield is React +
44
+ Vite + TypeScript — never infer, assume, or paraphrase a pre-authorization. A decision that claims
45
+ the brief "pre-authorized plain HTML" without a verbatim user quote that actually says so is a
46
+ stack-routing defect, not a lawful shortcut.
47
+ "Existing repository stack" means a real project the user brought: a package manifest, a framework
48
+ or build config (`vite.config`, `next.config`, `package.json`, etc.), or files the user explicitly
49
+ points at. A bare `index.html`/`.css`/`.js` with no manifest and no build config, sitting next to an
50
+ `.omd/` directory from a prior OMD run, is OMD's own leftover output — not a user stack. A fresh
51
+ design brief in that folder is a greenfield (React + Vite + TypeScript by default), not a
52
+ continuation of the leftover HTML; do not let your own previous output pin the stack to vanilla.
53
+ Testing repeatedly in one directory reuses the `.omd/refs/` board (fine, output-neutral) but never
54
+ reclassifies a greenfield as an existing HTML project.
55
+ The hand runs `omd stack` before its first production write and builds in exactly the stack it
56
+ computes from folder evidence — a blank greenfield resolves to React + Vite + TypeScript
57
+ deterministically, so the model never talks itself into plain HTML for a one-page site. The only
58
+ lawful override is a verbatim explicit user request for HTML.
59
+
60
+ Run `omd config show`. `checkpoint: none` is the default and means no approval waits.
61
+ Only `concept`, `structure`, or `both` opt into a human pause at that named point.
62
+ Speed comes only from output-neutral structure, never from degrading the result. Two levers, both
63
+ of which leave the full-fidelity output unchanged: reuse a coverage-complete `.omd/refs/` board when
64
+ this working directory already has one for the concept (scout only the missing categories rather
65
+ than rebuilding it), and let the scout capture references in parallel with `omd ref add-batch` — one
66
+ browser instead of one per reference. The first run in a fresh directory is the slowest because it
67
+ builds the board; later runs in the same directory are much faster and still full-fidelity. There is
68
+ no reduced-quality mode: every run is the real result.
69
+
70
+ Run `omd taste profile` and pass only that explicit-user profile to the framer. Never use
71
+ `--all` for design decisions. Current brief beats current explicit feedback, which beats
72
+ prior explicit taste, which beats agent choices. Record conflicts.
73
+
74
+ ## 1. Frame and concept hypothesis
75
+
76
+ Spawn `omd-framer` with the brief, explicit-user taste profile, and working directory. It
77
+ records the primary task, frequent action, costliest error/recovery, the surface
78
+ classification (`marketing` | `product` | `editorial` | `mixed`, per `theory/ux.md`
79
+ §Surface types), evidence, hypothesis, and trade in `.omd/frame.md`. The surface
80
+ classification routes every later stage's grammar: pass it explicitly to the composer,
81
+ sketches, hand, and eyes. A brief that asks for a tool (dashboard, console, CRUD/admin,
82
+ editor, settings, onboarding, search) is a `product` surface even when phrased like a
83
+ site request — do not let the marketing grammar be the silent default.
84
+
85
+ Read the frame and relevant theory. Explore several distinct candidate concept directions, not a
86
+ single guess — each a named generator/metaphor, colour direction, typography register,
87
+ surface/material stance, density posture, quiet/confident/showpiece register, and one memorable
88
+ moment. Ground them in the brief and evidence, and after the scout's design-gallery visual research
89
+ (§2, per `protocol/human-design-loop.md` §Visual reference gallery and concept exploration)
90
+ blind-select the strongest main-screen direction and record it — with its rejected alternatives —
91
+ using `omd frame generator` plus `omd decision`. The number of directions scales with ambition and
92
+ uncertainty. This visual-direction choice is a direction signal only and never replaces the
93
+ structural sketch divergence or any UX, copy, type, or critique gate; a generic default visual
94
+ system (unstyled controls, flat fields, weak hierarchy, arbitrary whitespace, no distinctive
95
+ surface/colour system) fails the visual acceptance gate even when every task passes. Pause only when
96
+ config explicitly includes the concept checkpoint.
97
+ When the brief explicitly signals visual ambition — 개쩔게, 죽여주게, 미쳤다, 어워드/awards-level,
98
+ killer, wow, showpiece — treat it as an explicit user request for the showpiece register and at
99
+ least one genuinely novel signature moment, and record it as such. Do not reframe an explicit
100
+ ambition brief down into restraint: substance-over-spectacle is the default only when the brief is
101
+ silent on ambition; the current brief beats the agent's own taste for restraint. Restraint still
102
+ governs *how many* techniques ship (one signature moment, never a catalogue), never *whether* the
103
+ explicitly requested showpiece ambition is honored at all.
104
+
105
+ ## 2. Research and copy before structure
106
+
107
+ Spawn `omd-scout` with the concept, explicit functions or product goal, surface classification,
108
+ user references first, and working directory; also pass the component inventory. Require the canonical branch decision before research.
109
+ `protocol/composition-contract.md` exclusively
110
+ owns the strict `## Reference synthesis` Markdown ABI; require scout to emit sanitized records
111
+ that use its exact axis keys, dispositions, reasons, and selector rules without a role-local
112
+ schema. Scout preserves explicit user-reference coverage, stable source keys/labels, trust,
113
+ uncertainty, and only applicable axes; it never passes raw source material downstream. Treat
114
+ the scout return as a sanitized summary, never raw transcripts or screenshots. Downstream
115
+ receives sanitized criteria, never raw URLs, screenshots, pixels, or source-page descriptions.
116
+ Resolve conflicts through product task, accessibility/mobile constraints, and one coherent
117
+ design system.
118
+ Require the scout to cover curated design-gallery visual references (Pinterest, Dribbble, Mobbin,
119
+ Behance, Land-book, and equivalents) as a first-class category per
120
+ `protocol/human-design-loop.md` §Visual reference gallery and concept exploration, sanitized into
121
+ the canonical multi-axis synthesis; no gallery image, URL, or pixel travels downstream.
122
+ **List-detail branch:** only for a requested or task-completely inferred list→detail workspace,
123
+ apply the canonical non-primary work-object selection requirement in
124
+ `protocol/human-design-loop.md`; it never creates a default task for other surfaces.
125
+ **Support-chat branch:** only for an explicitly requested or task-completely inferred
126
+ support-ticket conversation, apply the canonical temporal-window merge/split and visible-last-bubble
127
+ regressions in `protocol/human-design-loop.md`; it never applies conversation behavior elsewhere.
128
+
129
+
130
+ The coordinator does not author copy. The scout's voice/audience evidence is the writer's only dependency;
131
+ remaining board capture is independent. Once that evidence is in hand, spawn
132
+ `omd-writer` concurrently with the scout's remaining board capture — the writer drafts the copy deck
133
+ while the board finishes building. Give it the brief, that cited voice/audience evidence, working
134
+ directory, `protocol/copy-deck.md`, and `theory/voice.md`.
135
+ It writes only `.omd/copy-deck.md`. Run `omd copy --check`; on failure stop divergence and
136
+ send the deterministic findings back to the writer for autonomous repair without waiting
137
+ for the user.
138
+ The writer additionally runs `omd text-slop .omd/copy-deck.md` as an advisory self-scan; it is
139
+ non-gating and never replaces the blind copy review, but a kept candidate carries a recorded reason.
140
+
141
+ After the first clean check, spawn a fresh `omd-eye` in copy-editor mode with only the
142
+ sanitized brief, copy deck/fact ledger, and cited voice/audience evidence. Do not pass renders,
143
+ layout, code, build rationale, frame, decisions, or authorship. Before sending its findings
144
+ to the writer, preserve and validate the report as specified below. Then send the cleanly
145
+ preserved findings to the writer for deck-first revision, rerun `omd copy --check`, and start
146
+ sketches only after it passes again. Every shipped claim traces to a verified fact ID;
147
+ fixture/open facts never ship. Status/error/empty/recovery copy exists only where applicable.
148
+
149
+ Before returning the report to the writer, preserve the fresh eye's report verbatim at
150
+ `.omd/.cache/copy-eye.md`. The exact copy-eye report format is owned only by
151
+ `protocol/human-design-loop.md`; do not restate or alter it. Compute the
152
+ reviewed hash before writer revision, then immediately run `omd copy --review-check`. A failure
153
+ stops writer revision and divergence until the report format is repaired. The command validates
154
+ report structure only; it does not prove blindness or semantic quality and must not compare the
155
+ reviewed hash with the current deck. The writer's changed deck and final `omd copy --check` are
156
+ separate evidence; never overwrite the report with the final deck hash or claim that the eye
157
+ reviewed the revised bytes.
158
+
159
+ For a `product` or `mixed` surface, and for any multi-surface output, run `omd design`
160
+ and complete the durable design contract — its Information architecture and Interaction
161
+ states sections are the state discipline (loading, empty, error, success, disabled,
162
+ offline: implemented or explicitly skipped with a reason) that keeps a work surface from
163
+ shipping happy-path-only. Only a single-surface `marketing`/`editorial` run may skip this
164
+ artifact with a recorded reason; that skip never changes stack routing.
165
+ For every `product` surface and product screen of a `mixed` surface, the first viewport is owned by the work object at representative working density; never replace it with a marketing hero or decoration.
166
+ For `product` or `mixed` surfaces, the frame owns the `Task coverage matrix` and the composer
167
+ maps every applicable frame `T#` into `UX task coverage` using the canonical schema in
168
+ `protocol/human-design-loop.md`; do not restate or alter that protocol-owned schema.
169
+ The same protocol exclusively owns task-evidence fields, cardinality, cache locations,
170
+ applicability, and validation. The hand binds each existing production-reachable task
171
+ to its production locator and work-object identity, runs declared applicable probes and
172
+ required-viewport renders, then publishes actual evidence with `omd evidence tasks --input
173
+ .omd/.cache/task-evidence-manifest.json` followed by `omd evidence tasks-check --json`.
174
+ Invalid submit remains attemptable and proves an actionable error with the entered value
175
+ preserved; transient evidence is captured only after settlement or reduced motion. Never
176
+ create task rows because a state is reachable or hand-write `.omd/task-evidence.json`. Do not
177
+ invent product task/state/probe evidence or a task-evidence manifest for `marketing`,
178
+ `editorial`, or `static` runs.
179
+
180
+
181
+ ## 3. Typography proof before structure
182
+
183
+ After the second clean copy check, spawn `omd-typesetter` with the copy deck, scout's cited
184
+ typography evidence, `protocol/human-design-loop.md`, and `theory/typography.md`. It creates
185
+ layout-neutral actual-copy specimens in `.omd/.cache/type-proof/`, renders 1280x900 and
186
+ 390x844, and writes `.omd/type-proof.md`. It does not design composition, colour, graphics,
187
+ or motion and does not rewrite copy.
188
+
189
+ Spawn a fresh `omd-eye` in typography-proof mode with only the two specimens plus sanitized
190
+ copy and requirements. Do not pass authorship, reference rationale, page structure, colour,
191
+ or code. Return the blind findings to the typesetter, require revision and both renders
192
+ again, and start sketches only after the proof passes. Large type may pass when concept-
193
+ bearing and proof-clean; size alone is neither success nor failure.
194
+
195
+ The proof fingerprint is invalid after any copy, font family/file, requested weight/axis, or
196
+ proof container-width change. Rerun the proof instead of carrying an obsolete approval.
197
+
198
+ ## 4. Composition contract before divergence
199
+
200
+ Spawn a fresh `omd-composer` with only the sanitized frame/concept (including surface
201
+ classification), clean copy deck, approved type proof, scout transfer records,
202
+ `protocol/composition-contract.md`, and `theory/layout.md`. The composition protocol alone
203
+ owns the strict `## Reference synthesis` Markdown ABI: the composer serializes the scout's
204
+ sanitized records exactly in that section, with no duplicate schema, heading, axis, or selector.
205
+ It applies the canonical Branch A/B and clean-room rules in `protocol/human-design-loop.md`
206
+ without creating task rows. The composer writes only `.omd/composition.md`, records required
207
+ fingerprints, and runs `omd composition --check`; validator failure, including missing or
208
+ duplicate canonical axes or selectors, stops divergence. When no durable scout summary exists,
209
+ it records `N/A — reason` rather than inventing evidence.
210
+
211
+
212
+ Require one first-viewport dominant anchor, its visual-mass budget and relationship to
213
+ value/proof/visible CTA, plus a visible rejection condition. A visible CTA and predictable
214
+ completion path satisfy task reach; the terminal form/control surface need not be above fold
215
+ and is not rewarded merely for appearing there. The anchor may use lawful product/evidence
216
+ media, explanatory graphics, real interaction/data, or concept-bearing typography—never a
217
+ mandatory photo or invented fact/asset. When mechanism/material/workflow is central, Media
218
+ roles assigns a lawful carrier or an explicit alternate non-media mental-model carrier with
219
+ its limitation; `none because no approved photo` is insufficient.
220
+ For a confident/showpiece register where the composition is the deliverable, the composer
221
+ specifies 2–3 independent clean-room art-direction directions from the committed
222
+ palette/type/material, sanitized measured principles, and skin-abstracted blueprints. The
223
+ host/coordinator owns concurrent draft generation, cache management, blind selection, and
224
+ provenance/decision recording. The composer may consume only a host/coordinator-produced draft
225
+ whose lineage attests that it used only those sanitized inputs and no source screenshot, URL,
226
+ pixels, or visual likeness. The composer does not generate drafts, inspect raw source material,
227
+ manage the cache, select a draft, or record that decision. Drafts are design references, never shipped
228
+ page assets; `omd ref distance` still gates the shipped build. A quiet register or unavailable
229
+ host image capability uses the reference board and CSS/SVG graphics recipes instead.
230
+
231
+ Run `omd composition --check`. Missing sections, malformed fingerprints, or stale inputs
232
+ stop divergence and return to the composer. A later change to frame, copy, type proof, or
233
+ scout summary invalidates all dependent sketches and the production build until the contract
234
+ is recomposed and passes again.
235
+ The composer also runs `omd visual-richness .omd/composition.md` as an advisory carrier read;
236
+ `CARRIER-ADVISORY` findings are non-gating prompts to name a purposeful carrier for a content
237
+ section, and a `quiet` register legitimately yields none.
238
+
239
+ ## 5. Independent structural divergence and blind selection
240
+
241
+ Gate divergence by structural uncertainty and impact:
242
+
243
+ - default: two independent `omd-sketch` contexts;
244
+ - showpiece or high uncertainty/impact: three;
245
+ - skip only when structure is supplied (Figma/target/explicit layout), recording why.
246
+
247
+ On the normal graph, skipping the composer or sketch divergence is a protocol violation: an
248
+ `.omd/composition.md` that passes `omd composition --check` and the blind sketch-selection record are
249
+ mandatory ship evidence. The Figma structural-bypass route is the sole exception and records its
250
+ explicitly retained/skipped phases; do not run a terminal handoff or a second competing graph.
251
+
252
+ Give every sketch the same sanitized frame/concept, copy deck, sanitized approved typography
253
+ contract, and sanitized composition contract, plus a different anonymous candidate id and
254
+ one axis from the contract's Candidate axes section. Include approved dependencies, grid and
255
+ alignment behavior, density, focal hierarchy, form grammar, media or approved alternate
256
+ mental-model carrier, responsive recomposition, type
257
+ roles, family, weight, size/measure, and wrapping constraints; omit source rationale,
258
+ rejected alternatives, URLs, and authorship. Sketches preserve both contracts and vary only
259
+ their assigned axis. They cannot invent a new type scale, see one another, or read the full
260
+ proof, and write only under
261
+ `.omd/.cache/sketches/<id>/`. Their real-content low-fi renders contain structure, type
262
+ scale, and enough grayscale carrier structure to judge its functional relation—never colour,
263
+ motion, polished/decorative graphics, production edits, or sales prose.
264
+
265
+ Every candidate renders exactly four proofs: fixed desktop 1280x900, fixed mobile 390x844,
266
+ full-page desktop continuity, and full-page mobile continuity. Full-page captures use
267
+ `--full-page` and are supplemental evidence for narrative dependency and composition rhythm
268
+ only; fixed renders remain authoritative for every acceptance dimension.
269
+
270
+ Spawn a fresh `omd-eye` in sketch-selector mode with anonymous renders, sanitized frame,
271
+ copy deck, and the same sanitized typography and composition contracts only. Score exactly:
272
+ task/CTA clarity, narrative dependency, composition rhythm, concept-specific form,
273
+ responsive hierarchy, type/copy accommodation, interaction/form usability risk, and
274
+ accessibility/implementation cost. Do not substitute a generic visual-taste score or expose
275
+ candidate, source, typography, or composition rationale.
276
+ Use the frozen scale exactly: 0 absent/broken; 1 weak with major failures dominant; 2
277
+ adequate and functional with generic or consequential weakness; 3 strong, deliberate, and
278
+ robust with only minor weakness; 4 exceptional, unusually coherent/specific with no material
279
+ desktop/mobile contradiction. Require eight integer scores, eight one-sentence visible-
280
+ evidence rationales, and the arithmetic mean. Reject any contract violation or any dimension
281
+ below 2; do not average away a floor failure. Do not equate a form above fold with CTA reach,
282
+ and award concept-specific form only when the motif/anchor/carrier has a functional relation
283
+ to the domain mechanism, material, workflow, evidence, or action.
284
+
285
+ Use these frozen dimension-specific anchors. Scores 1 and 3 interpolate only between adjacent
286
+ 0/2/4 anchors; they are not generic visual-taste scores:
287
+
288
+ - **Task/CTA clarity** — 0: no immediate primary CTA or completion path; entry or next action
289
+ is ambiguous or blocked. 2: the CTA is visible and usable with an understandable next step,
290
+ but feedback or the path is generic or weak. 4: an immediate primary CTA, predictable
291
+ completion path, and state feedback are unmistakable on desktop and mobile; a terminal form
292
+ is not required above the fold.
293
+ - **Narrative dependency** — 0: sections are interchangeable or out of order, or prerequisite
294
+ information is missing or follows the decision that needs it. 2: the sequence is
295
+ understandable, but some sections remain weakly dependent or generic. 4: every section
296
+ answers an entering question and creates a prerequisite for the next; removal or reordering
297
+ visibly weakens the narrative.
298
+ - **Composition rhythm** — 0: alignment, visual mass, negative space, span, and density are
299
+ arbitrary or monotonous and obscure hierarchy or sequence. 2: those five properties form a
300
+ workable hierarchy with generic or uneven transitions. 4: alignment, visual mass, negative
301
+ space, span, and density vary deliberately to stage the sequence and dominant anchor across
302
+ desktop and mobile, without an arbitrary break.
303
+ - **Concept-specific form** — 0: the result is a generic template or its motif/carrier is
304
+ decorative and unrelated to the domain. 2: a domain relationship is recognizable, but some
305
+ anatomy remains generic or ornamental. 4: motif, anchor, and carrier arise from the domain
306
+ mechanism, material, workflow, evidence, or action and govern functional relationships
307
+ rather than decoration.
308
+ - **Responsive hierarchy** — 0: mobile is a shrunken/stacked desktop with lost or cropped
309
+ content, a broken task path, or a broken anchor dependency. 2: usable reflow preserves
310
+ content and task reach, but priority or anchor recomposition is conventional or uneven.
311
+ 4: deliberate mobile recomposition preserves semantic order, dominant-anchor morphology,
312
+ priority, and an uninterrupted CTA/task path with no desktop-only dependency.
313
+ - **Type/copy accommodation** — 0: real copy truncates, overlaps, becomes placeholder content,
314
+ or breaks Korean wrapping, hierarchy, or CTA labels. 2: real copy fits and hierarchy remains
315
+ understandable, with minor awkward wraps, repetition, or density. 4: real Korean copy,
316
+ repeated data, and CTA labels are fully integrated; measure, wrapping, hierarchy, and
317
+ concept-bearing type remain robust on desktop and mobile.
318
+ - **Interaction/form usability risk** — 0: the primary task cannot succeed, or controls,
319
+ focus path, feedback, error/recovery, or a required reachable state is broken. 2: the primary
320
+ task works with adequate controls and states, but feedback, recovery, or an edge state has a
321
+ consequential non-blocking weakness. 4: task success, immediate feedback, focus path,
322
+ duplicate prevention, value preservation, and every applicable recovery/exit are robust in
323
+ supplied probes; inapplicable states are not invented.
324
+ - **Accessibility/implementation cost** — 0: contrast, focus/order, reflow, or target reach
325
+ fails, or the structure is impractical and visibly unfinished. 2: the implementation path is
326
+ credible and basic access works, but costly complexity or incomplete finish remains. 4:
327
+ contrast, keyboard focus/order, reflow, target reach, reduced motion, maintainable structure,
328
+ and applicable finish details form a credible, accessible, finished implementation.
329
+
330
+ When every candidate violates a contract or has any dimension below 2, record **no winner**.
331
+ Never lower the floor, select the closest candidate, or hide the failure in the mean. Have the
332
+ fresh selector classify the shared failure from visible evidence only as contract-level when
333
+ a supplied contract requirement creates the shared contradiction, or execution-level when
334
+ the contracts permit success but candidates fail to execute it.
335
+
336
+ Run at most one bounded recovery round. For a contract-level failure, spawn a fresh composer
337
+ with only the sanitized shared visible contract conflict—no candidate renders, scores,
338
+ identities, or rationale. Require a revised `.omd/composition.md`, a clean
339
+ `omd composition --check`, and a new hash; invalidate every old candidate. Then spawn fresh
340
+ sketch contexts for replacements under the revised contract and assigned axes. For an
341
+ execution-level failure, preserve the approved contracts and run exactly one bounded
342
+ replacement round in fresh sketch contexts, one per candidate. Each replacement receives
343
+ the same approved contracts and axis plus
344
+ only its own sanitized visible failure and acceptance criteria. Do not pass numeric scores,
345
+ the prior render/source, other candidates/renders, or candidate/selector rationale.
346
+
347
+ Spawn a fresh selector for the replacement set. If none passes, do not retry again: reframe
348
+ and stop with visible evidence, or pause only when the configured structure checkpoint
349
+ requires a human decision. Never create an execution engine or unbounded retry loop. Record
350
+ the winner and rejected tradeoffs only when a candidate actually passes.
351
+
352
+ ## 6. Production build with reflective craft
353
+
354
+ On the normal graph, spawn `omd-hand` once with the selected structure, sanitized build brief,
355
+ copy deck, `.omd/type-proof.md`, `.omd/composition.md`, and accepted sanitized transfer criteria;
356
+ require `omd composition --check` before its first production write. On the Figma structural-bypass
357
+ route, supply `.omd/figma/snapshot.json`, `.omd/figma/design-system.md`, `.omd/attribution.md`, and
358
+ the selected frame inventory instead of composition/transfer inputs; require those artifacts to exist
359
+ and match the supplied frame before the first production write. The hand implements normal-graph
360
+ criteria at their destination screen/route and unique semantic reference-landing selector, or records
361
+ an evidence-backed deviation; it never receives raw URLs, screenshots, pixels, or source descriptions.
362
+ Transfer records never create tasks or probes. The hand builds semantic
363
+ real-content layout first,
364
+ then the visual system, then motion. It must record two concrete reflection-in-action loops:
365
+
366
+ ```bash
367
+ omd craft checkpoint semantic --render <path> --observed "..." --changed "..."
368
+ omd craft checkpoint visual --render <path> --observed "..." --changed "..."
369
+ ```
370
+
371
+ The semantic checkpoint occurs after desktop/mobile real-content layout. Then the hand
372
+ re-proves typography inside the selected production container at desktop and mobile after
373
+ OMD render/IR waits for `document.fonts.ready`. It compares requested versus computed
374
+ family/weight, actual Korean/Latin/numerals, wraps, clips, orphans, and hierarchy. The visual
375
+ checkpoint occurs only after that reproof and after type/colour/spacing/components, before
376
+ motion. Both checkpoints require a change; a gray-box or "no change" ritual does not count.
377
+ Immediately after scaffold/dependency resolution, resolve every newly introduced import/export
378
+ against the exact installed versions, parse generated configuration with its owning tool, and run
379
+ focused typecheck, build, and test-discovery. Repeat this smoke verification after every
380
+ dependency, dependency API, or build-config change; retain the full final verification. For
381
+ dialogs, toasts, and other transient UI, collect evidence only after fonts and
382
+ animations/transitions settle, or under reduced motion, and require visible pixels rather than
383
+ DOM presence alone.
384
+
385
+ The build acceptance contract verifies the primary task, most frequent action,
386
+ costliest-error recovery, an exit from every reachable state, immediate visible feedback,
387
+ and mobile reach. It also verifies the focal anchor's morphology, visual-mass budget, and
388
+ value/proof/CTA relationship plus the lawful media/alternate carrier's functional relation
389
+ and limitation in fixed desktop/mobile renders. It records visible acceptance evidence or a
390
+ deviation for the sharp eye. A full form need not occupy the first viewport. The hand uses native semantics, preserves form values on error, blocks
391
+ duplicate submits, implements only applicable states, and honors reduced motion.
392
+
393
+ ## 7. Squint before sharp, then safe interaction
394
+
395
+ Render desktop and mobile squint images before any sharp render is exposed to a critic:
396
+
397
+ ```bash
398
+ omd render <page> --viewport 1280x900 --squint -o .omd/.cache/squint-desktop.png
399
+ omd render <page> --viewport 390x844 --squint -o .omd/.cache/squint-mobile.png
400
+ ```
401
+
402
+ These commands capture the exact viewport by default. `--full-page` is supplementary
403
+ continuity evidence only and never replaces fixed-viewport desktop/mobile acceptance renders.
404
+
405
+ Spawn `omd-glance` with only those images. Preserve its four-line report. Squint isolates
406
+ hierarchy; never call it a colour-blind simulation or literal 50ms test.
407
+
408
+ Production source now exists. Read `protocol/slop-review.md`, run `omd slop scan <root>
409
+ --json`, and keep the raw report under `.omd/.cache/`. Triage each candidate as `confirmed`,
410
+ `dismissed`, or `needs-render`; candidate presence is not a failed gate, while an untriaged
411
+ candidate is. Treat `needs-render` as transitional: obtain sharp evidence and resolve it
412
+ before ship. Final untriaged and needs-render counts are both zero. Record durable
413
+ repair/dismissal evidence in `.omd/decisions.md`. Do not merge
414
+ source candidates with rendered IR warnings or send them to check history/coach; rendered IR
415
+ is authoritative where they overlap.
416
+
417
+ Use the copy deck's Interaction scope. `stateful` requires explicit non-destructive
418
+ `.omd/probes/primary.json` and `.omd/probes/recovery.json`, with both run through `omd probe`;
419
+ these are baseline probes, not a ceiling on the `Task coverage matrix`. `navigation-only`
420
+ requires and runs only the primary probe; recovery is N/A with a reason. `static` records
421
+ both probes N/A with reasons. Never invent recovery/error/empty UI or product task/state/probe
422
+ evidence for an inapplicable `marketing`, `editorial`, or `static` surface. Probe only local
423
+ files/localhost, declared click/fill/press actions, declared expectations, and optional
424
+ expected tab order. Never auto-discover and click controls; never probe remote production or
425
+ authenticated flows.
426
+
427
+ ## 8. Blind critique, repair, and reframe
428
+
429
+ Now render sharp desktop/mobile (and filmstrip when motion matters), run deterministic checks,
430
+ and spawn a fresh `omd-eye`. Pass only the sanitized review brief required by
431
+ `protocol/human-design-loop.md`. On the normal graph, include applicable reference-landing criteria
432
+ and the `omd composition --check` result, never source identity or material; the eye treats validator
433
+ failure or missing/duplicate canonical axes or selectors as a blocker and verifies visible/probe-
434
+ supported landed correspondence. On the Figma structural-bypass route, pass the supplied frame
435
+ identity, snapshot/design-system/attribution hashes, and fresh `omd figma diff <frame-id>
436
+ <rendered-page> --json` result instead of composition/reference-synthesis evidence. A validator pass
437
+ never replaces visual/probe review. Reject wrong landings, interaction-only or token-only substitutes,
438
+ or contradictory behavior; UX task performance and visual composition remain co-equal. Route only
439
+ the canonical conditional list-detail non-primary-task and support-ticket temporal-window regressions
440
+ when applicable, with no leakage to other surfaces.
441
+ The sharp eye explicitly judges focal hierarchy and the lawful media/alternate mental-model
442
+ carrier across desktop/mobile, without demanding a photo, invented asset, or form above fold.
443
+
444
+ For showpiece only, spawn one additional fresh eye with exactly one dominant-technique lens
445
+ chosen from typography, motion, or graphics. It reviews that technique only. Do not create
446
+ a permanent specialist or multi-lens panel.
447
+
448
+ Send prioritized findings back to the hand for the smallest repair, then rerun affected
449
+ checks/renders/probe and `omd slop scan`. Confirmed source candidates are repaired; dismissed
450
+ ones have evidence; confirmed current candidates are rescanned; final untriaged and
451
+ needs-render counts are zero. If rendered evidence changes the problem, run `omd frame reframe --to
452
+ ... --because ...`; otherwise record why the frame survived.
453
+ If a finding requests copy repair, update the deck through omd-writer first, re-run
454
+ `omd copy --check`, and only then update source through the hand. Copy, claim, or action
455
+ changes invalidate the affected blind copy review and typography proof. The hand never
456
+ silently rewrites shipped copy.
457
+
458
+ ## 9. Ship
459
+
460
+ Verify project tests/build plus `omd check`, two clean copy checks around an independent
461
+ writer/editor pass, a blind typography proof before sketches and production-container
462
+ reproof before the visual checkpoint, responsive sharp/squint renders, applicable filmstrip, humanize review,
463
+ probe, `omd craft status`, `omd design --check` when applicable, `omd ref distance`, bounded target
464
+ convergence when a manifest exists, and `omd check --site` for multi-page output. The normal graph also
465
+ requires a fresh `omd composition --check`; the Figma structural-bypass route instead requires the
466
+ supplied snapshot/design-system/attribution artifacts plus a fresh passing `omd figma diff` for every
467
+ selected frame. Source-candidate triage has no untriaged or needs-render items and its
468
+ scan was rerun after repairs. Everything is clean or has an evidence-backed deliberate overrule.
469
+ When the run is an iteration with a before/after pair, form the pairwise blind-choose verdict:
470
+ blind-choose is the visual distinction signal only; applicable task probes, accessibility checks, and
471
+ declared viewport task evidence remain independent passing UX gates. Record the comparison; it never
472
+ replaces the blind typography, copy, or critique gates above.
473
+
474
+ ### Refinement rounds (RED/GREEN, evidence-driven)
475
+
476
+ For a confident/showpiece register — and always when the brief signals awards-level ambition — the
477
+ first shippable build is not the ship: it is round 0 of a bounded RED/GREEN loop. First write the
478
+ acceptance criteria (the GREEN target) from the frame and `theory/expressive.md` § "Slop-free is not
479
+ the same as distinctive": for example, names the template it resembles and departs from it; no two
480
+ competing primary masses; one clear first-read; slop scan clean; `omd ref distance` <= 0.6; carrier
481
+ present and register-fit; and the blind-choose after beats before. Any unmet criterion is RED.
482
+
483
+ Then iterate, leaving evidence every round — a round with no evidence does not count:
484
+ 1. The hand makes one concrete change, then captures sharp desktop/mobile renders into
485
+ `.omd/.cache/rounds/round-<N>/`, measures each visual criterion (glance hierarchy, `omd check`/slop
486
+ scan, `omd ref distance`, carrier read), and reruns every applicable declared task probe,
487
+ accessibility check, and required-viewport task evidence. Any UX invariant failure rolls the round
488
+ back.
489
+ Build and judgment stay separate.
490
+ 2. Spawn a fresh `omd-eye` — never the hand that built it — with only the sanitized acceptance
491
+ criteria and the two anonymized renders (this round's after and the previous build). It forms the
492
+ blind-choose visual distinction and reports which criteria are still RED. Record its verdict, the
493
+ still-RED criteria, and the evidence paths with `omd decision`; blind-choose cannot overrule a UX
494
+ invariant.
495
+ 3. Decide continue or stop from the round evidence. CONTINUE only while the applicable UX invariants
496
+ pass, blind-choose favors the after, RED criteria remain, and the round budget (default 3) is not
497
+ spent — then fix the single highest-leverage RED target with the same one-concrete-change discipline
498
+ as the craft checkpoints and re-measure. STOP on GREEN (every acceptance criterion met — done), a
499
+ UX regression (rollback), a visual regression (revert to the previous build), a plateau
500
+ (blind-choose tie while still RED), or the budget (keep the best valid build and report the
501
+ remaining RED). A round with no evidence does not count.
502
+ The loop is bounded and never an automatic retry: it advances only on measured visual improvement
503
+ while UX and beautiful UI remain coequal, and converges on GREEN or the budget. A quiet register may
504
+ ship after one pass with a recorded reason.
505
+ After all source and approved inputs stop changing, freeze and collect final evidence in the order
506
+ required by `protocol/human-design-loop.md`: run `omd source --seal <root>`, then `omd source
507
+ --check <root>`; build and collect every final check, test, declared/applicable probes,
508
+ fixed-viewport screenshot/render, and applicable motion filmstrip from sealed source; then run
509
+ `omd source --check <root>` again. For `product` or `mixed`, publish the task index with
510
+ `omd evidence tasks --input .omd/.cache/task-evidence-manifest.json`, then `omd evidence
511
+ tasks-check --json`. The protocol exclusively owns final-evidence fields, artifact roles/cardinality,
512
+ cache locations, publication behavior, and stale-bundle handling. The hand writes the required
513
+ manifest input at `.omd/.cache/final-evidence-manifest.json`, runs `omd evidence finalize --input
514
+ .omd/.cache/final-evidence-manifest.json`, then `omd evidence check --json`, and never directly
515
+ writes `.omd/final-evidence.json`. Any source or build mutation requires the protocol's reseal,
516
+ rebuild, rerun, and reindex sequence; the seal proves byte freshness only and does not prove
517
+ semantic copy/source fidelity.
518
+ Deliver the working artifact and briefly state the frame,
519
+ concept, structural choice, what the two craft renders changed, glance/critique outcome,
520
+ and any deliberate overruling. Do not release, deploy, or wait for further approval unless
521
+ the user asked for it.