AIデザインが2画面目から崩れるとき — oh-my-designの93の契約

最初の画面は悪くないのに、次の画面から別の製品に見えるなら

AIコーディングエージェントで最初の画面を作ると、かなりもっともらしく仕上がります。問題は、設定、決済、検索結果のように画面を増やすときに起こります。同じ主要ボタンなのに色や角丸が変わり、読み込み・エラー状態が抜け落ち、新しいセッションでは以前に決めた余白まで改めて説明しなければなりません。

このとき、「Tossのようにすっきり」といったスタイル指示を長くするだけでは不十分です。エージェントがどの値をなぜ選んだのかを残し、次の画面でもその決定を再利用させる必要があります。

oh-my-designの興味深い点はまさにここにあります。核となるのは多くのスキルをインストールすることではなく、デザイン哲学を決定ID、トークン、コンポーネント状態、レンダリングレビューまでつなげることです。その結果をDESIGN.mdに残し、次の作業の出発点にします。 github +1

今やってみること：1画面に共通の基準を作る

最初から製品全体を作り直す必要はありません。既存の動作を維持すべき画面を一つ選び、インストール、契約の提案、承認、画面の検証までを一度つないでみてください。以下の手順は公開ドキュメントをもとにまとめたものであり、編集部がCLIを直接実行して確認した結果ではありません。

1. プロジェクトルートでインストールを開始します。
   Node.js 18以上、Gitリポジトリ、そしてインストール・認証済みのClaude Code・Codex・OpenCode・Cursorのいずれかを用意してください。npx oh-my-design-cli@latestを実行し、基本プロジェクトのインストール範囲を選択します。コアのローカルワークフローには、別途APIキーやMCPサーバーは必要ありません。 github +2
2. エージェントを完全に再起動し、インストール状態を確認します。
   Codexでは、プロジェクトローカルのロールを読み込むためにプロジェクトを信頼する必要があります。再起動後、同じルートでnpx oh-my-design-cli@latest doctorを実行し、スキル・エージェント・カタログ・DESIGN.mdに関する不足がないかを確認してください。 github +1
3. ユーザーと保護条件を含む最初の依頼を入力します。
   たとえば、「忙しい親が家族の食事を記録するアプリの、プロジェクト所有者向けDESIGN.mdを提案してください。Tossは参考資料としてのみ使い、検証済みの事実だけを維持してください。製品固有の事実は決定前に質問し、既存の動作とロゴを保護してください。承認前にDESIGN.mdを採用しないでください」と依頼できます。 oh-my-design +1
4. 提案ファイルを所有者が直接承認します。
   グラフに結合されたDESIGN.mdを採用するには、プロジェクト所有者または事前登録された外部権限コントローラーが、提案された正確なバイト列を確認して承認する必要があります。生成または実装したエージェントが自ら承認することはできません。 github +1
5. 境界が明確な画面を一つ改善します。
   採用済みのDESIGN.mdを先に読ませてから、「既存の検索動作とロゴは維持し、検索結果画面の階層と状態を改善してください」のように依頼します。成功基準は画面が派手になることではありません。既存の動作が維持され、目に見える変更と検証要約が出力され、新しいトークンと状態がDESIGN.mdの決定につながっていることを確認すればよいのです。 oh-my-design +1

93はUIテンプレート数ではなく、確認すべき契約数です

oh-my-designの93のプリセット契約は、完成画面93個をコピーしてくるライブラリではありません。基本要素、shadcn・Radix系のマッピングプリミティブ、コマース・マーケットプレイスのような画面ジャンル、参照から導かれた傾向という4層で構成されています。各コンポーネント契約は、構造、状態マトリクス、アクセシビリティ条件、トークンスロットを定義します。 github

したがって、プロジェクトに93個すべてを適用する理由もありません。検索画面なら、入力欄、ボタン、結果リスト、空状態、エラー状態のように、実際に使う要素の契約だけを選べばよいのです。契約の価値は数ではなく、適用する状態と適用しない状態の理由まで残すことにあります。

公式の構造は哲学から始まり、決定表、トークン、コンポーネント契約、レイアウト文法、実装、レンダリング批評、DESIGN.mdへと続きます。トークンやコンポーネント値がそれを生んだ決定表を参照していない、または宣言した原則がどのトークンにも影響していない場合、品質ゲートでは失敗に分類できます。 github +1

スキル数が違っても変わらない本体

以前知られていた22スキルと19ロールは、現在の規模ではありません。最新の公式Skillsページは27の製品スキルと20の専門エージェントを案内し、リポジトリREADMEはチャネル専用項目まで含めた全バンドルを28スキルと20ロールとして集計しています。 github +1

この差は、ドキュメントが異なる範囲を数えているために生じます。Cursorのインストール数もREADME内の記述が一致しないため、単一の数字として断定しにくい状況です。導入時には「スキルはいくつあるか」より、自分のエージェントとプロジェクトにどのファイルが実際にインストールされたかをdoctorの結果で確認するほうが正確です。

スキルはシステム生成、画面作業、レビューといった作業順序を担い、専門エージェントはアクセシビリティ・コンテンツのような狭い観点から根拠を補います。プリセット契約は実装結果が守るべき条件であり、DESIGN.mdはその条件と決定理由を次のセッションへ伝えます。数字が変わっても、この役割分担こそが製品の本体です。 github +2

契約は好みではなく、観察できる条件であるべきです

「アクセシビリティを考慮する」という文は良い意図を示しますが、合格かどうかを判定しにくいものです。一方、通常テキストのコントラスト比4.5:1、テキストを200%に拡大してもコンテンツと機能が維持されるか、キーボードフォーカスが見え、他のコンテンツに完全に隠されないかは検査できます。WCAG 2.2はこのような条件を具体的に定義しています。 w3

もちろん、契約に条件を書いたからといって、実際の実装のWCAG適合性が自動的に証明されるわけではありません。ロゴ・大きな文字・非アクティブなコンテンツのように、コントラスト比基準が異なる例外もあります。そのため契約は、プロジェクトの選択を固定する文書であると同時に、レンダリング結果を人がレビューするためのチェックリストであるべきです。 github +1

7→3と47%は可能性であり、保証ではありません

公式の変更履歴には、同じフィクスチャとブリーフにおいて、初回レンダリングの欠陥が7件から3件に減り、入力トークンが47%減少したという独自測定があります。重大度の高いP0・P1欠陥は、両方の条件で0件だったと記録されています。 github

ただし、標本数、実行の反復回数、使用モデル、統計的不確実性、外部の独立評価は公開されていません。すべてのプロジェクトの品質やコストが同程度に改善する根拠として使うのは難しいでしょう。自分のプロジェクトでは、初回レンダリングの欠陥数よりも、状態の欠落、新たに生じた恣意的な値、既存動作の回帰が次の画面で減ったかを確認するほうが実用的です。

さらに深く知りたいなら

GitHub - kwakseongjae/oh-my-design — 全体構造、93のプリセット契約の分類、インストールチャネルごとの差異を確認できる公式リポジトリです。 github.com

Getting started — oh-my-design CLI — プロジェクトのインストールからエージェントの再起動、doctorチェックまで、初回実行の順序を確認できます。 oh-my-design.kr

DESIGN.md Core v2 — Portable Design Contract Specification — 7つの固定領域、未確定値の扱い、所有者承認の境界を規範的に説明する仕様です。 github.com

Web Content Accessibility Guidelines (WCAG) 2.2 — コントラスト比、テキスト拡大、キーボードフォーカスなど、契約へ移せるアクセシビリティ基準の原文です。 w3.org