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 6 skills (apply, init, harness, remember, learn, sync), 11 sub-agents (master orchestrator + 10 specialists), 4 hooks, and 67 reference DESIGN.md files. After restarting your AI coding agent, you just talk in natural language — skills route to the right sub-agents automatically.

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.

Docs · v1.0.0

The skill-driven design harness.

Q: 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.

6 skills, 11 sub-agents, a 10-phase pipeline, and 67 reference DESIGN.md files — installed into your AI coding agent in one command. No API keys. No external infra. Then you just talk to your agent.

$npx oh-my-design-cli install-skills

Quick start

Three steps · two minutes

step 01

Install in your project

In your project root:

$npx oh-my-design-cli install-skills

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

step 02

Bootstrap a DESIGN.md

Open Claude Code / Codex / OpenCode / Cursor in the project, then say:

“Set up the design system for a calm B2B fintech dashboard.”

Agent picks a reference, proposes a hybrid DESIGN.md, asks you to confirm, writes the file plus shims.

step 03

Talk in natural language

That's it. From here on, you describe what you want — components, screens, copy, charts, 3D — and the agent applies your DESIGN.md, picks the right asset medium, and ships.

“Make the empty-state for the search results page.”

Skills · 6

Loaded into your agent's context, fired by triggers

Skills are markdown rule files that activate based on what you say. They route complex tasks to the right sub-agents.

omd:apply

Apply DESIGN.md

Trigger · Any UI task

Authoritative brand context for every UI request. Routes complex tasks (assets, charts, full screens, a11y audit) to specialist sub-agents.

omd:init

Bootstrap a project

Trigger · First-time setup

Pick from 67 reference design systems. Hybrid variation — preserves the reference voice while shifting only the axes you name.

omd:harness

Run the design pipeline

Trigger · /omd-harness <task>

Spawns omd-master to run the 10-phase pipeline (Discovery → Handoff). Sub-agents dispatched in parallel where independent.

omd:remember

Capture preferences

Trigger · User correction detected

Append-only log at .omd/preferences.md. Auto-fires when you say things like "we never use uppercase CTAs" or "stop using emoji icons".

omd:learn

Merge preferences into DESIGN.md

Trigger · Fold corrections

Folds pending preferences back into DESIGN.md by scope (global / page / component). Keeps your brand spec the single source.

omd:sync

Sync agent pointers

Trigger · Maintain shims

Keeps CLAUDE.md, AGENTS.md, .cursor/rules/omd-design.mdc up-to-date so every coding agent reads the same DESIGN.md.

Sub-agents · 11

Specialists, dispatched by the master orchestrator

omd-master runs the harness phases and dispatches specialists in parallel where independent.

opus

omd-master

Orchestrator

Conversational state machine. Runs the harness phases, asks the 3 mandatory user checkpoints, dispatches sub-agents.

opus

omd-ux-researcher

Research

Reads bundled references, validates Tier-1 official design system URLs, drafts the brief.

sonnet

omd-ui-junior

Wireframes & components · generator

Generates wireframes and component manifests strictly from DESIGN.md tokens. Defines all 5 states for every screen.

opus

omd-ux-engineer

Section UX audit · advisor

Section-level interaction / motion / IA / mobile / Web Vitals / WAI-ARIA audit + code-level fixes. NN/g + Refactoring UI integrated. Pairs with ui-junior (generator).

sonnet

omd-asset-curator

Asset medium picker

Picks medium (inline SVG / chart library / Lottie / Rive / Unsplash / 3D). Stack-aware (recharts vs chartjs, lucide vs heroicons).

opus

omd-3d-blender

3D renderer

Blender MCP renderer with just-in-time install walkthrough. Renders with materials cited from DESIGN.md §2 + §6.

sonnet

omd-microcopy

Voice copy · generator

Voice-consistent copy generation strictly tied to DESIGN.md §10. Refuses forbidden phrases.

opus

omd-ux-writer

Copy audit · advisor

Section-level copy audit + 2-3 strong alternatives + A/B hypothesis. Podmajersky / Mailchimp / Stripe / GitHub voice docs integrated. Pairs with microcopy (generator).

haiku

omd-a11y-auditor

Accessibility

Deterministic WCAG checks. axe-core + lighthouse + Tier-1 DS URL liveness. Pass/fail is binary.

sonnet

omd-persona-tester

Adversarial QA

Walks the generated UI under 4 strict personas (V/J/F/S) with hard turn budget. Emits 6 quantitative metrics.

opus

omd-critic

Root-cause review

Reads full run output, user feedback, persona ABANDONs. Writes a critique that re-enters at the lowest broken phase, not surface patches.

Pipeline · 4 stages · 10 phases

What happens on /omd-harness <task>

omd-master spawns the right specialists at each phase, asks 3 mandatory user checkpoints, and emits artifacts to .omd/runs/<id>/.

Phase✓User checkpointagentDispatched sub-agent∥Parallel stage

01 · Plan

Define the brief and the constraints.

01Discovery✓check
Brief · constraints · success metrics
agentmaster
02Research
Tier-1 DS scan · competitor URLs
agentux-researcher
03IA
Information architecture · sitemap
agentux-researcher

02 · System

Lock the brand tokens and components.

04Wireframes
ASCII wireframes · 5 states / screen
agentui-junior
05Design system
DESIGN.md · tokens · philosophy
agentmaster
06Components✓check
Component manifest · variants
agentui-junior

03 · Make∥ parallel

Generate artifacts in parallel.

07Asset sourcing
Inline SVG / chart / 3D / image picks
agentasset-curator
08Microcopy
Voice-consistent copy · §10 cited
agentmicrocopy

04 · Validate & Ship

Catch issues, package the deliverable.

09Validation
axe-core + 4-persona walkthrough
agenta11y-auditor + persona-tester
10Handoff✓check
Zip · v0/Cursor-ready package
agentmaster + critic

∥Parallel dispatch

Once the system is locked, Asset sourcing and Microcopy dispatch in parallel.

Both agents read the same DESIGN.md but emit independent artifacts — fastest end-to-end.

✓User checkpoints · 3

Three points where the harness pauses for your OK:

Discovery — does the brief look right?
Components — system tokens locked?
Handoff — ready to ship?

Skipping any aborts the run cleanly.

Use cases

Real prompts that route through real skills

What you say · what the agent does. No magic — every transition is a skill firing.

“Set up the design system for a calm B2B fintech dashboard.”

↳ what happens

Agent picks a reference (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.”

↳ what happens

Reads DESIGN.md, builds the component with brand tokens, picks an inline SVG matching the voice, drops microcopy that follows §10 voice rules.

“Design the entire onboarding from scratch — Toss-style for a family meal-tracking app.”

↳ what happens

Invokes the harness — runs the 10-phase pipeline, spawns sub-agents in parallel, asks 3 user checkpoints, hands back a v0/Cursor-ready package.

“Render a 3D water glass for the hero.”

↳ what happens

Recommends Blender, walks through install-on-demand (not bundled in upfront bootstrap), then renders with materials cited from §2 + §6.

“Add a daily-intake line chart.”

↳ what happens

Reads your package.json, sees recharts is installed, builds with brand colors. No library mismatch.

“We never use uppercase CTAs.”

↳ what happens

Silently appends to .omd/preferences.md. Next CTA anywhere in the project applies the rule. Run "fold preferences" later to merge by scope.

Install layout

Exactly what gets written to your project

Nothing hidden. Every path is documented; every owner is named.

PathOwnerPurpose

.claude/skills/omd-*/SKILL.mdinstall-skillsClaude Code skill bundle

.codex/skills/omd-*/SKILL.mdinstall-skillsCodex skill bundle

.opencode/agents/omd-*.mdinstall-skillsOpenCode agent bundle

.claude/agents/omd-*.mdinstall-skills11 canonical sub-agents (master + 10 specialists)

.claude/data/*install-skills67-reference fingerprints, vocabulary, opt-out corpus

.claude/hooks/*.cjsinstall-skillsUserPromptSubmit / SessionStart / PostToolUse hooks

references/*/DESIGN.mdbundled67 real design systems

DESIGN.mdyour agentYour project's authoritative brand spec

CLAUDE.md / AGENTS.md / .cursor/rules/omd-design.mdcomd:syncPointers so every agent reads DESIGN.md

.omd/preferences.mdomd:rememberAppend-only design correction log

.omd/runs/<id>/omd:harnessPer-harness-run artifacts (briefs, wireframes, eval, handoff zips)

FAQ

Common questions

Does it call any AI provider during install?+

No. Install copies skill markdown, hooks, and 67 DESIGN.md files. Zero API calls. Your AI agent (Claude Code, Codex, OpenCode, Cursor) is the inference layer — install just teaches it where to look.

Which agents are supported?+

Claude Code, Codex, OpenCode, and Cursor (via .cursor/rules). Hooks ship for Claude Code; the SKILL.md files are agent-agnostic markdown.

Can I bring my own DESIGN.md?+

Yes. If a DESIGN.md exists at repo root, omd:apply uses it as-is. Otherwise omd:init proposes a hybrid from one of the 67 references.

How do preferences differ from DESIGN.md?+

.omd/preferences.md is the running log of corrections (append-only). DESIGN.md is the canonical spec. Run "fold preferences" to merge by scope.

What's a harness run?+

Invoking /omd-harness <task> creates .omd/runs/<id>/ and steps through the 10 phases. Each phase emits artifacts. The final zip is v0/Cursor-ready.

Is it really free?+

Yes. MIT licensed. The npm tarball is the only package. No paid tier exists or is planned. References belong to their respective companies — reproduced for educational reference only.