AIに「Tossのようにすっきり」と伝えると、最初の画面はもっともらしくても、2画面目からボタン・余白・状態がぶれやすくなります。oh-my-design-cliが興味深いのは、より良いデザインを生成すると約束するからではなく、エージェントが恣意的に判断できる余地を契約と検証段階で減らしている点です。
22個のスキルの本体は「デザイン意思決定の追跡可能性」です
現在の公開リポジトリによると、oh-my-design-cliには22個のプロダクトスキル、19個の専門ロール、93個のプリセット契約、440件以上の品質グレード参照が含まれています。Claude Code・Codex・OpenCodeにはロール一式を導入し、Cursorには互換性のある21個のスキルを導入するなど、チャネルごとに構成が少し異なります。
数字だけを見ると巨大なプロンプト集に見えますが、構造は異なります。中核となる流れは哲学 → 決定表 → トークン → コンポーネント契約 → レイアウト文法 → 実装 → レンダリングレビューです。たとえば「アクセントカラーは主要アクションとフォーカスリングにのみ使う」という原則に決定IDを付け、実際のカラートークンがそのIDを参照します。根拠のない色値が生まれた場合、単なる好みの違いではなく、検証の失敗として扱う仕組みです。
ここでいう93は、完成済みのUIコンポーネントをコピーしてくる数ではなく、コンポーネントや画面を作る際に守るべきプリセット契約の数です。基本要素、shadcn/Radix系プリミティブ、コマース・マーケットプレイスのような画面ジャンル、参照から派生した傾向に分かれます。構造を既存のコンポーネントライブラリから持ってくる場合でも、色・余白・状態などの値はプロジェクトの決定表から埋めるよう求めます。
実務で重要な区別
スキルは「どの作業をどの順番で行うか」を担い、専門ロールは調査・アクセシビリティ・コピーのような狭い観点から根拠を提供します。プリセット契約は実装結果が満たすべき条件であり、DESIGN.mdはその条件がなぜ生まれたのかを次のセッションまで残す引き継ぎ書に近いものです。
プロンプトより契約が強い理由
プロンプトは一度の結果を導きますが、契約は次の画面でも同じ意思決定を再利用させます。公式ワークフローでも、新しいデザインシステムの構築、新画面のリリース、既存画面の改善、ユーザーの好みの修正記録を別々の作業として区別しています。「ダッシュボードをきれいに」ではなく、「動作を保護し、階層・密度・モーション・アクセシビリティを点検したうえで影響の大きい問題を修正する」のように、目標と保護条件を一緒に伝えることを勧めています。
| 区分 | スタイルプロンプト中心 | 契約中心ワークフロー |
|---|---|---|
| 色・余白 | モデルが画面ごとにもっともらしい値を選ぶ | 決定IDに結び付いたトークンを再利用 |
| コンポーネント状態 | 基本状態だけを作り、エラー・ローディングを漏らしやすい | 状態マトリクスと適用しない状態の理由まで記録 |
| 修正基準 | 「もっと洗練させて」のような主観的フィードバック | 原則・契約・同一経路のレンダリング証拠で判断 |
| 次のセッション | 会話が変わると説明を再度伝える | リポジトリのDESIGN.mdとシステムファイルを再読 |
| 不明な値 | 平均的なデフォルト値で空欄を埋める | 未決定の値は省略し、重要な決定だけを質問 |
DESIGN.md Core v2はこれを7つの領域に整理します。エクスペリエンス、基盤、タイポグラフィとアセット、コンポーネントと状態、レイアウトとプラットフォーム、コンテンツとロケール、ガバナンスです。特に、確認されていない値をもっともらしいデフォルトで埋めず、空欄のままにすることを定めています。デザイン文書を「ムードボードの説明書」ではなく、人とエージェントがともに読む実行契約にしたわけです。
トークンをツール間で交換できる形に構造化するという方向性は、oh-my-designだけの発想ではありません。Design Tokens Community Groupのフォーマット仕様も、デザイントークンを複数のツールがやり取りできる標準ファイル形式として表現し、統合コストを下げることを目指しています。oh-my-designは、そこに値の出所と決定理由、コンポーネント状態、検証手順を加えたアプローチと捉えられます。
93個の契約があっても品質が自動で保証されるわけではありません
契約の数より重要なのは、プロジェクトに合う契約を選び、実際の画面で検査したかどうかです。公式のアンチスロップ文書も、角丸カードや紫色のアクセントだけを問題とは判定しません。まずユーザー・タスク・既存動作・DESIGN.mdを読み、文脈のないパターンが何度も繰り返され、階層や信頼を損なっているかを確認するよう説明しています。
アクセシビリティも同じ原理です。「アクセシビリティを考慮する」という文だけでは検査できませんが、通常テキストのコントラスト比4.5:1やキーボードフォーカスの視認性のような観察可能な条件はテストできます。WCAG 2.2にはテキストのコントラスト比だけでなく、フォーカスが隠れてはならないという基準も含まれています。 したがって契約は、好みを絶対化する規則ではなく、測定できる品質とプロジェクト固有の選択を分ける装置であるべきです。
ベンチマークの数値は仮説として見てください。
プロジェクトの変更記録には、同一のフィクスチャとブリーフで初回レンダリングの欠陥が7件から3件に減り、入力トークンが47%減少したという内部測定があります。 ただし、外部の独立評価や多様なプロジェクト標本は公開されていません。導入の判断はこの数値よりも、皆さんの画面で状態の漏れ、アクセシビリティエラー、デザインドリフトが実際に減ったかどうかに基づけるべきです。
国内の実利用紹介でも繰り返し挙がる問題は、「最初の画面の美しさ」よりも、ページが増えるにつれてボタンの形や色値が変わる一貫性の崩壊です。DESIGN.mdをプロジェクトの共通基準に置くというアプローチはこの問題によく合いますが、「一貫性100%」のような表現を検証済みの保証として受け取るべきではありません。
自分のプロジェクトで小さく検証する4段階
- 実際のプロジェクトルートに導入し、状態を確認してください。
npx oh-my-design-cli@latestを実行してからエージェントを再起動し、npx oh-my-design-cli@latest doctorでスキル・ロール・カタログとDESIGN.mdの状態を確認します。公式ドキュメントではNode.js 18以上を最低条件として案内しています。 - ブランド名より先にプロダクトのタスクを書いてください。
「Tossスタイル」で終わらせず、「忙しい親が家族の食事を素早く記録するアプリ。記録完了が主行動で、既存のロゴとデータフローを保持する」のように、ユーザー・主行動・保護する動作を明記してください。確認されていないプロダクトの事実は、書く前に質問するよう依頼します。 - 画面1つと4種類の状態で試してください。
ホーム全体を作り直すより、検索結果や決済完了のように境界が明確な画面を選びます。基本・ローディング・空・エラー状態を作り、既存コンポーネントの再利用有無とキーボード移動・コントラスト比・モバイルリフローを確認してください。 - 結果ではなくドリフトを比較してください。
2つ目の画面を追加した後、同じトークンとボタン状態が維持されているかを見ます。DESIGN.mdにない値が新たに生じたか、修正理由を決定IDで追跡できるか、同じ経路を再レンダリングしたときに回帰がないかを記録してください。この3項目が減らなければ、スキル数が多くても導入効果は低いです。
さらに深掘りしたいなら
GitHub - kwakseongjae/oh-my-design — 22個のスキル、19個のロール、93個のプリセット契約と、全体の派生構造を確認できる公式リポジトリです。 github.com
Skills — oh-my-design CLI — スキルがシステム管理・画面制作・品質検証・ライティング・参照収集にどう分けられているかを確認できます。 oh-my-design.kr
Workflows — oh-my-design CLI — 新しいシステム構築、新画面制作、既存画面改善にそのまま使える自然言語の依頼例があります。 oh-my-design.kr
DESIGN.md Core v2 — Portable Design Contract Specification — DESIGN.mdの7領域、権限関係、未決定値の扱い、適合性段階を含む公式仕様です。 github.com
Design Tokens Format Module 2025.10 — デザイントークンをツール間で交換するためのDTCGフォーマットの目的とデータ構造を確認できます。 designtokens.org
Web Content Accessibility Guidelines (WCAG) 2.2 — コントラスト比、キーボードフォーカス、リフローなど、デザイン契約に入れられるアクセシビリティ基準の原文です。 w3.org
