# oh-my-design: a design system your coding agent has to answer to

> oh-my-design installs a design workflow into Claude Code, Codex, Cursor and OpenCode, deriving tokens and component contracts from a written philosophy through a chain of numbered gates, and shipping everything as editable files in your repository. It fits teams who want an agent to follow a stated design system, and it does not fit a project with no design decisions to record in the first place.

**kwakseongjae/oh-my-design** — Give your AI coding agent a design system. One command installs 500+ quality-graded company DESIGN.md references + skills into Claude Code, Codex, Cursor, and OpenCode. Free, MIT, zero AI calls.

- Repository: https://github.com/kwakseongjae/oh-my-design
- Website: https://oh-my-design.kr
- Stars: 547 · Forks: 48
- Language: JavaScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/kwakseongjae-oh-my-design

## A design system the agent cannot quietly ignore

oh-my-design is a command line tool that gives a coding agent a design system to work against. The description says it plainly: one command installs more than five hundred quality graded company DESIGN.md references plus skills into Claude Code, Codex, Cursor and OpenCode, for free, under the MIT licence, with zero AI calls in the core workflows. That last point matters for a tool aimed at agents, because the interesting part is not that a model can generate a design but that the generated design is checked against something the team wrote down. The project description says it is a design system your coding agent can actually hold, and the README frames the problem as the middle that AI UI work keeps missing: a philosophy you declare, tokens and component contracts derived from it, and numbered gates for the failures that AI repeats. The audience is a frontend team working with an agent that produces plausible interfaces nobody signed off on.

## The chain from philosophy to DESIGN.md

The mechanism is a derivation chain, and the README is explicit that a screen is the last step rather than the first. The chain runs:

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

Each step constrains the next, and the reasoning behind the design is stated rather than assumed. A principle has to name what it sacrifices, on the grounds that a principle you cannot argue with is decoration. Every decision receives an id in the form of a principle code and a number, plus one line of rationale, and tokens carry that id back, so a value with no decision behind it is treated as a gate failure rather than a style preference. The practical consequence is traceability: the README's claim is that you can start at any value in the system and walk back to the sentence that caused it. The chain is specified in the derivation chain reference under the autopilot skill, and the generated output the README shows runs to several hundred lines, so this is a document format with structure rather than a prose summary.

## Numbered gates that fail the build

The gates are where a stated philosophy becomes enforceable. The reference file named slop-gates holds 54 slop checks, and the README adds that there are 8 more system-fidelity gates, making 62 checks in total. Two of them are described in enough detail to be worth repeating. GS7 fails a token that carries no decision reference, and GS8 fails a component built from scratch when a matching preset already existed. The first is the mechanism described above, made into a pass or fail condition. The second prevents the agent from reinventing a card or a table that the preset catalog already defines, which is the failure mode that produces a codebase with four different button components. Alongside the gates sit 45 component craft norms covering geometry, states and optical alignment, and the spec directory holds machine-readable schemas for the graph, provenance and coverage. The spec file for the portable contract, its seven anchors and its conformance levels is what makes the system inspectable without running the CLI.

## 93 preset contracts and the states that do not apply

The preset catalog holds 93 component contracts organised in four layers: fundamentals, shadcn and Radix mapped primitives, screen genres, and reference derived flavours. A contract is not just a component description. It has anatomy, a state matrix, an accessibility contract, and the token slots that the team's own decisions fill, and it cites the preset it inherited from so the origin of a value is never in doubt. The part of the contract that distinguishes this approach is the list of states that deliberately do not apply, each with the reason. A card that has no disabled state explains that a sold out item still opens its detail page and that stock is shown as a badge, and a card with no loading state explains that the media carries explicit dimensions so the card itself is never a pending control. The README separates the roles clearly: shadcn gives the structure, and the preset says which values must come from the team's own decision table instead of a library default.

## Everything ends up as a file you can edit

The version 2 change is the one that matters for adoption, and the README puts it plainly: in v2.0.0 every layer is a file you can edit, the philosophy, the presets, the gates and the references, and the next build has to justify itself against whatever you put there. The argument offered is that taste you cannot inspect cannot be improved. So the tool is not a black box that emits a design system, it is a set of artefacts in your repository that a designer or a developer can argue with. The files listed in the repository make that concrete: a spec directory with the portable contract and the schemas, a skills directory holding the autopilot references and the preset catalog, a benchmarks directory with three complete systems the harness generated end to end, and a design-md directory. The manifest also ships machine-readable data files for reference fingerprints, reference quality, reference tags, vocabulary, synonyms and an opt-out corpus, plus a skills lock file, so the installed set of skills is pinned rather than floating.

## Reading the system back with omd book

The third artefact is a reader for the system you just derived. The book command is invoked with npx oh-my-design-cli@latest book, and it serves your system on a local port: each token beside the decision that produced it, state matrices with their reasons, contrast measured live against the pairs you declared, and preset lineage showing where a component came from. A static flag writes a single HTML file instead, which is the handoff artefact for a designer who does not want to run a server. The implementation lives in the book source file in the CLI directory, and the README lists it among the things you can inspect without installing anything. The live contrast measurement is the feature with the most practical value, because it turns accessibility claims into numbers computed from the actual pairs in your system rather than from a checklist.

## Two binary names, one package, many skills

The package is published as oh-my-design-cli and it installs two command names pointing at the same file:

```json
  "bin": {
    "oh-my-design": "dist/bin/oh-my-design.js",
    "omd": "dist/bin/oh-my-design.js"
  },
```

So the long form and the short form are interchangeable, and the README's own examples use the short one. The manifest version is 2.0.4, the package is an ES module, and the published file list is long: more than thirty skill directories, from init and apply through harness, learn, sync, taste, update and reference capture, to slop audit, restraint, designer review and final QA, along with the data files, the hook scripts for Claude, and the benchmark scripts. The README also counts 31 skills, 20 specialist roles, 93 preset contracts and more than five hundred references, which is a lot of behaviour for a package that also advertises no API key and no MCP server for the core workflows. There are no GitHub releases, the repository is not archived, and the last push was on 2026-10-20, so the package version rather than a tag is what you pin. The full walkthrough lives on the project site at oh-my-design.kr, and the README is available in English, Korean, Japanese and Traditional Chinese.

## Conclusion

oh-my-design fits a team that already has opinions about its interface and wants them written down where an agent cannot ignore them, and who is prepared to edit the philosophy, presets and gates as files. It does not fit a project that has not yet decided what its design system is, because the tool's first requirement is a philosophy that names what it sacrifices. Verify first that the derived DESIGN.md in this repository reads as your own decisions rather than the sample's, then run the gates against your own build, and treat the contrast numbers reported by omd book as measurements of your declared pairs rather than as a pass mark.

## FAQ

### What does oh-my-design install into my coding agent?

The README counts 31 skills, 20 specialist roles, 93 preset contracts and more than 500 quality graded references, installed into Claude Code, Codex, Cursor and OpenCode. The package installs two command names, oh-my-design and omd, from the same binary, and the core workflows need no API key and no MCP server.

### How are tokens and components derived from a design philosophy?

The README gives the chain as philosophy, decision table, tokens, component contracts, layout grammar, build, render critique and finally DESIGN.md, where each step constrains the next. Every decision gets an id and one line of rationale, and tokens carry that id back so a value with no decision behind it fails a gate.

### What do the gates in oh-my-design check?

The slop gates reference holds 54 checks and the README adds 8 system-fidelity gates. Two are named: GS7 fails a token that carries no decision reference, and GS8 fails a component built from scratch when a matching preset existed.

### Can I review the design system oh-my-design generated?

Yes. The book command, run as npx oh-my-design-cli@latest book, serves the system on a local port with each token beside its decision and contrast measured live against the pairs you declared, and the static flag writes a single HTML file for handoff. The generated DESIGN.md files are also committed in the benchmarks directory of the repository.

## Sources

- [Issues](https://github.com/kwakseongjae/oh-my-design/issues)
- [kwakseongjae/oh-my-design on GitHub](https://github.com/kwakseongjae/oh-my-design)
- [License: MIT](https://github.com/kwakseongjae/oh-my-design/blob/main/LICENSE)
- [Project website](https://oh-my-design.kr)
- [README](https://github.com/kwakseongjae/oh-my-design/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kwakseongjae-oh-my-design