Tell an AI to “make it as clean as Toss,” and the first screen may look convincing, but buttons, spacing, and states often start drifting by the second screen. What makes oh-my-design-cli interesting is not a promise to generate better designs; it is its use of contracts and validation steps to reduce the room an agent has for arbitrary decisions.
The core of 22 skills is ‘traceability of design decisions’
According to the current public repository, oh-my-design-cli includes 22 product skills, 19 specialist roles, 93 preset contracts, and more than 440 quality-grade references. Claude Code, Codex, and OpenCode install the full role bundle, while Cursor installs 21 compatible skills, so the setup differs slightly by channel.
By the numbers, it can look like a huge collection of prompts, but its structure is different. The core flow is philosophy → decision table → tokens → component contracts → layout grammar → implementation → rendering review. For example, the principle “use the accent color only for primary actions and focus rings” gets a decision ID, and the actual color token refers back to that ID. When an unsupported color value appears, it is treated not as a simple difference in taste but as a validation failure.
Here, 93 is not the number of finished UI components you copy in. It is the number of preset contracts to follow while creating components and screens. They are divided into base elements, shadcn/Radix-family primitives, screen genres such as commerce and marketplaces, and tendencies derived from references. Even when structure comes from an existing component library, the system requires values such as color, spacing, and state to be filled from the project’s decision table.
An important practical distinction
Skills define “what work to do and in what order,” while specialist roles provide evidence from focused perspectives such as research, accessibility, and copy. Preset contracts define conditions the implementation must meet, and DESIGN.md is closer to a handoff document that carries forward why those conditions exist into the next session.
Why contracts are stronger than prompts
A prompt guides one result, while a contract makes the same decisions reusable on the next screen. The official workflow also separates building a new design system, launching a new screen, improving an existing screen, and recording corrections to user preferences as distinct tasks. Rather than saying “make the dashboard prettier,” it recommends communicating the goal together with protection conditions, such as “preserve behavior, inspect hierarchy, density, motion, and accessibility, then fix the highest-impact issues.”
| Category | Style-prompt-focused | Contract-focused workflow |
|---|---|---|
| Color and spacing | The model selects plausible values on each screen | Reuse tokens linked to decision IDs |
| Component states | Likely to create only the default state and omit errors and loading | Record the state matrix and why certain states do not apply |
| Revision criteria | Subjective feedback such as “make it more polished” | Judge against principles, contracts, and rendering evidence on the same path |
| Next session | Re-explain everything when the conversation changes | Re-read the repository’s DESIGN.md and system files |
| Unknown values | Fill gaps with average default values | Omit undecided values and ask only about important decisions |
DESIGN.md Core v2 organizes this into seven areas: experience, foundations, typography and assets, components and states, layout and platform, content and locale, and governance. In particular, it requires unverified values to be left blank rather than filled with plausible defaults. It turns a design document from a “moodboard guide” into an executable contract read by people and agents together.
The direction of structuring tokens in a form that can be exchanged between tools is not unique to oh-my-design. The Design Tokens Community Group’s format specification likewise aims to lower integration costs by representing design tokens as a standard file format that multiple tools can exchange. oh-my-design can be seen as adding the source and rationale of values, component states, and validation procedures to that approach.
Even 93 contracts do not automatically guarantee quality
More important than the number of contracts is whether you selected contracts appropriate to the project and inspected them on real screens. The official anti-slop document does not label a rounded card or a purple accent as a problem by itself. It says to first read the user, task, existing behavior, and DESIGN.md, then check whether context-free patterns repeat several times and harm hierarchy or trust.
Accessibility follows the same principle. A sentence saying “consider accessibility” cannot be tested, but observable conditions such as a 4.5:1 contrast ratio for normal text and visible keyboard focus can be tested. WCAG 2.2 includes not only text contrast requirements but also a criterion that focus must not be obscured. Therefore, contracts should not be rules that absolutize taste; they should distinguish measurable quality from project-specific choices.
Treat benchmark numbers as hypotheses.
The project’s change log includes an internal measurement showing that, with the same fixture and brief, first-render defects fell from 7 to 3 and input tokens decreased by 47%. However, no independent external evaluation or broad project sample has been published. Your adoption decision should rest less on these figures and more on whether missing states, accessibility errors, and design drift actually decrease on your own screens.
A recurring issue in domestic real-world usage writeups is not “the visual appeal of the first screen” but a collapse of consistency as pages grow, with button shapes and color values diverging. Treating DESIGN.md as the project’s shared standard fits this problem well, but phrases such as “100% consistency” should not be taken as verified guarantees.
Four steps to validate it on a small scale in your project
- Install it at the real project root and check its status.
Runnpx oh-my-design-cli@latest, restart the agent, then usenpx oh-my-design-cli@latest doctorto check the status of skills, roles, the catalog, and DESIGN.md. The official documentation lists Node.js 18 or later as the minimum requirement. - Write the product task before the brand name.
Do not stop at “Toss style.” Specify the user, primary action, and behavior to protect, for example: “an app for busy parents to quickly log family meals; completing a record is the primary action; preserve the existing logo and data flow.” Ask the agent to question unverified product facts before using them. - Test with one screen and four state types.
Instead of rebuilding the whole home screen, choose a clearly bounded screen such as search results or payment completion. Create default, loading, empty, and error states, and check whether existing components are reused as well as keyboard navigation, contrast ratio, and mobile reflow. - Compare drift, not just the result.
After adding a second screen, check whether the same tokens and button states remain in use. Record whether new values absent from DESIGN.md appeared, whether revision reasons are traceable through decision IDs, and whether re-rendering the same path introduces regressions. If these three do not decrease, the adoption benefit remains low even with many skills.
If you want to dig deeper
GitHub - kwakseongjae/oh-my-design — The official repository where you can review the 22 skills, 19 roles, 93 preset contracts, and the full derivation structure. github.com
Skills — oh-my-design CLI — See how skills are divided across system management, screen creation, quality validation, writing, and reference collection. oh-my-design.kr
Workflows — oh-my-design CLI — Includes natural-language request examples you can use directly for building a new system, creating a new screen, and improving an existing screen. oh-my-design.kr
DESIGN.md Core v2 — Portable Design Contract Specification — The official specification covering DESIGN.md’s seven areas, authority relationships, handling of undecided values, and conformance stages. github.com
Design Tokens Format Module 2025.10 — Review the purpose and data structure of the DTCG format for exchanging design tokens between tools. designtokens.org
Web Content Accessibility Guidelines (WCAG) 2.2 — The original accessibility criteria, including contrast ratio, keyboard focus, and reflow, that can be included in a design contract. w3.org
