<p align="center">
  <img src=".github/assets/logo-bg.png" width="480" alt="oh-my-design" />
</p>

<h1 align="center">oh-my-design</h1>

<p align="center">
  <strong>One-command bootstrap for skill-driven design with your AI coding agent.</strong> 100+ real company design systems. Zero AI calls in the install. Then you just talk to your agent.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/oh-my-design-cli"><img src="https://img.shields.io/npm/v/oh-my-design-cli?style=flat-square&color=cb3837" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/oh-my-design-cli"><img src="https://img.shields.io/npm/dm/oh-my-design-cli?style=flat-square&color=cb3837" alt="npm downloads" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/kwakseongjae/oh-my-design?style=flat-square" alt="License" /></a>
  <a href="https://github.com/kwakseongjae/oh-my-design/stargazers"><img src="https://img.shields.io/github/stars/kwakseongjae/oh-my-design?style=social" alt="GitHub Stars" /></a>
  <img src="https://img.shields.io/badge/references-100%2B-7c5cfc?style=flat-square" alt="100+ References" />
  <img src="https://img.shields.io/badge/CLI%20commands-1-blue?style=flat-square" alt="One CLI command" />
</p>

---

## What is oh-my-design?

**oh-my-design (OmD)** turns your AI coding agent (Claude Code / Codex / OpenCode / Cursor) into a senior product designer with a working memory of your brand. You install once. After that, you just describe what you want — components, screens, copy, assets, charts — and the agent applies your project's design system, picks the right asset medium, and ships.

`DESIGN.md` is the brand spec ([Google Stitch](https://stitch.withgoogle.com/docs/design-md/overview/) tokens + the brand-philosophy layer: Voice / Narrative / Principles / Personas / States / Motion). 100+ real-company DESIGN.md files ship in this package. Pick one, customize through conversation, ship.

**No API keys. No external infra. Everything runs inside your existing CLI session.**

## Install

```bash
npx oh-my-design-cli install-skills
```

Then restart your agent (Cmd+Q in Claude Code, then relaunch) so the new skills + agents are loaded.

That is the only CLI command you will run. Everything else is natural language to your agent.

## Your first 60 seconds

This is the whole point: one prompt turns into a `DESIGN.md` your agent remembers across every future session.

1. Install (above), then **restart your agent** (Cmd+Q, relaunch) so it loads the new skills.

2. In your project, type your first prompt — copy this exactly:

   > Set up our design system — Toss-style, for a family meal-tracking app.

   Your agent runs **`omd:init`**: it recommends a reference from the 100+ real-company catalog, asks you to confirm, and writes **`DESIGN.md`** to your project root. (`omd:sync` then wires up the `CLAUDE.md` / `AGENTS.md` / Cursor shims so every agent reads it automatically.)

   **That `DESIGN.md` is your activation — your agent now remembers your brand.**

3. Now build against it:

   > Design the home screen.

   The agent reads `DESIGN.md` and ships brand-correct UI. No re-explaining your design system, ever again.

Don't want Toss? Any brand works — `Stripe-style`, `Linear-clone B2B SaaS`, `Karrot-style marketplace`. Browse the full catalog at [oh-my-design.kr/design-systems](https://oh-my-design.kr/design-systems).

## Upgrading

Skills and agents evolve every release. To pick up the latest bundle in an existing project:

```bash
npx oh-my-design-cli@latest install-skills
```

Idempotent. Managed files (those carrying the `<!-- omd:installed-skill -->` marker at the top) are refreshed in place. Files you edited that don't have the marker are left untouched (status `skipped-drift`). Pass `--force` if you really want to overwrite your custom edits.

Restart your agent after re-running so the refreshed skills + agents are loaded.

**Check what's installed vs what's latest:**

```bash
npx oh-my-design-cli --version       # what your project currently uses
npm view oh-my-design-cli version    # latest on the registry
```

**What's new each release:** [CHANGELOG.md](./CHANGELOG.md). Every release entry says what changed in the skills, agents, hooks, CLI, and data. If a change requires anything beyond a re-install — for example a migration of `DESIGN.md` frontmatter — it will be called out at the top of that entry.

### v0.2 agent layer (bundled)

A supervisor + specialist topology for multi-step authoring workflows. **6 skills + 6 sub-agents**, all channel-aware, installed alongside the core skills by `install-skills`:

| Skill / agent | Role |
|---|---|
| `omd-orchestrator` | Supervisor — 5-stage workflow (write → review → revise → localize → critic → images → handoff), 2-round revision cap |
| `omd-kr-writer` | Korean prose, **12 voice presets** (toss-tech-design default / karrot-neighborly / brunch-maker / naver-d2 / …) |
| `omd-locale-adapter` | KR → EN/JP/ZH-TW **adaptation** (cultural swaps, not literal translation) |
| `omd-designer-review` | Visual + brand audit vs DESIGN.md — typo/color/radius/state, BLOCK·WARN·FYI |
| `omd-final-qa` | 8-item rubric, read-only verdict, no rubber-stamps |
| `omd-codex-image` | Channel-aware image materialization — `<!-- omd:gen-image -->` spec → **Codex native generation** / `omd-asset-curator` fallback / OpenCode user-queue |

Pattern adopted: Anthropic orchestrator-workers + LangGraph supervisor revision-cap. Background & full routing rules: [`data/research/2026-05-18-agent-landscape.md`](./data/research/2026-05-18-agent-landscape.md) · KR voice taxonomy: [`data/research/2026-05-18-kr-style-presets.md`](./data/research/2026-05-18-kr-style-presets.md).

Promotion of future skills into the bundle is governed by the [`omd-release-hygiene`](./.claude/skills/omd-release-hygiene/SKILL.md) checklist. (A deterministic Korean-orthography linter was prototyped and dropped — a 25-pattern regex heuristic had too low recall to be worth shipping; if you need automated KR spellcheck, wire an external service such as the 부산대 한국어 맞춤법 검사기.)

## How to use omd with your AI

Open Claude Code (or Codex / OpenCode) in your project. Just talk:

> "Set up the design system for a calm B2B fintech dashboard."
> Agent picks a reference from the catalog (likely Linear or Stripe), proposes a hybrid DESIGN.md, asks for confirmation, writes the file plus shims.

> "Make the empty-state for the search results page."
> Agent reads DESIGN.md, builds the component with brand tokens, picks an inline SVG illustration matching the voice, drops in microcopy that follows the §10 voice rules.

> "Design the entire onboarding from scratch — Toss-style for a family meal-tracking app."
> Agent invokes the harness — runs the 10-phase pipeline (discovery, research, IA, wireframes, components, assets, microcopy, validation, handoff), spawns sub-agents in parallel where possible, asks you 3 mandatory checkpoints, hands back a v0/Cursor-ready package.

> "Add a daily-intake line chart."
> Agent reads your `package.json`, sees `recharts` is installed, builds the chart with brand colors, no library mismatch.

> "We never use uppercase CTAs."
> Agent silently appends to `.omd/preferences.md`. Next time anyone makes a CTA, that rule applies. Later you can say "fold preferences into DESIGN.md" and the agent merges by scope.

## What's in the install

| Path | Owner | Purpose |
|---|---|---|
| `.claude/skills/omd-*/SKILL.md` | install-skills | Claude Code skill bundle (15 skills — core flow + capture/assets + v0.2 agent layer) |
| `.codex/skills/omd-*/SKILL.md` | install-skills | Codex skill bundle |
| `.opencode/agents/omd-*.md` | install-skills | OpenCode agent bundle |
| `.claude/agents/omd-*.md` | install-skills | 16 canonical sub-agents (master + 15 specialists) |
| `.claude/data/*` | install-skills | reference fingerprints, vocabulary, opt-out corpus |
| `.claude/hooks/*.cjs` | install-skills | UserPromptSubmit / SessionStart / PostToolUse hooks |
| `.claude/skills/skill-rules.json` | install-skills | Skill activation rules |
| `references/*/DESIGN.md` | bundled | 100+ real design systems |
| `DESIGN.md` | your agent (after init flow) | Your project's authoritative brand spec |
| `CLAUDE.md` / `AGENTS.md` / `.cursor/rules/omd-design.mdc` | omd-sync skill | Pointers so every agent reads DESIGN.md |
| `.omd/preferences.md` | omd-remember skill | Append-only design correction log |
| `.omd/runs/<id>/` | omd-harness skill | Per-harness-run artifacts (briefs, wireframes, eval, handoff zips) |

## The 15 skills + 16 agents

Skills (loaded into your agent's context based on prompt triggers):

**Core flow**
- **omd:apply** — DESIGN.md as authoritative context for every UI task. Routes complex requests (assets, charts, full screens, a11y audit) to specialized sub-agents.
- **omd:init** — Bootstrap DESIGN.md from a reference + project description. 100+ references, hybrid variation that preserves the reference voice while shifting only user-named axes.
- **omd:harness** — `/omd-harness <task>` to run the 10-phase design pipeline. **v1.6.0**: auto-triggers on natural-language requests ("그럴싸한 랜딩 만들어줘", "프로토타입 구색 갖춰") — no slash required. New **CTX-PRIME** pre-phase scans your repo (stack, brand color, voice, surface inventory) in ~20ms, then surfaces a single audience picker + batched Interview-lite so `omd-master` skips slot-gate and jumps straight to PROPOSE_PLAN. 7 hero archetypes (rule 9) match brand vibe to layout (center-text / carousel / split-screen / editorial / dashboard / quote-led / left-character). Reveal safety net (rule 10), wordmark-only logo (rule 5), container-inner consistency (rule 7), decomposed hero (rule 8).
- **omd:remember** — Captures user corrections to `.omd/preferences.md` automatically when the agent detects them.
- **omd:learn** — Folds pending corrections back into DESIGN.md by scope.
- **omd:sync** — Maintains the shim files (CLAUDE.md / AGENTS.md / Cursor mdc) so every agent reads your DESIGN.md.

**Live capture + assets** (v1.3.x)
- **omd:reference-capture** — Live brand site CDP/playwright inspect → `assets/_reference/<id>/` with tokens.json + structure.json + fonts.json + `.live-inspect-proof.json` + screenshots + LICENSE-NOTE/attribution. Phase 3.9 browser-harness fast-path: 3-5× faster than playwright MCP when available.
- **omd:asset-fetch** — Free-license asset catalog with verified URLs. DiceBear CC0 (notionists/lorelei avatars), Lucide ISC icons, Picsum CC0 / Loremflickr Flickr-CC photos, SIL OFL display fonts (Bricolage Grotesque / Space Grotesk / DM Serif Display / Fraunces). Strict anti-patterns: handcrafted character SVG forbidden, brand creative work never in product DOM.
- **omd:experiment-gallery** — N-brand experiment results in a single comparison index.html. iframe scaled previews + wow ratings + multi-turn deltas + per-brand IP audit. Reusable across batches.

**v0.2 agent layer** (6 more) — `omd:orchestrator` / `omd:kr-writer` / `omd:locale-adapter` / `omd:designer-review` / `omd:final-qa` / `omd:codex-image`. See the [v0.2 agent layer](#v02-agent-layer-bundled) table above for what each does.

Sub-agents — master + 15 specialists (invoked by the master or directly by skills):

- **omd-master** — Conversational state machine, runs the harness phases. opus.
- **omd-ux-researcher** — Reads bundled references, validates Tier-1 official design system URLs. opus.
- **omd-ui-junior** — Generates wireframes and component manifests from DESIGN.md. sonnet.
- **omd-ux-engineer** — Section-level interaction / motion / IA / mobile / perceived-perf audit + code-level fixes. NN/g heuristics + Refactoring UI + Web Vitals + WAI-ARIA. Senior advisor; pairs with `omd-ui-junior` (generator). opus.
- **omd-asset-curator** — Picks asset medium (inline SVG / chart library / Lottie / Rive / Unsplash), generates inline code or sources external. Stack-aware (recharts vs chartjs vs custom SVG, lucide vs heroicons, etc.). sonnet.
- **omd-microcopy** — Voice-consistent copy generation tied to DESIGN.md §10. sonnet.
- **omd-ux-writer** — Section-level copy audit + 2-3 strong alternatives + A/B hypothesis. Podmajersky / Erika Hall / Mailchimp / Stripe / GitHub voice docs integrated. Senior advisor; pairs with `omd-microcopy` (generator). opus.
- **omd-a11y-auditor** — WCAG checks. haiku.
- **omd-persona-tester** — Adversarial 4-persona walkthrough (V/J/F/S). sonnet.
- **omd-critic** — Root-cause analysis when the user iterates. opus.

Plus the **6 v0.2 sub-agents** (orchestrator / kr-writer / locale-adapter / designer-review / final-qa / codex-image) — documented in the [v0.2 agent layer](#v02-agent-layer-bundled) section.

## MCP server

Want the brand DESIGN.md files exposed directly to your agent as MCP resources, tools, and prompts? Use **[oh-my-design-mcp](./packages/mcp/)** — a separate, free, drop-in MCP server.

```json
{
  "mcpServers": {
    "oh-my-design": {
      "command": "npx",
      "args": ["-y", "oh-my-design-mcp"]
    }
  }
}
```

Works with Claude Desktop, Cursor, Cline, Continue, and Codex. Zero AI calls, zero config, fully offline. Full install guide and tool reference: [`packages/mcp/README.md`](./packages/mcp/README.md).

## What it is not

- It is not a collection of CLI commands. There is one bootstrap command. Everything else is skill prose.
- It is not an SDK. If you need the matching algorithm or shim format, look at the skill markdown directly.
- It does not generate emojis as icons. Asset agent prefers inline SVG (Lucide-matched or custom).

## Repository layout

> For contributors. If you're just *using* OmD, you never touch these — the install ships everything you need.

The brand `DESIGN.md` corpus lives in more than one place **on purpose**. Here's the map so nothing looks like accidental duplication:

| Path | In git? | Ships to npm? | Role |
|---|---|---|---|
| `web/references/<id>/DESIGN.md` | ✅ | ✅ (CLI pkg) | **Canonical source of truth.** Lives under `web/` because the Vercel project root is `web/` — the site build can only read files beneath it. Everything else is derived from here. |
| `references` → `web/references` | ❌ gitignored | — | Local convenience symlink so root-level scripts/tests resolve the same path during local dev. |
| `design-md/<id>/DESIGN.md` | ✅ | ❌ | Public [awesome-design-md](https://github.com/VoltAgent/awesome-design-md)-style mirror — frontmatter-stripped + a "Source / Last verified" note. A different *format*, not a byte copy. |
| `packages/mcp/data/references/` | ❌ gitignored | ✅ (MCP pkg) | Build artifact. Regenerated from `web/references` by `packages/mcp/scripts/sync-data.mjs` on every `prepublish`/`build`. Never edit by hand. |

**Rule of thumb: edit `web/references/<id>/DESIGN.md` only.** `web/scripts/build-registry.mjs` regenerates the typed registry, and the pre-commit catalog-integrity gate (`web/__tests__/catalog-integrity.test.ts`) plus `sync-data.mjs` keep the derived copies honest.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history. Migrating from 0.1.x: see [MIGRATION.md](MIGRATION.md).

## License

MIT — see [LICENSE](LICENSE). References belong to their respective companies; reproduced for educational reference.
