AIにUIを生成させる前に、何をコンテキストに書くべきか — デザインシステム側の不備とどう付き合うか

この記事について

AIにUI画面を自律的に生成させる検証を進めています。入力はコードとコンテキストファイル。「コードを Single Source of Truth とする」という前提に立ったとき、AIに何を渡せば画面が組めるのかを確かめる試みです。

本記事は、そのうちコンテキストファイルの設計に絞っています。生成の検証結果はまだありません。設計段階で下した判断と、その理由の記録です。

執筆にあたっての役割分担も先に明示しておきます。

• 検証：実装コードと実測値（computed style）
• 記録：作業中のLLMとの対話ログ
• 記事化：LLM
• 事実確認と判断：筆者

記事化をLLMに任せているのは、この記事の対象が「LLMとの協働で積み上げた判断」そのものだからです。数か月分の判断を後から記憶で書き起こすより、同時記録から起こしたほうが、行き止まりだった経路が残ります。ただし要約は真っ先に失敗を削る方向に働くので、そこは意図的に残しました。

なお本記事は、コードをSSoTとする前提に立った上で「では何をコンテキストに書くか」を扱います。その前提自体の是非、すなわち画面生成の起点をどこに置くべきかという議論は扱いません。

前提：コードを正とすると、何が足りないか

本検証は、コンポーネントライブラリとトークン定義がコードとして存在している環境が対象です。デザインシステムの実体がコードにある以上、AIが参照すべきもそこだろう、という前提に立っています。他の入力形式との優劣はここでは扱いません。

そのうえで最初に分かったのは、コードだけでは足りないということでした。コンポーネントは個々の部品の仕様しか持っていません。「この部品とこの部品をどう並べるか」「どこに余白を持たせるか」「ブレイクポイントを跨いだときに何を差し替えるか」は、コードのどこにも書かれていない。

人間はこれを、既存画面を眺めたり、周囲に聞いたりして補っています。AIに自律生成させるなら、その暗黙の部分を明示的に渡す必要がある。それがコンテキストファイルです。

では、その中身をどうやって決めるか。進め方としては、まず代表的な画面をいくつか人手で実装します。以下これをサンプル画面と呼びます。既存のデザインデータを見ながら組み、そのとき自分が何を判断したのかを規則として抽出して、コンテキストファイルに落とす、という順序です。

つまりデザインデータは、生成時にAIへ渡す入力ではありません。人間が規則を導くための材料として使い、導いた規則だけがコンテキストに残ります。

以下は、その過程で何を書き、何を書かなかったかの記録です。

課題1：知見が出てくるが、全部書くと使えない

サンプル画面を手で作りながら知見を溜めていくと、当然ながら大量に出ます。ここで最初に躓きました。全部書くとコンテキストが膨らみ、肝心の判断材料が埋もれます。

選別の基準として置いたのはこれです。

AIが画面を組むとき、これを参照するか？

この基準で切ると、出てくる知見は綺麗に二分されました。

参照する（＝書く）

• コンテナの階層構造と、どこが余白を持つか
• パンくずの有無で上部パディングが変わるといった、条件付きのルール
• ブレイクポイントごとのコンポーネント差し替え
• 表示モードによってトークンの解決結果が変わる箇所

参照しない（＝書かない）

• デザインツールのAPIをどう叩いたか
• デザインデータの構造をどう探索したか
• 実装検証にあたって使ったツールの限界

後者は、人間が構築作業を進めるうえでは重要な知見です。詰まった時間も長い。しかしAIが自律生成するとき、AIはデザインツールを見ません。参照されない知識をコンテキストに書くのは、単なるノイズです。

作業ログとして残す価値と、コンテキストに載せる価値は別物でした。ここを分けずに「せっかく得た知見だから」と全部書いていくと、コンテキストファイルは短期間で読み通せない分量になります。分量が増えること自体より、AIが参照しない情報が参照すべき情報を埋めてしまうことを避けたい、という判断です。

課題2：見た目が同じなのに、構造が違う

複数のサンプル画面を突き合わせると、視覚的には同一なのに、デザインデータ上の構造が異なるケースが出てきました。同じ余白が、ある画面では親コンテナのgapで、別の画面では子要素のpaddingで表現されている、といった類です。

最初はこれを「どちらが正しいのか」という問題として扱おうとしました。デザインデータを遡って意図を特定しようとしたわけです。これは筋が悪かった。

差異の多くは意図ではなく、作成時期や作業者に由来する揺れでした。そして重要なのは、AIは一貫したルールを1つ必要としているのであって、揺れの網羅的な説明を必要としていないということです。

そこで方針を変えました。

デザインデータへの忠実性より、ルールの一貫性を優先する。

具体的には、余白の帰属について次の規則を立てました。

余白は親コンテナが持つ。隣接する余白の値が変わる箇所が、階層の境界である。

これはデザインデータ上のすべてのケースを説明する規則ではありません。しかし、これに従って組めば全画面が一貫した構造になり、見た目も一致します。そして何より、AIが判断に迷わない。

「デザインデータを正しく読み取る」を目標に置いていたら、この決着はつきませんでした。目標は「一貫した規則でサンプル相当の出力が得られること」であって、それは規則を宣言することで満たせます。

課題3：SSoT側に不備があるとき

「コードをSSoTとする」と決めても、そのコードが常にデザイン仕様を再現できるとは限りません。実際、いくつかのコンポーネントで再現不能な差分が出ました。型に応じた分岐を持っていない、ラベルが単一文字列で複数行にできない、内部で常に特定の要素をレンダリングしていて差し替えられない、といったものです。

ここでの判断が、たぶんこの検証で一番効いています。

コンポーネント本体は直さない

直したくなります。しかしコンポーネントライブラリは他所でも使われており、検証のために本体を触ると、検証していたはずの前提が崩れます。SSoTを検証しているのに、SSoTを都合よく書き換えては意味がない。

もう少し踏み込むと、本体を直すという判断自体が、この検証の中では下せないものです。共有されているコンポーネントの仕様変更が妥当かどうかは、他の利用箇所すべてを含めて評価されるべきで、ひとつの画面がひとつのデザイン仕様を再現できないという事実だけでは決まりません。ここで自律的に直すと、検証は通りますが、その判断が正しかったかどうかは誰にも確かめられない状態になります。

だから直さずに記録に回します。次に述べる台帳は、この「自分では決められない変更」を、決められる人に渡すための形式でもあります。

回避策には基準を設ける

• className などで外側から上書きできる → 回避策を実装する。ただし最小単位に局所化し、インラインコメントで理由を残す
• 上書きできない → 回避策を作らず、記録に回す

「頑張れば再現できる」を追いかけないことにしました。追いかけた実装は、コンポーネントの内部構造に依存するので、ライブラリが更新された瞬間に壊れます。

再現できないものを台帳にする

再現不能だった差分は、専用のファイルに1件ずつ記録しています。現時点で16件。

この台帳が、当初想定していなかった副産物になりました。デザインシステムのAI駆動開発への適合度は、成功した画面の数ではなく、回避策の件数で測れるからです。

件数が増える箇所には偏りがあります。特定の型を持つコンポーネント群、特定のサイズ指定でしか有効にならないプロパティ。これは「AIが悪い」でも「実装者が悪い」でもなく、コンポーネント設計とデザイン仕様の間にあるズレの所在を示しています。改善要求を出すときの根拠として、感想より遥かに強い。

失敗を成果物として残す、という発想に切り替わったのはここでした。

副次的に出てきた地雷

コンテキストに書くべきと判断したもののうち、事前には予想していなかったものをいくつか。

トークンの二重定義

トークンが :root にしかなく、@theme inline 側に存在しない場合、エラーにならずに無視されます。無言で失敗するので、目視では気づけない。「両方に存在することを確認する」を明示的なチェック項目として書きました。

表示モードによる解決結果の差

同じトークン名でも、表示モードによって解決される値が変わるものと、変わらないものがあります。フォントサイズはモードに依存せずブレイクポイントにのみ依存する、といった具合に、依存軸が種類ごとに違う。ここを取り違えると、実測値を比較しても何が合っていないのか分かりません。

検証は必ず computed style で行う

クラス名が付いているかどうかは、意図した値が効いているかどうかの証拠になりません。当たり前のようでいて、AIに検証させると容易にここを混同します。実測値のみを判定材料にする、という原則をコンテキスト側にも書いています。

現時点の所感

コンテキストファイルの設計で難しかったのは、技術的な難所ではなく、何を書かないかの判断でした。

得られた知見をすべて書けば精度が上がる、という直感は誤りです。AIが参照しない知識は、探索空間を広げるだけのノイズになります。「AIが画面を組むときにこれを見るか」という問いを毎回通すだけで、書くべき量はかなり減りました。

もう一つは、SSoT側の不備を修正待ちにしないこと。不備は不備として台帳に残し、コンテキスト側は「この制約の下でどう組むか」を記述する。修正を待つと検証が止まりますし、待っている間に得られたはずの知見が得られません。

生成の検証はこれからです。ここで立てた規則がどこまで通用するかは、正直まだ分かりません。効くはずだと考えているのは知識の二分類と余白の帰属規則で、逆に不安があるのは回避策のインラインコメントがAIに正しく解釈されるかどうかです。この予測の当たり外れも、記録として残しておきます。