oh-my-design
Give coding agents a traceable design system so interface work follows decisions owned by your project.
- Source repo
- kwakseongjae/oh-my-design
- Stars
- ★ 534
- Last updated
- 11d ago
- License
- MIT
- Primary language
- JavaScript
- FA score
- 76/100 · Good
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A frontend developer using Claude Code wants to establish a project-owned DESIGN.md before asking the agent to build a product home screen.
- Not a fit if
- Teams that need design generation outside an existing coding-agent session
- Teams using only coding agents that are not listed as supported
- Source review
- 76/100 · Good
What does this agent do, and when should you use it?
oh-my-design is a CLI that installs design workflows into Claude Code, Codex, OpenCode, and Cursor. Its bundle includes 28 skills, 20 specialist roles, 93 preset component contracts, and more than 500 quality-graded company design references. The workflow derives tokens, component contracts, and layout rules from a declared philosophy and decision table, then guides an agent to build and critique an interface against them. Outputs include a portable DESIGN.md and optional structured evidence under `.omd/system/`; the local `omd book` view can also export a single HTML file. Core workflows run inside a coding-agent session you already use and require no separate API key, daemon, or MCP server.
Run npx oh-my-design-cli@latest to install skills, specialist roles, and the reference catalog into detected agents, or target a channel with install-skills --agent <name> --all. After installation, doctor diagnoses the bundle; natural-language requests are handled by OmD skills in the coding agent. omd:init can recommend a reference from a brief and prepare a DESIGN.md and graph preview; after the project owner reviews and approves it, the CLI compiles and adopts hash-bound files. The agent can then read DESIGN.md and build against its recorded decisions. omd book presents tokens, their decisions, state matrices, and preset lineage on a local port. The CLI also includes commands to inspect, validate, and migrate DESIGN.md files.
- A frontend developer using Claude Code wants to establish a project-owned DESIGN.md before asking the agent to build a product home screen.
- A team using Codex wants to install reusable skills, specialist roles, and reference data in its repository for later sessions.
- A design-system maintainer using Cursor wants Agent Skills and a project rule to keep DESIGN.md in the agent's workflow.
- A team with a legacy DESIGN.md wants to inspect and validate it, then stage a migration in a separate directory for review.
- A designer wants to inspect token origins and component-state rationale in the local
omd bookview or export a static HTML handoff.
How do you install or deploy this agent?
You need a Node.js/npm environment and a supported coding agent. Project-scoped installation is the default. Restart the agent after installation, then run the doctor command to check the bundle.
How do you use this agent?
Install in the project and diagnose the bundle:
npx oh-my-design-cli@latest
npx oh-my-design-cli@latest doctorAfter restarting the agent, submit a brief such as the README example to Claude Code, Codex, or OpenCode:
Create a project-owned DESIGN.md for a family meal-tracking app. Use Toss as a reference, keep only verified reference facts, and ask before deciding product-specific facts.The OmD workflow prepares a preview for review and adoption under its approval checkpoints. Then ask the agent to read DESIGN.md and design a specific screen. Browse or export the system with:
npx oh-my-design-cli@latest book
npx oh-my-design-cli@latest book --static ./outTo install the Cursor channel and restart Cursor:
npx oh-my-design-cli@latest install-skills --agent cursor --allWhat are this agent's strengths and limitations?
- Tracks design decisions from philosophy through numbered rationale to tokens and component contracts, with gates for tokens lacking a decision and components that bypass a matching preset.
- Includes 93 preset contracts and more than 500 quality-graded references to start from existing design material.
- Supports four coding-agent channels and includes a local doctor check plus static HTML export from
omd book.
- Workflows depend on a supported coding-agent session such as Claude Code, Codex, OpenCode, or Cursor; the CLI is not a standalone design-generation service.
- The agent must be restarted after installation; Codex also requires project trust before project-local roles load.
- Adopting a DESIGN.md requires review by the project owner or a pre-registered external authority controller; the agent cannot approve its own proposal.
How does this agent compare with similar options?
The README relates its presets to shadcn/ui: shadcn/ui supplies structure, while OmD presets specify which values must come from the project's decision table. It also says the old catalog MCP transport is retired; current skills and roles use the local catalog or raw Markdown routes.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| oh-my-design This agent | 76 · Good | CLIFree | ★ 534 | 11d ago | JavaScript | Codex · Claude Code |
| UI Craft | 77 · Good | CLIFree | ★ 381 | 1mo ago | JavaScript | Codex · Claude Code |
| Superdesign Skill | 43 · Major gaps | Agent plugin / skillFreemium | ★ 652 | 1mo ago | JavaScript | Codex · Claude Code |
| Taste-Skill: AI Frontend Aesthetic Upgrade | 31 · Major gaps | CLIFree + model costs | ★ 95k | today | JavaScript | ChatGPT · Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Installation can target project or global paths; the README says OpenCode global installation leaves global hooks/settings unchanged. Upgrades preserve user-edited files, and the guidance recommends doctor and cautious use of --force. The design workflow requires review and explicit authority checkpoints, and the generating agent cannot approve its own proposal, so confirmation is thoroughly addressed. The README says the core workflow needs no extra API key or MCP server, but also says agents can fetch references directly; the full network and data-flow picture is not documented. Sensitive-data handling is thin. Dependency manifests, CI checks, and npm provenance are described, but no vulnerability-response policy is shown. References are attributed to their companies and described as reconstructed educational material. Publisher identity is unverified and no specific maintainer is identified.
The README, package metadata, and workflows describe a coherent multi-channel installer, doctor, upgrade, and build process. A release-workflow comment still gives a v1.7.2 example while package metadata says 2.0.2, suggesting a small stale-documentation inconsistency. Node 18+ and npm/npx installation are documented, though installation and some reference retrieval depend on external services. Doctor and scoped repair commands provide failure recovery, but the supplied files do not show concrete error-output examples.
The materials cover design-system creation, existing-interface changes, reference import, review, and implementation, and spell out differences among Claude Code, Codex, OpenCode, and Cursor, including Cursor compatibility limits. They also provide multilingual prompts and workflows. The complete trigger rules are not present in the supplied evidence, so trigger precision is not fully established.
The README organizes outputs, derivation, installation, supported channels, upgrades, and links to specifications, examples, and migration material. Commands, project/global paths, restart and doctor steps, noninteractive installation, and repair guidance are concrete. Channel and skill names appear reasonably stable, but no complete FAQ is supplied and limitations do not cover every environment or risk. The MIT license file agrees with package metadata. Versioning and changelog paths are present, though the release notes include a stale version example. The publisher is unverified and specific maintenance responsibility is unclear.
The product provides portable DESIGN.md output, layered system contracts, and a local book with static export. Its example traces a token back to a decision ID, supporting review and reuse. The 500+ references, skills, and multi-agent installation offer clear added value. The README claims no AI calls or extra API/MCP requirements, but installation needs Node/npm and references may be fetched online; the full cost and network tradeoff is not described.
The README links claims to the specification, derivation chain, gates, presets, and generated examples; package contents and CI workflows also show build and check commands, providing some cross-source support. The supplied materials do not establish that these commands passed at this revision, and this review does not claim execution or independent testing. Some capability claims remain project assertions, so fact and inference are not fully separated throughout.
- This is a low-confidence static review; installation, tests, and CI were not run, and project claims were not independently verified.
- Installation and some reference retrieval depend on external services; review the target channel, write paths, and network access before use.
- A release-workflow comment contains an old version example, and the materials do not identify a specific maintainer.
FAQ
Do the core workflows require a paid API key or MCP server?
Does installation silently adopt a newly generated design system?
Which coding agents have documented installation support?
Can I stage a migration of an old DESIGN.md without overwriting the source?
design-md migrate writes a candidate to a specified output directory. The README says legacy formats remain readable and migration must preserve source content with dropped=0.