Oh My Design

A design process for coding agents — not a visual style. OMD makes the model earn each decision: question the brief, gather evidence, write real copy, prove typography, compose deliberately, build once, inspect the render, and reframe.

한국어

Built with OMD — in one shot

The landing page above was generated by OMD itself from a single one-shot prompt — the visual output was not hand-tuned. It is live at 3x-haust.github.io/oh-my-design, and its source is in example/.

What it is

Here, “design like a human” means accountable judgment, not a signature look. The goal is a repeatable process; the result can be quiet, expressive, conventional, or strange. What stays constant is the chain of decisions behind it.

Oh My Design (OMD) keeps a coding agent from jumping straight from a request to polished UI. It asks what problem is being solved, records evidence, separates writing from layout, compares anonymous structures, and critiques the rendered output without exposing the reviewer to the builder’s rationale.

The durable loop is:

brief → evidence → copy → typography proof → composition contract → isolated structure → one production build
      → rendered critique and interaction evidence → reframe

OMD runs inside Codex and Claude Code. It ships six user-facing skills, nine internal pipeline agents, a local omd CLI, design theory and recipe packs, and a durable project record under .omd/.

Requirements

• Node.js 22.18 or newer (the CLI runs the TypeScript entrypoints directly)
• Claude Code, Codex, or both, with the host config directory already present
• A browser provider: browser-rs v0.1.10 is preferred on its two supported platforms; Playwright + Chromium remains the required fallback for rendering, probing, and typography proofs (see below)

Install

npm — global CLI (recommended)

npm install -g @3xhaust/oh-my-design
oh-my-design install    # copy skills + agents into every detected host and patch its config
oh-my-design doctor     # verify the host install
omd doctor              # verify the runtime, Chromium, project write access, and the theory pack

oh-my-design install --host claude|codex scopes install, doctor, and uninstall to one host. uninstall reverses exactly what install did and never touches your .omd/ directory. Host installation also attempts browser-rs afterward and reports present, installed, unsupported, or failed; a browser-rs failure does not roll back an otherwise healthy OMD/Playwright host installation.

Install the scoped package @3xhaust/oh-my-design. The unscoped oh-my-design on npm is an unrelated project.

Claude Code — plugin marketplace

/plugin marketplace add 3x-haust/oh-my-design
/plugin install oh-my-design@omd

Then open a session and run /ultradesign.

From source (contributors)

git clone https://github.com/3x-haust/oh-my-design
cd oh-my-design
npm install
node bin/omd-install.ts install    # copy skills + agents into detected hosts
node bin/omd.ts doctor

Browser provider and Chromium (after global installation)

After globally installing @3xhaust/oh-my-design, OMD prefers the browser-rs MCP provider for interactive reference research, user-directed region captures, and visual QA. It is a deliberately narrow v0.1.10 integration, not a claim of universal browser compatibility:

| Platform | browser-rs state | Exact SHA-256 | | --- | --- | --- | | Darwin arm64 | Supported; default interactive provider when healthy | 9a5895fc2f07b1010226d30f081d678fa2edcc15dd6f24cdf10074cfe1573749 | | Linux x64 | Supported; default interactive provider when healthy | 792ca76e5ce0423968763556e110900a3aa65737fc6227724914aa137e972589 | | Any other platform | Unsupported; no browser-rs download | Use the Playwright + Chromium fallback below. |

The managed binary, when installed, is $HOME/.local/share/oh-my-design/browser-rs/v0.1.10/browser-rs with a verified receipt.json. OMD verifies the exact checksum before publishing it. Resolution is OMD_BROWSER_RS_BIN, then browser-rs on PATH, then that receipt-owned target. OMD never overwrites a foreign override/PATH binary or an unreceipted/tampered managed-target file, and oh-my-design browser uninstall removes only matching OMD-owned receipt-and-digest bytes.

# Explicit provider lifecycle. `doctor` exits 1 when the selected provider is not healthy.
oh-my-design browser install
oh-my-design browser doctor --json

# After global package installation, provide your own equivalent local HTML fixture.
oh-my-design browser smoke --fixture /absolute/path/to/local-probe.html --out /tmp/omd-browser-rs-smoke.png

# Preserves foreign, unreceipted, or tampered bytes rather than deleting them.
oh-my-design browser uninstall

From a source checkout, use the proven TypeScript entrypoint instead of assuming a global bin:

node bin/omd-install.ts browser install
node bin/omd-install.ts browser doctor --json
node bin/omd-install.ts browser smoke --fixture test/fixtures/probe.html --out /tmp/omd-browser-rs-smoke.png
node bin/omd-install.ts browser uninstall

On a supported platform, missing, unowned, or bad browser-rs is unhealthy; first repair the intended binary/ownership (or intentionally set OMD_BROWSER_RS_BIN), then rerun browser doctor. On an unsupported platform, provider health is good only when the Playwright module and Chromium fallback are both available. Existing omd render and omd probe are the deterministic Playwright fallback after browser-rs initialization or capability failure.

The installer does not install Chromium. If omd doctor reports Playwright unavailable or its Chromium executable missing, install what the report names, then re-check:

npm install -g playwright
npx playwright install chromium
node bin/omd.ts doctor

Chat-first LEGO reference assembly

OMD treats a reference as a set of traceable bricks selected for the approved brief, not as a whole-site style to copy. The canonical sequence is:

brief blocks → fragment inventory → brick analysis → candidate assemblies
→ selected assembly → clean-room composite → production usage ledger → final provenance report

The conversation is the interface. Codex/Claude shows the candidate table and the final Korean/English provenance table directly in chat. There is no omd-board executable, DESIGN UI, HTML board, or PNG board. reference-board-v1 is only an internal, validated .omd/reference-board.json record; the package exposes only the public omd and oh-my-design bins.

Behind the conversation, an agent can capture a component, validate the evidence, render the chat-ready candidates, and bind the user’s chat choice:

# Internal agent operations; the person reviews the resulting Markdown in chat.
omd ref add <url-or-local-page> --as <component> --selector '<css>' --blueprint --shot
omd ref import-image ./local-fragment-input.json
omd ref check
omd ref candidates
omd ref select <candidate-id>
omd ref check

omd ref candidates emits a Korean-first Markdown table with source site/page, captured UI or image part, proposed route/component, take, avoid, and adaptation. It does not open a board. The selection is hash-bound to both validated raw evidence and a sanitized reference-assembly-v1 projection.

Captures, clean-room composition, and final traceability

A component brick is a selector-scoped blueprint plus a local PNG. For Pinterest-like galleries and similar sources, browser-rs performs the user-directed region capture and omd ref import-image imports that local PNG. The input records absolute HTTP(S) sourcePage, optional sourceImage, human-readable captureRegion, optional cropBox, licenseStatus (allowed, restricted, or unknown), rights notes, visual role/principles, and canonical provenance time. OMD does not scrape, hotlink, download remote source images, or ship their pixels.

The composer receives only the sanitized selected assembly: transferable structure/principles/geometry, never a source URL, source selector, provenance, screenshot, local source image, or raw pixels. The assembly intentionally retains its target targetSelector so implementation can map a selected part to its destination. .omd/reference-composite-lineage.json records either a hash-bound generated clean-room composite or an unavailable reason. When host image generation is available, two or three independent concept drafts may be generated concurrently and compared; no image-provider or API-key layer is added. When unavailable, use a CSS/SVG/evidence fallback. Existing motion, prefers-reduced-motion, and WebGL/3D gates are unchanged.

During implementation, each selected source part receives a used, rejected, or anti-reference row in .omd/reference-usage.json. .omd/reference-report.md and the final chat response contain Korean and English tables with: status; source site/page; exact captured UI/image region; shipped route/component/selector; borrowed properties; explicitly non-borrowed properties; transformation; and production evidence path, selector, and verification note.

See docs/lego-reference-audit.md for the code-backed Korean/English capability audit, source paths, provider limitations, and verification evidence.

The human design loop

omd-ultradesign coordinates this order:

1. Preflight — pin the project directory, run omd doctor, inspect the repository, and route Figma briefs to omd-figma.
2. Frame — interrogate the brief and record the problem, reframe hypothesis, primary task, frequent action, and costliest error with cited evidence.
3. Concept — choose a generator, visual register, typography direction, and the intended memorable moment.
4. Research — collect measured references across the domain, competitors, audience language, components, typography, and relevant motion.
5. Write copy — a dedicated writer creates a fact-traceable copy deck before layout begins.
6. Review copy blind — a fresh reviewer sees the brief, copy, fact ledger, and voice evidence, but no render, code, layout, rationale, or authorship.
7. Prove typography blind — a typesetter renders layout-neutral actual-copy specimens at 1280×900 and 390×844; a fresh eye reviews them without page structure or rationale, then the typesetter revises and rerenders.
8. Compose deliberately — a fresh composer defines the experience spine, one dominant focal anchor, mass/rhythm, a lawful mechanism carrier or explicit alternate, responsive recomposition, and candidate axes. omd composition --check verifies input freshness.
9. Diverge structurally — isolated agents receive the same composition contract and render fixed desktop/mobile plus supplemental full-page continuity proofs for each candidate.
10. Choose blind — a fresh selector scores eight frozen 0–4 dimensions, rejects contract violations or any dimension below 2, and never equates a form above the fold with CTA reach.
11. Build once — one selected structure becomes the production implementation. The builder does not generate another candidate set.
12. Reflect while building — the builder records a semantic checkpoint, re-proves type in the selected desktop/mobile containers, then records the visual checkpoint before optional motion.
13. See the result — desktop and mobile renders, squint views, applicable filmstrips, deterministic checks, and declared local probes supply the review evidence.
14. Triage source candidates — after production source exists, a read-only scan proposes narrow candidates. The coordinator resolves each through rendered context; candidate presence alone is not a failure.
15. Critique, repair, and reframe — a squint-only glance reports hierarchy first; a separate sharp reviewer judges craft and sanitized candidates, then repairs are rendered, checked, and rescanned.
16. Ship — project tests, build checks, applicable design gates, and unresolved findings are reported with their evidence.

Figma files and explicit visual targets already supply structural decisions, so the loop may skip structural divergence in those routes — but it records why.

Skills

Six user-facing skills. Canonical names use the omd- prefix; Codex shows them as (omd) <skill>, and the Claude marketplace flavor references them as oh-my-design:<skill>.

| Skill | Use it for | | --- | --- | | omd-ultradesign | Run the complete human design loop for a page, app, dashboard, blog, landing page, or redesign. | | omd-figma | Pull a Figma file, synthesize its system, implement frames, compare responsive pairs, and report measured fidelity. | | omd-scout | Build a measured LEGO fragment inventory and chat-ready Markdown candidate/usage tables without designing or implementing. It closes consequential coverage gaps and reports uncertainty instead of filling quotas. | | omd-critique | Review an existing design without changing it; group deterministic findings by root cause and judge rendered craft. | | omd-humanize | Preserve facts while locally repairing sound discourse or reconstructing a misshapen message from verified facts, voice, and surface action. | | omd-coach | Read accumulated check history, identify recurring problems and trends, and suggest what to practise next. It does not read taste records. |

Internal pipeline agents

Nine agents are implementation details of the loop, not public commands. They do not pin a concrete model — each inherits the model selected for the session.

| Agent | Responsibility | Write boundary | | --- | --- | --- | | omd-framer | Questions the brief and records an evidence-backed frame. | Read-only; records through the frame CLI. | | omd-scout | Researches measured evidence for pipeline coverage. | Read-only; records through reference CLI commands. | | omd-writer | Writes or repairs the copy deck and fact ledger. | Only .omd/copy-deck.md. | | omd-typesetter | Builds and revises the pre-structure actual-copy typography proof. | .omd/type-proof.md and .omd/.cache/type-proof/. | | omd-composer | Converts sanitized evidence into the fresh composition contract before divergence. | Only .omd/composition.md. | | omd-sketch | Produces one isolated grayscale structural candidate with real copy. | Only its cache candidate directory. | | omd-hand | Builds the selected structure and records two craft checkpoints. | Production repository and declared OMD records. | | omd-glance | Reports hierarchy from squint renders only. | No writes. | | omd-eye | Selects anonymous structures, reviews copy or typography proof blind, or critiques sharp renders. | No writes. |

Claude Code can enforce declared denied tools in agent metadata. Codex agent files have no equivalent tool-restriction field, so read-only limits there are prompt contracts rather than a hard sandbox. OMD does not describe those contracts as filesystem isolation.

Evidence boundaries and artifacts

| Stage | Durable output | Boundary | | --- | --- | --- | | Frame | .omd/frame.md | Claims need a user sentence, research line, datum, or named observation. Internal OMD instructions are not evidence. | | Research | .omd/refs/*.json | Builders receive measurements and principles, not screenshots to imitate. Scouting stops on decision/component coverage, independence, and source trust — not a universal capture count or gallery quota. | | Copy | .omd/copy-deck.md | Each shipped factual claim points to a verified fact ID. fixture facts test density only; open facts cannot support shipped claims. | | Blind copy review | review handoff | The reviewer cannot inspect renders, source, layout, frame, decisions, or authorship and does not edit the deck. The writer applies the review, then omd copy --check runs again. | | Typography proof | .omd/type-proof.md; specimens in .omd/.cache/type-proof/ | Actual target-language copy proves roles, source/licence, glyph coverage, requested/computed family and weight, axes, fallback/loading, wraps/clips, and rejected alternatives at both viewports. Browser evidence does not identify the physical font used for each glyph. | | Composition contract | .omd/composition.md | A clean-room composer receives sanitized evidence and defines a focal anchor, CTA path, mechanism carrier/alternate, and responsive relationships without requiring a photo or form above the fold. Exact hashes make stale inputs fail. | | Structural sketches | .omd/.cache/sketches/<id>/ | Each candidate supplies fixed 1280×900 and 390×844 acceptance renders plus full-page desktop/mobile continuity evidence. Full-page captures inform dependency/rhythm only. | | Blind choice | .omd/taste/preferences.jsonl | The selector sees anonymous renders and sanitized task context, not candidate rationale or authorship. omd choose stores the selected candidate and its reason as an agent choice. | | Production build | repository source | One builder implements one selected structure and preserves the copy deck. Separate omd decision entries record implementation reasons in .omd/decisions.md. | | Production evidence | .omd/attribution.md | The builder records the sources behind shipped tokens, motion, composition, and graphics. | | Craft checkpoints | .omd/craft.jsonl | One semantic and one visual checkpoint each record an observation and the concrete change it caused. | | Source-candidate triage | raw JSON in .omd/.cache/; reasoning in .omd/decisions.md | omd slop scan exposes controlled signals without source excerpts. needs-render is transitional; final untriaged and needs-render counts are both zero. | | Rendered review | cache renders, filmstrip, probe output | The squint reviewer sees only squint renders. The sharp reviewer receives sanitized task context plus measured outputs, never the builder’s rationale. | | Reframe | .omd/frame.md revision | omd frame reframe appends what the render revealed instead of erasing the original framing. | | Final source seal | .omd/source-seal.json | omd source --seal records final copy/type/composition and sorted production-source hashes; --check proves byte freshness only, not semantic fidelity. |

Human approval checkpoints are separate from craft checkpoints. Projects default to checkpoint: none; concept, structure, or both can be enabled in .omd/config.json.

Stack routing

Every builder follows the same precedence:

explicit user request
  > existing repository stack and toolchain
  > React + Vite + TypeScript for a truly blank greenfield

Existing vanilla HTML is an existing stack. An unrecognized package or toolchain is investigated and preserved, not treated as an empty repository. Plain HTML for a new greenfield project is used only when the user explicitly asks for it. Greenfield scaffold dependencies are allowed; existing projects should not receive unnecessary ones.

Verification stack

OMD combines deterministic checks with rendered review.

| Layer | Commands and evidence | | --- | --- | | Contracts | omd copy --check validates deck structure and fact references. omd composition --check validates composition sections and input freshness. omd source --seal/--check validates final approved-input/source bytes without claiming semantic fidelity. omd design --check validates design-contract coverage. | | Typography proof | Layout-neutral desktop/mobile specimens run before sketches; selected-container reproof runs after semantic structure and before the visual checkpoint. Copy, font/file, weight/axis, or container-width changes invalidate the proof. | | Render evidence | omd render captures the exact viewport by default; --full-page is supplementary continuity evidence, --squint isolates hierarchy with grayscale and blur, --filmstrip captures load-time frames. | | Interaction | omd probe executes only a declared, safe local plan and reports expectation or tab-order failures. | | Source candidates | omd slop scan [root] [--json] reads supported production source without writing it. Candidates require contextual triage; they are not omd check warnings, scores, or authorship claims. | | Design lint | omd check evaluates system, a11y, slop, motion, and ux conditions. Contrast and hit-area rules are errors; slop and other quality-floor rules are warnings where authored that way. Any finding exits 1, so it is usable in CI. | | Site consistency | omd check --site <dir> or multi-page positional checks report cross-page ladder and token drift. | | Reference distance | omd ref distance <page> compares measured invariants against saved references and reports how close the build is, as an advisory fidelity signal — it never blocks shipping. | | Figma fidelity | omd figma pull, system, and diff connect a Figma snapshot to a measured implementation report. Requires export FIGMA_TOKEN=…; omd doctor treats a missing token as optional. | | Visual target | omd target set <image-path-or-url> --as <name> and omd target diff run a bounded image comparison against a registered PNG target. A URL must be a direct HTTP(S) image URL. | | Performance | omd lighthouse <lighthouse-report.json> gates a Lighthouse JSON report against a performance budget (default: performance ≥ 90 and Core Web Vitals within Google's "good" thresholds). You run Lighthouse (npx lighthouse <url> --output=json); OMD gates its report and exits non-zero on a breach. |

Slop findings are a quality floor and warnings; they do not prove a design was generated by AI. A written overrule records intent but does not suppress a finding or change command status. Rendered critique remains necessary — a rule engine cannot safely judge optical balance, composition rhythm, typography craft, or whether the memorable moment belongs to the concept.

Interaction applicability

The copy deck declares exactly one interaction scope.

| Scope | Required evidence | | --- | --- | | stateful | Primary and recovery copy, .omd/probes/primary.json, and .omd/probes/recovery.json. Both probes run. | | navigation-only | Primary copy and the primary probe. Recovery copy and recovery probe are N/A with concrete reasons. | | static | Primary copy. Recovery copy and both probes are N/A with concrete reasons. |

Loading, empty, error, success, disabled, offline, and recovery states are designed only when the surface can reach them — the harness does not add fake states to satisfy a checklist. Probe plans use declared click, fill, and keypress steps with explicit expectations, are limited to local files and localhost/loopback URLs, and reject authenticated, remote, destructive, or undeclared actions. OMD never discovers controls and clicks them automatically.

Project state

Durable, reviewable records live directly under .omd/:

• frame.md, copy-deck.md, type-proof.md, composition.md, source-seal.json, design.md, decisions.md
• attribution.md, motion-spec.md, craft.jsonl, config.json
• refs/*.json, reference-board.json, reference-selection.json, reference-composite-lineage.json, reference-usage.json, reference-report.md, declared probes/*.json, taste/preferences.jsonl, and history.jsonl

Generated IR, renders, filmstrips, sketch candidates, probe results, and scratch output live under .omd/.cache/; deleting the cache should not erase design intent. oh-my-design uninstall removes installed OMD files and config changes while preserving the project’s .omd/ directory.

CLI reference

A compact map of node bin/omd.ts --help:

omd ir <page> [-o file]
omd render <page> -o shot.png [--viewport WxH] [--full-page] [--squint] [--filmstrip]
omd probe <page> [--plan path] [--json] [--out path]
omd check [<page>|--ir file] [--json] [--category slop] [--no-log]
omd check --site <dir>
omd check <page1> <page2> ...
omd slop scan [root] [--json]
omd coach
omd composition --check [--json]
omd source --seal [root]  |  omd source --check [root] [--json]

omd frame show
omd frame set --problem P --reframe R --why EVIDENCE [--task T --frequent-action A --costliest-error E]
omd frame reframe --to "..." --because "..."
omd frame generator --set "metaphor"
omd choose c1 c2 --chose c2 --why "..."
omd decision "what" --why "why"
omd taste record "subject" --kind selection|praise|rejection|overrule --evidence "verbatim" --from-user
omd taste profile [--all]
omd config set checkpoint none|concept|structure|both  |  omd config show
omd craft checkpoint semantic|visual --render path --observed "..." --changed "..."
omd craft status [--json]

omd ref add <url|file> --as <component> [--selector "css"] [--image] [--blueprint]
omd ref list  |  omd ref distance <page>
omd ref principles <source> --as <component> --add "..."
omd ref show <source> --as <component>
omd ref check [manifest] [--json]
omd ref import-image <input.json> [--json]
omd ref candidates [manifest]                 # chat-ready Korean-first Markdown; no board UI
omd ref select <candidate-id> [--json]

omd design  |  omd design --check
omd copy --check [--json]
omd pack dir | list | <relpath>
omd doctor

omd figma pull <file-url>  |  omd figma system  |  omd figma diff <frame-id> <page-or-url>
omd target set <image-path-or-url> --as <name>  |  omd target list  |  omd target diff <page> [--target <name>] [--viewport WxH] [--threshold N] [--json]

Architecture and contributing

Prompt source of truth:

• src/agents/*.agent.yaml
• src/skills/omd-*/SKILL.md

Generated outputs — do not edit directly; npm run build regenerates them for direct hosts and plugin packaging:

• agents/, skills/, dist/

Edited directly: core/, bin/, adapters/, test/, evals/, scripts/, README.md, README.ko.md, and the theory and recipe packs under core/.

Before submitting a change:

npm test
npx tsc --noEmit
npm run build

New linter rules must remain narrow, include positive and negative tests, and always use warning severity.

Limits and trust

• The prompts define a disciplined workflow; they do not guarantee strong design without real project evidence, usable copy, rendered inspection, and project-specific validation.
• Probes are for local, non-authenticated, non-destructive paths — not a general browser automation layer.
• Reference distance, lint, and image diff are measurements. They inform judgment rather than replace it.
• Plugin/marketplace manifests are shipped artifacts; the from-source direct installer is the path covered by install-to-doctor regression tests.

Licensed under the MIT License.