開発手法ガイド：アトミックデザイン編 — AI に粒度を指定して UI を量産する

🤖 AI 駆動開発でアトミックデザインが効く理由

AI コーディングツールに「このボタンのデザインを修正して」と指示するとき、 影響範囲がどこまで波及するか がわからないと安全にコミットできない。UI は再利用される要素が多く、一箇所の変更が予想外の画面を壊す。

アトミックデザイン（Atomic Design）は Brad Frost が 2013 年に提唱し、2016 年の書籍で体系化した UI コンポーネントを粒度で分類する手法 。2025 年現在は Design Tokens との統合で再評価されている。AI 駆動開発での効用は 3 つ。

本記事は開発手法ガイド：概要のシリーズ 10 本目。アトミックデザインの 5 階層、2025 年の柔軟運用、AI 駆動開発での活かし方を整理します。

🧬 アトミックデザインの 5 階層

Brad Frost の原典では 5 階層。化学の原子〜有機体の比喩で命名されている。

依存方向

下位（Atom 側）が上位（Page 側）を知らない 一方向依存 が原則。

Pages ──→ Templates ──→ Organisms ──→ Molecules ──→ Atoms
  （上位は下位に依存できるが、逆は禁止）

この向きを守る限り、Atom の変更は上位全てに影響しうるが、Atom の変更で Atom 側に予想外の波及はない。

🎨 2025 年は「Design Tokens + Atomic」

Design Tokens が Atom より手前の層

Brad Frost 自身が ブログ で述べているように、2025 年の実装は Design Tokens を Atomic の下に置く のが主流。

Design Tokens （色・間隔・タイポグラフィの最小単位）
    ↓
Atoms
    ↓
Molecules
    ↓
Organisms
    ↓
Templates
    ↓
Pages

Design Tokens とは

色やサイズを 意味のある名前 で管理する仕組み。

悪い: color: #3B82F6;
悪い: padding: 16px;

良い: color: var(--color-primary-action);
良い: padding: var(--spacing-md);

Shopify Polaris、shadcn/ui、Tailwind CSS（v4 の @theme）がトークンファーストの代表。AI に「この色を primary-action に揃えて」と指示できるのが大きい。

運用ツールセット

🛠️ 現代フロントエンドの必須技術 — Tailwind / レスポンシブ / ダークモード

アトミックデザインを実装する上で、 ほぼ必須 となる現代フロントエンドの技術が 3 つあります。これらを Atom レベルで揃えると、上位コンポーネントが自然に追従し、AI が量産しても見た目が崩れません。

1. Tailwind CSS — Utility-First で Atom を高速量産

Tailwind CSS は 「クラス名で直接スタイルを書く」 Utility-First のアプローチ。CSS ファイルを別途書かずに、HTML/JSX 内で完結します。

// 旧来：別 CSS / CSS-in-JS
<button className="primary-button">注文確定</button>
// styles.css で .primary-button を定義する必要

// Tailwind CSS：クラス名だけで完結
<button className="bg-primary text-white px-4 py-2 rounded hover:bg-primary-hover">
  注文確定
</button>

Tailwind v4 の @theme で Design Tokens 統合

Tailwind v4 から、 CSS だけで Design Tokens を定義 できます。

@theme {
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
}

これで bg-primary ・ p-md のように使え、 Design Tokens と Tailwind が一体化 。Atom を作る基盤が整います。

AI 駆動開発との相性

2. レスポンシブデザイン — モバイルファーストが基本

PC・タブレット・スマホで同じコンポーネントが 自動的に最適表示 される設計。Atom レベルで対応しておくと、上位コンポーネントが自然に追従します。

Tailwind のブレークポイント

<div className="
  text-base       // モバイル：16px（基本）
  md:text-lg      // 768px 以上：18px
  lg:text-xl      // 1024px 以上：20px
">
  価格表示
</div>

モバイルファーストの考え方

「モバイル → 段階的に大画面へ」が現代の定石。 基本スタイル = モバイル とし、md: ・ lg: で大画面向けに上書きする発想。逆順（PC 基本 → モバイルで縮める）にするとコードが汚くなります。

AI への指示テンプレート

PriceDisplay コンポーネントをレスポンシブ対応で：
  モバイル:   フォント 14px、横幅 100%
  タブレット (md:):  フォント 16px
  PC (lg:):       フォント 18px、横幅 auto

明示しないと AI は モバイル対応を忘れがち 。「レスポンシブで」を必ず指示に含めるか、 CLAUDE.md に必須要件として書いておきます。

3. ダークモード対応 — dark: プレフィックスで両対応

OS のテーマ設定や、ユーザー切り替えで ライト / ダーク両モード に対応するのが現代の必須要件。Atom レベルで対応すると、上位が自動追従します。

Tailwind の dark: プレフィックス

<button className="
  bg-white text-slate-900            // ライトモード
  dark:bg-slate-800 dark:text-white  // ダークモード
">
  注文確定
</button>

Design Tokens で両モード対応する設計

トークン側で両モードを定義しておくと、コンポーネントは モードを意識せずに書ける 。

@theme {
  --color-bg: #ffffff;
  --color-text: #1e293b;
}

@media (prefers-color-scheme: dark) {
  @theme {
    --color-bg: #0f172a;
    --color-text: #f1f5f9;
  }
}

これで bg-bg ・ text-text を使うだけで両モード完結。Atom が肥大化しません。

AI 駆動開発のチェックポイント

3 つを組み合わせた「現代の Atom」

// Tailwind + レスポンシブ + ダークモード が揃った Atom
<button className="
  bg-primary text-white                              // tokens
  px-4 py-2 rounded
  hover:bg-primary-hover
  text-sm md:text-base                               // レスポンシブ
  dark:bg-primary-dark dark:hover:bg-primary         // ダークモード
">
  注文確定
</button>

このレベルが揃って初めて、 AI が量産しても見た目が崩れない Atom 群が成立します。逆にここが揃わない状態で AI に量産させると、 見た目バラつき・モバイル崩れ・ダーク非対応 が一気に積み上がります。

🔄 「硬直的 5 階層」から「柔軟な実践」へ

2025 年のトレンド

Atomic Design in 2025: From Rigid Theory to Flexible Practice などで指摘されているのは：

• 「Atom と Molecule の境界で迷う時間が勿体ない」 → 必ずしも 5 階層に収めなくて良い
• 「Molecule 層はオプション」 → Atoms と Organisms だけで十分な場合も
• 「Behavioral Patterns」 → フォーム・モーダル・通知など挙動で分類する階層の追加

現実的な運用

多くのプロジェクトで採用されているのは Atoms / Molecules / Organisms の 3 層 。Templates と Pages はフレームワーク（Next.js / Astro / Nuxt）のルーティング機構に吸収されることが多い。

libs/ui/
  ├── atoms/      — Button / Input / Icon …
  ├── molecules/  — FormField / SearchBox …
  ├── organisms/  — Header / ProductCard …
  └── tokens/     — colors / spacing / typography

🎯 AI への指示にアトミックデザインを組み込む

指示テンプレート

階層: {Atom / Molecule / Organism}
名前: {コンポーネント名}
依存可能: {利用できる下位コンポーネント・tokens}
依存禁止: {API クライアント / グローバル状態 / ルーティング}
Storybook: {ストーリーを一緒に作成 yes/no}

例：

階層: Molecule
名前: PriceDisplay（金額表示コンポーネント）
依存可能: atoms/Label, atoms/Currency, tokens/spacing
依存禁止: API クライアント、グローバル状態
Storybook: 通常価格 / セール価格 / 0 円 / 巨大金額 のストーリー 4 本

この粒度で指示すると、AI が勝手に fetch したり、Context を使ったりする余地が消える。

レビューチェックリスト

• 下位階層のコンポーネントだけを import しているか（上位や同階層を使っていないか）
• API 呼び出し・ルーティング・グローバル状態を参照していないか（Organism までは NG、Template/Page で OK）
• Design Tokens を使っているか（ハードコードされた色・サイズはないか）
• Storybook にストーリーがあるか
• アクセシビリティ属性（aria-label など）が付いているか
• 命名がドメイン語彙と一致しているか（Btn1 ではなく PrimaryButton）

🔍 Storybook が AI 駆動開発の基盤

ストーリー駆動でコンポーネントを育てる

Storybook は コンポーネントの使い方を視覚的にカタログ化 するツール。AI に「PriceDisplay の使い方」を聞かれたとき、コードではなく *.stories.ts を参照させる方が正確。

指示例:
  atoms/Button に「ghost バリアント」を追加したい。
  button.stories.ts の既存パターンに倣って、ghost バリアントの
  ストーリーを追加し、そのあと Button.tsx に実装してほしい。

Storybook が整備されていると AI が「どう使うか」を学習できる 。これがない状態で AI にコンポーネント追加を任せると、使い方が分からず過剰な prop が生えたりする。

視覚回帰テスト

Chromatic や Percy で Storybook の差分を自動キャプチャすると、 AI が勝手に見た目を変えてしまう事故 を検知できる。CI に組み込むと安全。

🎭 AI 駆動開発でアトミックデザインが効く場面

1. 「Atom レベルで」と指示できる

「新しい IconButton を Atom として追加して。既存の Button との
  違いは icon 必須 / text 省略可 / 円形 / 40x40 固定。
  tokens の spacing/sm を使って padding を設定すること。」

階層を指定することで、AI が過剰な責務を Atom に持たせようとするのを防ぐ。

2. 粒度が揃っていると AI が画面全体を組み立てやすい

Atoms / Molecules の整備が進んでいるほど、「この Figma デザインから React コンポーネントを組み立てて」という指示が通りやすくなる。個別部品を組み合わせる発想を AI が取れる。

3. Design Tokens で「見た目の一貫性」を保てる

AI が個別コンポーネントごとに違う色・サイズを使うのを、Design Tokens で強制的に揃えられる。

⚠️ アトミックデザイン採用時のアンチパターン

1. 階層の形骸化

「Button は Atom だから atoms フォルダに置く」と機械的に振り分けるだけで、実際の import 関係が混乱する（Atom が Molecule を import するような逆流）。

是正: 依存方向を lint で強制 する。eslint-plugin-boundaries や Nx のモジュール境界チェックが有効。

2. ページ専用 Organism の増殖

「CheckoutPageHeader」「ProductListPageFooter」のように、1 ページでしか使わない Organism が量産される。

是正: ページ固有のコンポーネントは Organisms に置かず、 Pages / Templates 層でインライン記述 。本当に再利用されるものだけ Organism に昇格。

3. Atom と Molecule の境界で議論が止まる

「SearchBox は Atom か Molecule か」で半日議論する。生産性を殺す。

是正: 境界は厳密でなくて良い 。後から昇降格できる。とにかく作ってしまい、後でリファクタリング。

4. Design Tokens なしで Atomic だけ導入

色・サイズがハードコードされたまま、コンポーネントだけ分類される。結果、見た目の一貫性が保てない。

是正: Design Tokens を先に整える 。Atomic より先にトークン定義。

5. Storybook なしで進める

ストーリーがないと AI が使い方を学習できず、同じコンポーネントの使い方が画面ごとに揺れる。

是正: 最初の Atom 3 個を作るときから Storybook をセットアップ。以後は 1 コンポーネント 1 ストーリー を規約化。

📚 まとめ

• アトミックデザインは UI コンポーネントを粒度で分類する手法 。Atoms / Molecules / Organisms / Templates / Pages の 5 階層
• 2025 年は Design Tokens + Atomic が主流。トークンを Atom より下に置く
• 現実的には Atoms / Molecules / Organisms の 3 層 + フレームワークの Pages が多い
• 現代の Atom には Tailwind CSS / レスポンシブ / ダークモード がほぼ必須。Atom レベルで揃えると上位が自動追従
• AI への指示で 階層と依存禁止を明示 すると、生成コードの粒度が安定する
• Storybook が AI 駆動開発の「コンポーネントの使い方」参照先になる
• 階層の厳密性より 依存方向の lint 強制 が効く。後から昇降格できる前提で柔軟に運用

🔗 関連記事

• 開発手法ガイド：概要 — シリーズ全体の位置づけ
• 開発手法ガイド：DDD 編 — UI のドメイン語彙を揃える
• 開発手法ガイド：モノレポ編 — UI ライブラリをパッケージ化して配布

📖 関連用語

• Storybook — Atoms/Molecules/Organisms をカタログ化する基盤ツール
• Tailwind CSS — Utility-First で Atom を高速量産する CSS フレームワーク
• アクセシビリティ — Atom レベルで WCAG / 色覚多様性 / キーボード操作に対応
• SOLID 原則 — コンポーネント設計にも適用される原則
• SoC（関心の分離） — アトミックデザインが体現する原則
• DRY — コンポーネント再利用の根拠
• Astro — Pages 層のフレームワーク例

📎 参考資料

• Atomic Design — Brad Frost
• Design Tokens + Atomic Design — Brad Frost
• Atomic Design in 2025: From Rigid Theory to Flexible Practice
• A Comprehensive Guide to Atomic Design and Design Tokens