oh-my-design

What you get back

Three artifacts, all of them files in your repository:

In v2.0.0 every layer above is a file you can edit — the philosophy, the presets, the gates, the references — and the next build has to justify itself against whatever you put there. Taste you cannot inspect cannot be improved.

Full walkthrough: oh-my-design.kr/docs/en.

How the system gets derived

A screen is the last step, not the first. The harness makes the agent build a system it then has to answer to:

philosophy → decision table → tokens → component contracts → layout grammar → build → render critique → DESIGN.md

Each step constrains the next. A principle has to name what it sacrifices — a principle you cannot argue with is decoration. Every decision gets an id (D-<principle>-<n>) and one line of rationale. Tokens carry that id back, so a value with no decision behind it is a gate failure, not a style preference. The chain is specified in skills/omd-autopilot/references/derivation-chain.md.

Here is what that looks like in a DESIGN.md the harness actually produced (benchmarks/ui-resolve-bench/e2e/onzip/DESIGN.md, 644 lines, generated end to end):

### Principles
- Accent is a signal — terracotta on linen, used for the primary action,
  selected chip, and focus ring, never a full-card wash (D-P2-4).

### Semantic tokens
- **color.accent**: `#8B4529` — Terracotta signal. D-P2-4. 6.1:1 on paper.
  Area budget under 5 percent.

The same id appears in the principle and in the token. That is the whole idea: you can start at any value in the system and walk back to the sentence that caused it.

Component contracts go one level further — they cite the preset they inherited from, and they state which interaction states deliberately do not apply, with the reason:

### Component: product-card
**Semantics:** P-CM-01. Price is the heaviest text. Whole-card link, no inner
competing CTA. Painted hover uses four-sided space.4 (P-FN-07).

| State | Applicability | Reason |
|---|---|---|
| disabled | not-applicable | A sold-out item still opens its detail page;
                             stock is a badge, not a disabled card. |
| loading  | not-applicable | Card media uses explicit width and height; the
                             card itself is not a pending control. |

P-CM-01 and P-FN-07 are entries in the preset catalog, so the build did not invent a card from zero. shadcn/ui gives you the structure; the preset says which values must come from your decision table instead of a library default.

Two of the numbered gates exist specifically to keep this honest — GS7 fails a token that carries no decision reference, and GS8 fails a component built from scratch when a matching preset existed. Both are in slop-gates.md alongside 54 other checks.

Verify any of this yourself

Nothing above needs the CLI installed to check — these are files in this repo:

What is oh-my-design?

oh-my-design (OmD) installs local design workflows into the coding tool you already use. Claude Code, Codex, and OpenCode receive reusable skills and specialist roles; Cursor receives native Agent Skills plus a focused project rule that applies the same DESIGN.md. New design-system creation targets the vendor-neutral DESIGN.md Core v2: a concise portable contract that remains useful when pasted into a generic chat or attached to Claude Design/Open Design, with optional structured evidence under .omd/system/. The package also includes 500+ quality-graded company references. Existing reference formats remain readable during the lossless migration window. Core install and local workflows need no separate API key, daemon, or MCP server; inference stays inside your existing coding-agent session. The optional claude-design skill opens your logged-in claude.ai/design session in Chrome.

DESIGN.md Core v2

The visible file starts with the project, not with OmD metadata. It has no YAML frontmatter, generator stamp, model name, verification tier, or internal path. Seven stable semantic anchors cover experience, foundations, typography/assets, components/states, layout/platforms, content/locales, and governance.

When an adopted profile: portable-core manifest and graph.json are valid and hash-bound, the graph is the machine source of truth and DESIGN.md is its portable projection. A staged migration-candidate manifest remains non-authoritative: the named source DESIGN.md stays canonical until explicit adoption. Without those sidecars, Markdown that passes omd design-md validate is still a complete brief for a human or an unfamiliar design/coding tool. A seven-anchor file may be recognized as structural Core while failing the stronger Portable Core usefulness gate, for example when no primary task is evidenced. Unknown values stay absent instead of becoming plausible defaults.

Browse the adopted system on a local port — tokens with the decision that produced them, component state matrices including the states that deliberately do not apply, contrast measured against the pairs the system promised, and the preset lineage:

npx oh-my-design-cli@latest book              # serves on :6060, re-reads on refresh
npx oh-my-design-cli@latest book --static ./out   # standalone HTML for handoff

Inspect or stage a legacy migration without overwriting the source:

npx oh-my-design-cli@latest design-md inspect ./DESIGN.md
npx oh-my-design-cli@latest design-md validate ./DESIGN.md
npx oh-my-design-cli@latest design-md migrate ./DESIGN.md --out-dir .omd/migrations/core-v2

The migration is dual-read/single-write: legacy 13/15/16-section and unmarked documents remain readable, while new generation and refactoring write Core v2. A staged migration must preserve every source segment as a mapped Core decision or an opaque extension and report dropped=0. See the migration plan.

If repository facts or reviewed user decisions enrich the staged graph before review, rebind the unchanged migration ledger with the provider-free helper; never hand-edit report hashes:

npx oh-my-design-cli@latest design-md rebind-migration <migration-dir> \
  --enrichment <safe-partial-enrichment.json> --provenance <provenance.json> \
  --coverage <coverage.json> --out-dir <fresh-rebound-dir>

Use --graph <complete-enriched-graph.json> only when an external tool already produced the whole graph. The safer --enrichment form starts from the lossless candidate internally and forbids writes to opaque extensions, projection bindings, and schema identity.

Adopting a graph-backed project system is an exact, receipt-gated transaction:

npx oh-my-design-cli@latest design-md prepare-review <graph.json> \
  --provenance <provenance.json> --coverage <coverage.json> \
  --out-dir <fresh-review-dir>
npx oh-my-design-cli@latest design-md approve-review \
  <fresh-review-dir>/review-request.json --reviewer <project-owner-id> \
  --out <fresh-review-receipt.json> --authority-transition-approved
npx oh-my-design-cli@latest design-md compile \
  <fresh-review-dir>/input-graph.json \
  --provenance <fresh-review-dir>/provenance.json \
  --coverage <fresh-review-dir>/coverage.json \
  --review-receipt <fresh-review-receipt.json> \
  --out-dir <fresh-package-dir-outside-project> --adopt
npx oh-my-design-cli@latest design-md prepare-checkpoint \
  <fresh-package-dir-outside-project> --reviewer <project-owner-id> \
  --out <fresh-project-checkpoint.json> --authority-transition-approved
npx oh-my-design-cli@latest design-md adopt \
  <fresh-package-dir-outside-project> --project-root <project-root> \
  --checkpoint-receipt <fresh-project-checkpoint.json>

An owner-reviewed reference reconstruction uses the same public commands with