はじめに
AI 駆動開発によって、Web アプリケーションを短時間で作り上げること自体は、もはや特別なことではなくなった。
一覧画面、詳細画面、フォーム、認証、簡単なフィルタやダッシュボード程度であれば、フロントデザインまで含めて、いわゆるバイブコーディングで一気に形にできる。
このスピードは、PoC や検証用途、単機能ツールにおいては非常に有効である。
一画面、あるいは数画面で完結する用途であれば、デザインシステムを導入しなくても何も困らない。
むしろ、最初から厳密な設計を持ち込む方が非効率ですらある。
しかし、このやり方をそのまま「本番稼働するアプリケーション」に持ち込んだ瞬間、問題は必ず表面化する。
そしてその問題は、見た目の好みや UI の微調整といったレベルの話ではない。
本番稼働で顕在化する問題は「統一されていないこと」そのもの
本番稼働において致命的になるのは、ボタンの色が少し違う、といった軽微な話ではない。
アプリケーション全体としての設計された一貫性が失われることが問題である。
例えば、ある画面では一覧から詳細がスライドペインで開く。
別の画面ではモーダルが表示され、さらに別の画面ではページ遷移が発生する。
色のトーンは画面ごとに大きく異なり、情報密度や余白の取り方も揃っていない。
これらは単体で見れば、それぞれ「あり得る設計」である。
スライドペインも、モーダルも、ページ遷移も、それ自体が間違いというわけではない。
問題は、それらが何の原則も共有せず、同一アプリケーション内に混在することにある。
ユーザーは、もはや一つのアプリケーションを使っている感覚を持てなくなる。
画面が変わるたびに、操作の前提を読み直す必要が出てくる。
どこまでが一覧で、どこからが詳細なのか。
戻る操作は安全なのか、それとも文脈を壊すのか。
これは UX の微調整の話ではない。
プロダクトとしての信頼性が崩れるという話である。
なぜ開発初期には問題が見えないのか
この問題は、開発初期にはほぼ確実に見過ごされる。
なぜなら、画面を一つずつ見ている限り、どれもそれなりに完成して見えるからである。
PoC や単機能ツールでは、そもそも問題にならない。
画面数が少なく、文脈も単一であれば、バイブコーディングは合理的な選択である。
しかし、画面数が増え、機能が増え、「アプリケーション」になった瞬間から状況は変わる。
画面単位では成立していた実装が、アプリケーション単位では破綻する。
「アプリ全体で統一しろ」というプロンプトが無力な理由
多くの人はここで、「アプリケーション全体でデザインを統一しろ」という指示を AI に与えようとする。しかし、この種のプロンプトはほとんど意味を持たない。
LLM にはアプリケーション全体を“同時に保持し、比較し続ける”能力がないからである。
実際のアプリケーションでは、
数十の画面が存在し、それぞれに微妙に異なる UI 実装が散在している。
- どの色が多く使われているのか、
- どの詳細表示パターンが主流なのか、
- どの画面が例外で、どれが基準なのか。
これらを把握するためには、
アプリ全体を一つの構造物として同時に記憶し、相互に比較し続ける必要がある。
しかし LLM の思考は、常に「与えられたコンテキストの範囲内」で完結する。
どれだけ長いプロンプトを書いたとしても、どれだけ多くのファイルを読み込ませたとしても、それは常に 部分的なスナップショットに過ぎない。
その結果、LLM は次のような振る舞いを取らざるを得なくなる。
- 直近で見た画面を基準にする
- 文脈的にもっともらしい UI を生成する
- 「改善案」として新しい解を提示する
これは「統一」ではなく、単なる再生成である。
さらに致命的なのは、統一とは本質的には「生成」ではなく「選別」の作業であるという点だ。
アプリ全体を統一するためには、
- どの実装を正とするか
- どの実装を捨てるか
- どの差分を吸収し、どこを例外とするか
といった、設計上の決断が不可欠になる。
これは「もっともらしいものを作る」能力とは別種の能力であり、判断基準（真実）が外部に固定されていなければ成立しない。
バイブコーディングで作られたアプリケーションにはその判断基準が存在しない。
すべての画面がそれなりに正しく、しかし、どれも基準ではない。
統一に必要な前提条件が、そもそも与えられていないのである。
ここで初めて「デザインシステム」が必要になる
だからこそ、フロントエンドにおいては、画面を実装する前にデザインシステムを定義する必要がある。
ここで言うデザインシステムとは、見た目をおしゃれにするためのものでもデザイナーのための資料でもない
アプリケーション全体で共有されるデザイン上の決定事項を、画面実装から切り離し、全画面に配布するための構造である。
デザインシステムの考え方
フロントエンドのデザインは、システマチックに管理されるべきだと長らく言われてきた。
Atomic Design はその代表例である。
Atomic Design の細かな分類自体は、いまや本質ではなく、重要なのは、「意味を持たない層」と「意味を持つ層」を分離するという発想である。
AI 駆動開発において、この考え方はさらに重要になる。
トークンと Primitive の役割
トークン（Token）
トークンは、アプリケーション全体のテーマを定義する。
- 色
- タイポグラフィ
- 余白
- 角丸
- ダークモード
ここには意味も振る舞いも存在しない。
値だけを一箇所に集約する。
Primitive
Primitive は、画面を構成する最小単位の UI 要素である。
- Button
- Input
- Select
- Dialog
ここで重要なのは、Primitive 自体に意味を持たせないことだ。
ボタンは「押せる」だけであり、登録・削除・キャンセルといった意味は、画面に配置されて初めて生まれる。
画面実装（Screen）の責務
画面は意味を持つが、見た目を持たない。
画面実装の役割は、
-
データをどう見せるか
-
どういう操作を提供するか
を定義することであり、 -
色を決める
-
余白を決める
-
状態の見せ方を決める
ことではない。
レイヤー構成の整理
この考え方を整理すると、次のようなレイヤー構造になる。
| layer | example | framework | implement file / folder |
|---|---|---|---|
| token | color, typography, spacing, radius, theme | Tailwind CSS | src/app/globals.css |
| primitive | button, input, select, dialog | shadcn/ui | src/app/design-system/primitives/* |
| screen | xxx-list-page, xxx-detail-page | React / Next | src/app/**/page.tsx |
デザインシステムとして「先に用意するもの」と、画面実装に残る責務
ここまで述べてきたように、AI 駆動開発においてフロントデザインシステムを導入する目的は、画面ごとの実装からデザイン上の判断を排除することにある。
そのために、実装前に人間が用意するものと、画面実装（Screen）において行われる判断とを、明確に分離しておく必要がある。
デザインシステムとして「作っておく」もの
まず、デザインシステムとして事前に用意されるのは、Token と Primitiveである。
-
Token は、アプリケーション全体で共有される視覚的な値の参照点であり、色、タイポグラフィ、スペーシング、角丸、テーマ切り替えといったあらゆる視覚的決定の根拠を一箇所に集約したものである。
ここでは「どの値を使うか」は決まっているが、それがどこで使われるか、どの操作に結びつくかといった意味は一切分からない。
Token はあくまで「値の名前」であり、意味を持たない。 -
Primitive は、その Token を消費する最小単位の UI 要素である。
Button、Input、Dialog といった Primitive は、- 見た目
- 状態（hover / focus / disabled）
- variant の語彙
を内部にすべて閉じ込めており、
画面側が見た目に介入できない構造になっている。
重要なのは、Primitive 自体も業務的な意味を持たないという点である。
ボタンは「押せる」だけであり、それが登録なのか削除なのかキャンセルなのか、といった意味は与えられていない。
Screen に残される唯一の判断
一方で、画面実装（Screen）に残されている判断は、ただ一つである。
「この操作は、どの意味を持つか」
そして、
「その意味は、どの Primitive / variant に対応するか」
という判断である。
画面実装時に行われるのは、
- この操作は主要操作なのか
- 補助的な操作なのか
- 破壊的なのか
- 可逆なのか
といった 意味論的な分類であり、
色やサイズ、余白といった視覚的判断ではない。
したがって、
- primary の Button を使うか
- secondary にするか
- destructive にするか
といった選択は、デザインを考えているのではなく、操作の意味を UI の語彙にマッピングしているに過ぎない。
なぜこの分離が重要なのか
この分離が成立していれば、画面実装者（人間であっても AI であっても）は、新しい見た目を生み出すことができない。
選べるのは、
- 事前に定義された Primitive
- 事前に定義された variant の集合
だけであり、もし「適切なボタンが存在しない」と感じた場合は、画面側で場当たり的に対応するのではなく、デザインシステム側に立ち戻って Primitive を拡張する必要がある。
このルールによって、
- デザインの判断は常に中央に集約され
- 画面は意味と構成に専念し
- アプリケーション全体の一貫性が保たれる
という構造が成立する。
Screen は「選ぶ」が、「決めない」
この設計を一言で表すなら、次のようになる。
- デザインシステムは決める。
- Screen は選ぶ。
Screen が行うのは、既に決められた UI 語彙の中から、その画面の意味に最も適したものを選択することだけである。
この境界を明確にしなければ、AI は必ず視覚的判断に踏み込み、アプリケーションは再び画面単位で分裂していく。
Tailwind CSS v4 と shadcn/ui を使う理由
フロントエンドのライブラリやフレームワークは数多く存在し、更新も激しい。
どれが最善かを一般論で語ることには意味がない。
重要なのは、
- トークンを一箇所に集約できること
- Primitive をコードとして配布できること
- 画面実装からデザイン判断を排除できること
である。
- Tailwind CSS v4 では、色などのトークンを globals.css に直接定義できる。
- shadcn/ui は、Primitive を「自分のコード」として管理できる。
この組み合わせは、思想を実装に落としやすい。
AI にルールを守らせるために必要なこと
これらをテックスタックとして選ぶだけでは不十分である。
重要なのは、AI が参照するルールとして明文化することだ。
そのためにDESIGN.md を用意する。
DESIGN.md には、
- デザインシステムの思想
- レイヤーごとの責務
- AI が判断してよい範囲
- 判断してはいけない範囲
を明示的に書く。
BMAD-METHOD を使った AI 駆動実装ワークフロー
デザインシステムを AI 駆動開発に組み込むために、BMAD-METHOD を使って、カスタムエージェントを作成する。
このエージェントには以下のようなワークフローをもたせる。
-
init-frontend
- フロントエンドのライブラリ・フレームワークを決定
- デフォルトは Tailwind CSS v4 + shadcn/ui
- globals.css に基本的な Token を定義
- DESIGN.md を作成し、以降の実装で必ず参照させる
-
create-design-system
- Button、Input などの基本 Primitive を shadcn/ui から導入
- 必要に応じて見た目や振る舞いを調整
-
implement-with-ds
- DESIGN.md に従って画面を実装
- 画面では Primitive を選択して組み合わせるだけ
- トークンやスタイルの直接指定は禁止
-
modify-design
- 新しい要件で Primitive が足りなくなった場合
- 画面側で場当たり対応せず、Design System を更新する
このように、
デザイン整備 ↔ 画面実装を往復するワークフローを明示的に導入する。
おわりに
バイブコーディングは、画面単位では成立する。
しかし、アプリケーション単位では成立しない。
アプリケーションとして成立させるためには、
デザインを生成させる対象から、配布される前提へと昇格させる必要がある。
最後にDESIGN.mdのサンプルを載せておく。
## Purpose
This document defines how frontend UI must be implemented.
Its goal is to ensure visual consistency across the entire application,
especially in AI-driven development.
This is a rule document, not a tutorial.
---
## Core Principle
UI consistency must be achieved structurally, not by instructions.
Screens must not decide design.
Design decisions must be centralized and distributed.
---
## Layer Responsibilities
### Token
- Defines global visual values (colors, spacing, typography, theme)
- No behavior, no meaning
- Defined once and shared everywhere
Location:
- globals.css
Rules:
- Values only
- No component or screen logic
---
### Primitive
- Defines reusable UI building blocks
- No business meaning
- Consumes tokens only
- All visual states are defined here
Location:
- design-system/primitives
Rules:
- Screens must not override styles
- New visual behavior must be added here, not in screens
---
### Screen
- Defines layout, data, and meaning
- Composes primitives only
- Must not define visual values or styles
- May choose which primitive and which variant to use based on the semantic meaning of the action
Location:
- app routes / pages
---
## AI Usage Rules
- AI must not invent design values
- AI must not hardcode styles in screens
- If a new visual pattern is required, update primitives first
If the design system is insufficient, stop and modify it.
Do not bypass it.
---
## Summary
Design system exists to remove decisions from screens.
If AI needs to decide visual details, the system is underspecified.