When the first screen looks fine but the next one feels like a different product
Creating a first screen with an AI coding agent can look quite convincing. The trouble starts when you add screens for settings, payments, or search results. The same primary button gets a different color and corner radius, loading and error states go missing, and in a new session you have to explain even the spacing decisions all over again.
At that point, simply writing longer style directions such as “make it clean like Toss” is not enough. You need to preserve why the agent chose each value and have it reuse those decisions on the next screen.
This is where oh-my-design gets interesting. Its core is not installing lots of skills, but connecting a design philosophy to decision IDs, tokens, component states, and rendered-result reviews. The result is recorded in DESIGN.md as the starting point for the next task.
Try this now: establish a shared standard for one screen
You do not need to rebuild the entire product from scratch. Pick one screen whose existing behavior must be preserved, then connect installation, contract proposal, approval, and screen validation once. The process below is based on public documentation; it is not the result of the editorial team directly running the CLI.
- Start installation from the project root.
Prepare Node.js 18 or later, a Git repository, and one installed and authenticated agent among Claude Code, Codex, OpenCode, and Cursor. Runnpx oh-my-design-cli@latestand choose the scope for the base project installation. No separate API key or MCP server is required for the core local workflow. - Fully restart the agent and check the installation status.
In Codex, you must trust the project for project-local roles to load. After restarting, runnpx oh-my-design-cli@latest doctorfrom the same root to check for anything missing related to skills, agents, catalogs, or DESIGN.md. - Enter an initial request that includes users and guardrails.
For example: “Please propose a project-owner DESIGN.md for an app where busy parents record family meals. Use Toss only as reference material and retain only verified facts. Ask before deciding product-specific facts, preserve existing behavior and the logo, and do not adopt DESIGN.md before approval.” - Have the owner approve the proposed file directly.
To adopt a graph-bound DESIGN.md, the project owner or a pre-registered external authority controller must review and approve the exact proposed bytes. The agent that generated or implemented it cannot approve it itself. - Improve one screen with clear boundaries.
Have the agent read the adopted DESIGN.md first, then ask something like, “Preserve the existing search behavior and logo, and improve the hierarchy and states of the search results screen.” Success does not mean making the screen more flashy. Confirm that existing behavior remains intact, that visible changes and a validation summary are produced, and that new tokens and states connect to decisions in DESIGN.md.
Distinguish the scope of the approval process.
You do not need the full adoption package merely to read a standalone DESIGN.md as a reference document. However, if a graph bound by a manifest and hash is claimed to be the current project’s authoritative standard, owner approval and adoption boundaries must be respected. Core v2 itself is currently labeled as a draft interoperability contract.
The 93 are not UI templates—they are contracts to inspect
oh-my-design’s 93 preset contracts are not a library for copying 93 finished screens. They consist of four layers: fundamental elements, mapping primitives in the shadcn and Radix families, screen genres such as commerce and marketplaces, and tendencies derived from references. Each component contract defines structure, a state matrix, accessibility requirements, and token slots.
So there is no reason to apply all 93 to a project. For a search screen, select only contracts for elements you actually use, such as the input, buttons, result list, empty state, and error state. The value of a contract is not its count, but recording the reasons for states that are included and states that are not.
| Work scenario | With style directions alone | With connected contracts |
|---|---|---|
| Adding an accent color | Choose a plausible color on each screen | Use a token that references a decision ID |
| Implementing an input | Easy to create only the default state | Check the state matrix, including focus, error, and disabled |
| Creating the second screen | Explain the style from the previous conversation again | Read DESIGN.md and existing contracts first |
| Revising design | Judge through impressions such as “make it more polished” | Compare the decision table with rendered results from the same path |
The official structure begins with philosophy and flows through a decision table, tokens, component contracts, layout grammar, implementation, rendering critique, and DESIGN.md. If a token or component value does not reference the decision table that produced it, or a declared principle affects no token, it can be classified as a quality-gate failure.
The core that remains even when skill counts differ
The previously known count of 22 skills and 19 roles is no longer current. The latest official Skills page describes 27 product skills and 20 specialist agents, while the repository README counts the full bundle, including channel-specific items, as 28 skills and 20 roles.
This difference exists because the documents count different scopes. Even the Cursor installation count cannot be stated as a single number because descriptions within the README do not match. So when adopting it, it is more accurate to check the doctor results for which files were actually installed for your agent and project than to ask how many skills there are.
Skills handle work sequences such as system generation, screen work, and review, while specialist agents add evidence from narrow perspectives such as accessibility and content. Preset contracts are conditions that implementation results must satisfy, and DESIGN.md carries those conditions and their decision rationale into the next session. That division of roles is the product’s core even when the numbers change.
A contract must be observable conditions, not taste
“Consider accessibility” is a well-intentioned statement, but it is difficult to determine whether it has passed. In contrast, you can test a 4.5:1 contrast ratio for normal text, whether content and functionality remain available when text is enlarged to 200%, and whether keyboard focus is visible and not completely obscured by other content. WCAG 2.2 defines such conditions specifically.
Of course, writing conditions in a contract does not automatically prove that the actual implementation conforms to WCAG. There are exceptions with different contrast requirements, such as logos, large text, and inactive content. A contract therefore needs to be both a document that fixes the project’s choices and a checklist for people to review the rendered result.
Judge the effect on the second screen.
Rather than the look of the first screen, compare whether the same button token remains on the next screen, whether loading, empty, and error states are present, and whether values absent from DESIGN.md have been added arbitrarily. The cost of creating contracts becomes meaningful only when drift across those three items decreases.
7→3 and 47% are possibilities, not guarantees
The official change log includes its own measurement showing that, with the same fixture and brief, first-render defects dropped from 7 to 3 and input tokens decreased by 47%. It also records zero P0 and P1 defects, the highest-severity categories, under both conditions.
However, the sample size, number of runs, models used, statistical uncertainty, and independent external evaluation have not been disclosed. It is difficult to use this as evidence that every project’s quality or cost will improve by that amount. In your own project, it is more practical to check whether missing states, newly introduced arbitrary values, and regressions in existing behavior decrease on the next screen rather than focusing on the number of first-render defects.
If you want to dig deeper
GitHub - kwakseongjae/oh-my-design — The official repository where you can examine the overall structure, the classification of 93 preset contracts, and differences by installation channel. github.com
Getting started — oh-my-design CLI — Check the first-run sequence, from project installation to agent restart and the doctor check. oh-my-design.kr
DESIGN.md Core v2 — Portable Design Contract Specification — A specification that normatively explains the seven fixed areas, handling of undecided values, and owner-approval boundaries. github.com
Web Content Accessibility Guidelines (WCAG) 2.2 — The source text for accessibility standards that can be incorporated into contracts, including contrast ratios, text enlargement, and keyboard focus. w3.org
