自作のデザインシステム
@gunjo/ui（群青／gunjo.jp（gunjo.jp を新しいタブで開く）） を、群青を一度も見たことのない 予備知識ゼロのAI に170画面組ませてきた連載のまとめ第1弾。今回は ユースケース別の対応表（by-use-case）（gunjo.jp を新しいタブで開く）（gunjo.jpのdocsにある、やりたいことからコンポーネントを引く一覧）の設計で見つかった 6つの罠を、実際のroundつきで並べます。
なぜ「対応表の罠」を語るのか
「AIから使えるデザインシステム」を売りにするなら、この対応表は避けて通れません。docsを読んでも目的のコンポーネントに たどり着けないなら、そのコンポーネントは 無いのと同じだからです。
だから群青は最初から ユースケース別の対応表（gunjo.jp を新しいタブで開く） を用意しました。「経路検索の結果カードを作りたい」→ ListCard、「請求書の金額内訳を出したい」→ AmountBreakdown、というふうに、やりたいことからコンポーネントを引ける一覧です。
でもこの対応表は、間違って誘導すると、そもそも「載せない」より危険です。載っていなければ使う人は手組みに向かいますが、「あると思って使い、詰まる」ほうが、成功と勘違いされて発見が遅れるからです。170画面のコールドテストで、その罠を 6種類のパターンに整理できました。
パターン①：意味のキーワードは合うが、UIの形が逆
例: 対応表で「経路 (route)」を引くと Itinerary（旅程用・縦に手順を積むコンポーネント）に誘導されます。でも本当に欲しかったのは、横に並んだA→Bの区間ヘッダ——OriginDestination でした。
- #166国際物流（仕出→仕向）で手組み
- #169鉄道路線別実績（起点→終点）で手組み
- #170鉄道特急予約（東京→新大阪）で手組み
この3画面が独立に「Itinerary は縦に積む形なので、横のA→Bが組めない」と予備知識ゼロのAIに書かれ、3回確認を満たして OriginDestination を実装しました。意味のキーワードは合うのに、UIの形が逆という罠です。
タップして拡大表示クリックして拡大表示
対応表の是正：tracking timeline → RouteStops がHH:MM止まりだった誤誘導を「複数日は dateLabel と明記」で塞ぎ、A→Bのヘッダは OriginDestination へ誘導し直しました。
パターン②：見た目は近いが、意味が逆（扱う対象の取り違え）
例: 対応表で「2人を並べる」を引くと RelationshipRow（上司↔部下）が出ます。でも RelationshipRow の from / to の型は PersonCellProps に固定されていて、会社×制度のような組織どうしのペアには型が通りません。
- #160求貨求車（荷物×空車の二者間マーケット）
- #172 M&A（買い手×売り手・会社×会社）
- #173補助金マッチング（自社×制度・会社×制度という種類の違うペア）
3回目の #173で、予備知識ゼロのAIは「アバター＋在席ドットの人モデルを組織に強制してくる。財務データのスロットも、スコアや要因内訳の領域もない。追加すべきは、人を前提としない MatchCard と、PersonCell の組織版 CompanyCell」と正確に切り分けました。→ 2つのコンポーネントを同時に実装。
MatchCard は left/right をあえて ReactNode にした（型を CompanyCellProps に固定しなかった）ので、会社×制度のような種類の違うペアでも使えます。見た目が近いことは、意味が正しいことと同じではない、という罠でした。
パターン③：表示専用のコンポーネントを、入力に見せる（すり替え罠）
例: 対応表で「星の評価を入力させたい」を引くと Rating が出ます。しかし Rating は role="img" の表示専用で、onChange も、フォーカスできる星も持っていません。予備知識ゼロのAIが善意で onChange を配線しても、無反応で詰まります。
- #150タクシー乗車後評価（5段階星＋良かった点タグ）
- 使う人が動くUIと信じて実装 → 無反応 → 発見が遅い（最も危険な罠）
これは予備知識ゼロのAI自身が「動くコンポーネントに見えるが動かない」と表現した、すり替え罠の典型例です。足りないコンポーネントなら使う人は「無いから手組み」に向かえますが、「あると思って使い、詰まる」罠は、成功と勘違いされて発見が遅れます。この気づきが、入力用の RatingInput を課題として記録することと、対応表側に「Rating は表示専用」と明記することにつながりました。
パターン④：時間の精度が違うのに、名前が近い（時刻vs時間帯）
例: 対応表で「集荷の時間帯を選ぶ」を引くと TimePicker が候補に出ます。でも TimePicker はHH:MMの「正確な時刻」を選ぶコンポーネントで、「午前 / 12-14時 / 16-18時」のような離散的な時間帯は選べません。
- #164荷主ポータル 集荷依頼（配送業界の「時間帯」発注）
- #165宅配便 個人向け 再配達（受け取り時間帯）
予備知識ゼロのAIは #164で TimePicker を手組みで避け、#165では最初から SegmentedControl を選びました（対応表も是正済み）。「時間帯 → SegmentedControl / RadioGroup」に誘導し、TimePicker は「正確な時刻」だけに絞ることで、時間の精度の軸の罠を塞ぎました。
パターン⑤：単一選択と複数選択を、同じ名前で誘導
例: 対応表で「カード行を並べる」を引くと ListCard が出ます。でも ListCard.onSelect は、カード全体を1つの <button> にしてしまう（aria-pressedのトグル）ので、単一選択の意味になります。モバイルの経費履歴などで、複数選択＋一括操作の BottomActionBar をつけたいときにこれに引っかかると、カードの中にボタンを入れ子にしてしまい、不正なHTML ＋フォーカス順の崩れで詰まります。
- #149タクシー乗車履歴（月別履歴＋経費の複数選択＋一括ダウンロード）
- 「モバイルで複数選択」→
ListCard+Checkbox+BottomActionBarに是正済み
この罠は、書類ダウンロード行（DocumentRow）は ListCard では構造的に不可能という、次回のまとめ記事「『作るべき理由』には強さの段階がある」の主題にもつながります。
パターン⑥：粒度違い（親と子で片方だけが載っている）
例: 対応表で「案件一覧＋一括割当」を引くと、DataTable は出ますが、ActionDataTable（複数選択＋行アクション）は載っていません。予備知識ゼロのAIは DataTable を選び、複数選択を手組みしてから「実は ActionDataTable が既存だった」と気づきます。
- #159トラック運送 配車管理（案件一覧の一括割当）
- 対応表を是正し「案件一覧＋一括割当 →
ActionDataTable」と明記
「載せない」は、無いと分かれば手組みするだけで済みます。でも親だけ載せて子を隠すと、使う人は親で足りると思い、子の存在に気づきません。粒度の軸で、親と子の両方を対応表に載せておく必要があります。
同じ罠は Meter の仲間でも出ました。ExpiryBadge（期限）/ ReferenceValue（範囲）/ Meter（容量）/ LimitMonitor（名前付き上限）という4兄弟が揃うまで、予備知識ゼロのAIは毎回 Meter target に誤誘導されて、拘束時間や運賃の比較で詰まっていました。
タップして拡大表示クリックして拡大表示
対応表の質は4つの軸で評価すべき
170画面で見えた落とし穴を集めると、この対応表の質は4つの軸で評価する必要があると分かりました。
- 型 (Type) — そのコンポーネントのPropsに、狙いの引数が入るか（
RelationshipRowはCompanyCellPropsを受け付けない） - アクセシビリティ (a11y) — 意味が正しいか（
ListCard.onSelectのaria-pressedは「単一選択のトグル」で、複数選択には使えない） - 形 (Shape) — 横A→Bか、縦のシーケンスか（
OriginDestinationvsItinerary） - 扱う対象 (Domain) — 人モデルか組織モデルか（
PersonCell/RelationshipRowvsCompanyCell/MatchCard）
この4軸のどれかですり替わっている対応表は、使う人を「あると思って使い、詰まる」に落とします。無いことを正しく伝える正直な対応表も、正解の一つです。
まとめ
- 対応表は「すり替える」ほうが「載せない」より危険（発見が遅れる）
- 170画面のコールドテストで、すり替え罠は 6種類のパターンがあった:
- 形の軸（縦vs横）
- 扱う対象（人vs組織）
- モード（表示vs入力）
- 時間の精度（時刻vs時間帯）
- 選択のスコープ（単一vs複数）
- 粒度（親と子）
- 対応表の質は 型 / アクセシビリティ / 形 / 扱う対象の4軸で
- 正直な対応表（
Ratingは表示専用、と明記する）は、隠す対応表より安全
「AIから使えるデザインシステム」を作るなら、対応表の設計は「書式」ではなく「設計判断」です。予備知識ゼロのAIが誤誘導される回数を、「見つからない」ではなく「あると思って使い、詰まった」で数えると、直すべき優先順位が変わって見えます。
関連
- ユースケース別の対応表 (by-use-case)（gunjo.jp を新しいタブで開く） — 群青の対応表本体
- /cold-tests/why（考え方のページ）（gunjo.jp のコールドテストの記録を新しいタブで開く） — 3回確認の方法論
- /cold-tests（カタログ）（gunjo.jp のコールドテストの記録を新しいタブで開く） — 175画面の常設カタログ
- 総集編（Zenn）（Zenn を新しいタブで開く） — 170画面で見えた5つの法則
この記事はZennにも掲載しています。Zenn版（Zenn を新しいタブで開く）
この記事のもとになった記録は、本にまとめました
『あなたがAIにUIを作らせると、何が起きるか』
予備知識ゼロのAIに、実在する業種の業務UIを175枚作らせ続けた記録です。何が組めて、何が組めなかったか。全175回の採点と、生まれた26コンポーネントの年表を載せています。
- Zenn版（Zenn を新しいタブで開く）（序章と第7章は無料で読めます）
- Amazon Kindle版
この連載は、作者がAI（Claude）と協働で制作しています。実験・検証の設計、判断、公開前の事実確認は人間が行い、実作業と下書き執筆はAIが担っています。
