DESIGN.md is a structured markdown file that defines your project's brand spec — tokens (colors, typography, spacing, radius), voice, narrative, principles, personas, states, and motion. AI coding agents (Claude Code, Codex, OpenCode, Cursor) read it as authoritative context before generating any UI, so the output looks like your brand instead of generic 'modern minimalist' slop.

How does oh-my-design work?

Run `npx oh-my-design-cli install-skills` once in your project. It installs 15 skills (core flow + live-capture + asset + the v0.2 agent layer: orchestrator, kr-writer, locale-adapter, designer-review, final-qa, codex-image), 16 sub-agents (master orchestrator + 15 specialists), 4 hooks, and 100+ reference DESIGN.md files. After restarting your AI coding agent, you just talk in natural language — skills route to the right sub-agents automatically.

Does it call any AI provider during install?

No. The install is a pure markdown copy — zero API calls, zero data leaves your machine. Your AI coding agent (Claude Code, Codex, OpenCode, or Cursor) is the inference layer; install just teaches it where to look.

Which AI coding agents are supported?

Claude Code, Codex, OpenCode, and Cursor (via .cursor/rules). The skill markdown files are agent-agnostic; hooks ship for Claude Code specifically.

What is the design harness?

The omd-harness skill runs a 10-phase design pipeline (Discovery → Research → IA → Wireframes → Design system → Components → Asset sourcing → Microcopy → Validation → Handoff). It dispatches sub-agents in parallel where independent, asks 3 mandatory user checkpoints, and emits a v0/Cursor-ready package. Trigger it by saying things like 'design the entire onboarding from scratch' or '/omd-harness '.

Yes — MIT licensed, open source, no signup, no API key, no paid tier. The references in the bundle belong to their respective companies and are reproduced for educational reference only.

oh-my-design v1.4.0 (2026-05-15)

Architectural refactor — single-source registry replaces 5 hand-maintained maps.

Three consecutive KR-10 batches (78→88, 88→98, 98→108) lost data because the sub-agent missed one of 5 hand-maintained data maps (route.ts, logos.ts, tokens.ts, homepage-urls.ts, design-systems.ts). homepage-urls.ts was missed in 2 batches in a row, requiring a 20-brand backfill. Prose checklists in omd-add-reference Phase 5 failed to enforce parity.

Option C — single source of truth + machine gate:

Canonical YAML frontmatter in every references/<id>/DESIGN.md carries id, name, country (ISO), category (slug), homepage, primary_color, logo.{type,slug}, verified, and optional display_name_kr + ds block. All 108 existing references migrated via web/scripts/migrate-frontmatters.mjs (preserves any existing fm; merges from the 5 source maps; emits canonical block).
Typed registry at web/src/data/registry.generated.ts (autogenerated, ~41 KB, 108 entries, sorted by id for stable diff). Built by web/scripts/build-registry.mjs, which validates the schema and fails fast pointing at the offending file. Auto-runs on npm run dev and npm run build.
5 consumers refactored to derive everything from REGISTRY / REGISTRY_BY_ID. route.ts, logos.ts, tokens.ts (BRAND_COLORS), design-systems.ts (getDesignSystem / getAllDesignSystems). web/src/lib/homepage-urls.ts deleted — getHomepageUrl now lives in registry.generated.ts. preview-export-view.tsx import updated.
Catalog-integrity vitest at web/__tests__/catalog-integrity.test.ts: 108 parametrized per-id assertions (schema, §1 canonical header, prose-first paragraph, fingerprint cross-check, design-md mirror) plus 5 cross-cutting invariants (registry sort, triple-fingerprint byte identity, mirror coverage, llms.txt advisory check). 328 tests, all green.
Husky pre-commit hook at .husky/pre-commit runs build-registry + catalog-integrity only when data-plane paths change (references/, data/reference-fingerprints.json, mirror copies, registry.generated.ts, scripts, the test itself). Other commits stay fast. Hook wired via core.hooksPath = .husky.
Skill thin-out:
- .claude/skills/omd-add-reference/SKILL.md Phase 5: 80 lines → 32 lines. Prose checklist replaced with the canonical frontmatter schema + a single npm run build-registry && npm test gate. Sub-agent self-verification step required.
- .claude/skills/omd-batch-launch/SKILL.md Phase 3: 58 lines → 22 lines. Same pattern.
Build verified — cd web && npm run build passes type-check and prerenders all 247 routes (incl. all 108 /design-systems/<id> pages). No regression in API, builder, playground, or browse modal — every surface reads the same registry.

Migration is one-way and irreversible: any new reference must follow the canonical frontmatter schema. The vitest gate (and husky) will refuse to merge a DESIGN.md missing a required field.