oh-my-design

Oh My Design

AI that designs like a human. Give OMD one request. It researches, compares real material, chooses a direction, builds, renders, and repairs internally. The model adapts its methods to observed evidence rather than requiring routine reference or draft approval; account access and external-action permissions remain separate.

Native Pi uses the same production engine for normal autonomous execution and explicitly enabled private developer evaluation. See usage, private evaluation and versioned calibration. Technical integration is tested; human-level quality claims still require real held-out blind ratings.

한국어

Built with OMD — in one shot

The landing page was generated by OMD itself from a single one-shot prompt — the visual output was not hand-tuned. View it at 3x-haust.github.io/oh-my-design.

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.

The design practice contract makes this concrete inside each selected method. Behavioral checks remain distinct from claims about human-level quality. Local research and development notes under /docs/ are not tracked or published with the repository.

Concept exploration follows the content: a page can revolve around one strong idea, and alternatives can share a brand palette. Visual drafts help choose a direction even when the delivered page is entirely HTML and CSS. OMD compares feasible directions for their visible design and task fit; passing a build or fidelity check alone does not establish visual quality.

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 adaptive rather than a mandatory stage checklist:

outcome + facts + risk → selected methods and reasoned skips → one production build
                       → real-surface interaction and visual evidence → causal repair or reframe

Task-critical product work can select a task-flow benchmark, semantic entry-surface contract, and source-bound browser plan. Marketing work can select a different evidence, copy, composition, and motion path. OMD preserves the user's model choice in both cases. It derives evaluator selectors from current task records instead of accepting a caller-authored answer key, and it does not invent a product capability merely to make an under-specified greenfield concept look distinctive.

OMD runs inside Codex, Claude Code, and hosts that implement the public Pi extension API. 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.19 or newer (the CLI runs the TypeScript entrypoints directly)
• Claude Code, Codex, or a Pi-compatible host
• 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.

Pi-compatible hosts — extension package

OMD is a standard Pi package. Pi and API-compatible forks such as Senpi load the same extension and canonical skills; OMD does not probe or launch a Senpi executable.

pi install npm:@3xhaust/oh-my-design

For a compatible fork, use that host's package-install command with the same npm package. The extension registers /omd for a project doctor check and the structured omd_cli tool for the existing OMD CLI. Compatibility requires the public Pi extension/package API; fork-only APIs are not used.

Pi's omd_cli does not need an external activation file. First run omd route validate --input .omd/.cache/route-input.json --json, repair the named input errors, then publish with route classify. An input validation error is not missing host authentication.

Three-layer enforcement connects declaration → stage/owner procedure → automatic refusal. The coordinator inspects each brief, delivers its contracts, then runs omd brief <stage> --check --json. Plain brief inspection is not entry permission. Production entry uses the full production readiness validator; routed recipe add checks all targets before writing, even outside Pi. Pi's public tool_call / message_end hooks ensure native write/edit application mutations and arbitrary bash wait for current pre-production inputs; research inputs and directly owned design documents remain writable. The completion hook withholds an unverified final success claim. OMD commands are queued per project to prevent sibling calls from competing for the mutation lock. During a source-writing turn, repairable terminal failures keep triggering repair/recheck follow-ups while the named work pointer or authored evidence changes. Two consecutive unchanged failure states stop the loop; authority failures and user aborts do not retry. Message replacement semantics are verified against Pi 0.85.1; forks must support that public event behavior, not merely expose an on function. An explicit full-build request with the packaged skill also continues a checked selected stage on an existing route after a failed publisher; research-only or stop-at-stage requests do not. Run /omd after /reload; hook-less compatible hosts explicitly report that only CLI checks exist. Hooks are workflow gates, not an OS sandbox or proof of design quality. External processes/custom mutation tools are outside this hook boundary, and streamed draft text may precede final validation. Independent reviewer authorization is still required by implementation final evidence; Pi does not manufacture it. After upgrading, revalidate/reclassify the original approved route with the current build if old build/skill authority is stale. stage status.completed means artifact presence only.

Reference research is saved separately: .omd/refs/domain/research.json for similar-service screens, features and flows, and .omd/refs/design/research.json for composition, type, density and component craft. omd ref discover-plan --json suggests screen galleries such as Mobbin/Page Flows/UI Bowl/Pinterest for product UI and website galleries such as Siteinspire/Pinterest for marketing. Verify free access per entry; on blocked/login/paid access, use another public source without purchases, trials or MCP installation. Free viewing does not grant reuse rights. Record the inspected screen, discovery entry and concrete quality reason, not just a prestigious gallery name. Visit gallery items with omd ref navigate <item-url> --lane design --json; their captures stay under .omd/discovery/design/. Retain the observed original or capture the loaded UI image with ref add <item-url> --lane design --selector <img-css>, not the wrapper chrome; cropping is optional. Use omd schema reference-research --json, omd ref research-set --input <input.json> and omd ref research-check --json to publish/check both files and their aggregate consistency receipt. Capture PNGs and metadata directly into their own folders with ref add --lane domain|design or lane on each add-batch entry. Inspect them with ref list --lane domain|design --json; domain captures do not silently enter the visual board. Current v7 research binds source and gallery-entry PNGs to native capture JSON, keeps domain and design lanes separate, and records source-specific market coverage when a market is explicit or a Korean-language user brief starts Korean-first reference research. That default never dictates a country aesthetic. Korean welfare discovery now starts with actual service-name searches on the public Daum web endpoint; Korean-language .com products can qualify, while English foreign government domain captures are refused until current local-domain research validates the local coverage and any global fallback. Locally authored capture files or --from-user alone do not unlock that fallback. Selector-scoped captures check the full page's visible-language balance. A homepage is not an inspected entry, and a different original source must appear in the gallery's observed outbound links. Historical v5 remains readable with search-only requirements; v6 retains its search-or-direct-root contract. Reuse valid captured evidence only when current validators permit, then publish through v7 without relabelling historical bytes. Domain/design hosts, final redirects and PNG evidence must be independent. Non-user discovery must be a supported public gallery item, not a service page labelled as a gallery. Public Pinterest, Dribbble and Behance items do not require UI Bowl's paid MCP. Free viewing is checked per item. Design sources declare visual-direction or component-support with observed composition, type, density, imagery, transfer and exclusions. Current v7 needs at least two independent visual-direction service families from distinct inspected gallery items with different PNG bytes, and both directions must participate in the current board. Tracking URL variants, renamed captures, and unused screenshots do not count. Every board candidate uses visual-direction evidence; support-only documentation cannot complete the lane. Inspect previews in .omd/refs/design/README.md. These are provenance/role checks, not a machine certification of beauty.

Current v7 requires native acquisition evidence, not query prose. omd ref search --input <json> accepts {lane, query, url, queryParam} and records a fresh-browser GET, actual links/capture or failure. Put its returned receipt in the lane's searches. Every query must match an execution and retained non-user sources/entries must occur in observed links and have separate native visit captures. Failed attempts can accompany a usable free alternative. HTTP 200 alone is not search quality. The executor accepts public Google/Bing/DuckDuckGo search pages with queryParam: "q"; use task/pattern and gallery site: queries. Arbitrary service pages with invented query parameters are rejected. When search is blocked, v6/v7 also allow signed direct-public list discovery through omd ref navigate. New search-v2 and direct-entry-v3 records are project-signed and tamper-evident, but they are not