フェーズ 3: UI - インターフェース設計とプロトタイピング

UI は Agent App Factory パイプラインの第 3 フェーズで、PRD 内の機能記述を明確なインターフェース構造（UI Schema）とプレビュー可能なプロトタイプに変換することを担当します。このフェーズは、最終アプリケーションの外観とインタラクション体験を決定し、製品要件と技術実装をつなぐ重要な架け橋となります。

学習後にできること

PRD を標準準拠の ui.schema.yaml ファイルに変換する
ui-ux-pro-max スキルを使用してプロフェッショナルなデザインシステム（スタイル、カラーパレット、フォント）を生成する
ブラウザでプレビューできるプロトタイプ（HTML + CSS + JS）を作成する
UI Agent の責任範囲を理解する（視覚デザイン、技術実装には関与しない）
一般的な AI デザイントラップを回避する（例：紫グラデーションの乱用、Inter フォント）

現在の課題

明確な PRD を持っていても、どこからインターフェース設計を始めればいいかわからないかもしれません：

「PRD は書いたけど、どんな UI スタイルが適しているか思いつかない」（デザインシステム知識の欠如）
「どの色、フォント、レイアウトを使えばいいかわからない」（プロフェッショナルな規範ではなく個人の美的感覚に依存）
「デザインしたプロトタイプが PRD と一致しない」（インターフェース構造と機能要件の乖離）
「デザインが醜かったり派手すぎて、製品のポジショニングに合わないのではないかと心配」（業界のデザイン経験の欠如）

このようなデザインの盲点により、後続の Code フェーズで明確な視覚的規範が欠如し、最終的に生成されるアプリケーションが外観が混乱し、インタラクションに一貫性がなくなる可能性があります。

この手法を使うタイミング

PRD が完成し、以下の条件を満たしている場合：

明確な PRD ドキュメントがある（ユーザーストーリー、機能リスト、非目標を含む）
まだインターフェース設計を開始していない（UI は最初のデザインフェーズ）
まだ技術スタックを決定していない（技術実装の詳細は Tech フェーズで行う）
デザイン範囲を制御し、過度な設計を避けたい（UI フェーズは 3 ページ以内に制限）

🎒 開始前の準備

前提条件

UI フェーズを開始する前に、以下を確認してください：

✅ PRD フェーズが完了し、artifacts/prd/prd.md が生成されている
✅ ui-ux-pro-max プラグインがインストールされている（推奨方法：factory init を実行すると自動インストールされる）
✅ 7 フェーズパイプライン概要を理解している
✅ AI アシスタントが準備されている（Claude Code の使用を推奨）

核心アプローチ

UI フェーズとは何か？

UI フェーズは製品要件と技術実装をつなぐ架け橋であり、その唯一の責務はPRD 内の機能記述をインターフェース構造と視覚的規範に変換することです。

フロントエンド開発ではない

UI Agent はフロントエンドエンジニアではなく、React コンポーネントや CSS コードは書きません。そのタスクは：

PRD 内の機能要件を分析する
インターフェース情報アーキテクチャ（ページとコンポーネント）を決定する
デザインシステム（色、フォント、間隔、角丸）を生成する
プレビュー可能なプロトタイプ（HTML + CSS + JS）を作成する

「どのフレームワークを使うか」は決定せず、「どのように見えるか」だけを決定します。

なぜデザインシステムが必要か？

デザインシステムのない家のリフォームを想像してみてください：

❌ デザインシステムなし：リビングはミニマリストスタイル、寝室はレトロスタイル、キッチンはインダストリアルスタイルで、全体的に混乱
✅ デザインシステムあり：全室でトーン、スタイル、素材を統一し、調和した外観

UI フェーズは、ui-ux-pro-max スキルを通じてこの「全屋リフォームガイド」を生成し、後続の Code フェーズで生成される全インターフェースが統一された視覚的規範に従うことを保証します。

出力ファイル構造

UI フェーズは 3 つのファイルを生成します：

ファイル	内容	役割
ui.schema.yaml	デザインシステム設定 + ページ構造定義	Tech フェーズでこのファイルを読み取りデータモデルを設計し、Code フェーズでこのファイルを読み取りインターフェースを生成
preview.web/index.html	ブラウザでプレビューできるプロトタイプ	インターフェースの外観を事前に確認し、設計が期待通りか検証するために使用
design-system.md（オプション）	永続化されたデザインシステムドキュメント	設計決定を記録し、後続の調整を容易にするために使用

ステップバイステップガイド

ステップ 1: PRD が完了していることを確認する

UI フェーズを開始する前に、artifacts/prd/prd.md が存在し、内容が完全であることを確認してください。

チェックポイント ✅：

ターゲットユーザーは明確ですか？
- ✅ 具体的なペルソナあり（年齢/職業/技術力）
- ❌ 曖昧：「全員」
コア機能はリストされていますか？
- ✅ 3-7 個の重要機能
- ❌ 多すぎるまたは少なすぎる
非目標は十分ですか？
- ✅ 少なくとも 3 つ行わない機能をリスト
- ❌ 欠如または少なすぎる

PRD が不完全な場合

PRD フェーズに戻って修正し、設計に明確な入力があることを確認してください。

ステップ 2: パイプラインを UI フェーズまで進める

Factory プロジェクトディレクトリで以下を実行してください：

bash

# PRD フェーズから続ける（PRD フェーズが完了したばかりの場合）
factory continue

# または ui から直接開始
factory run ui

CLI は現在の状態と利用可能なフェーズを表示します。

ステップ 3: AI アシスタントが UI Agent 定義を読み込む

AI アシスタント（Claude Code など）は自動的に agents/ui.agent.md を読み込み、その責任範囲と制約を理解します。

Agent の責任

UI Agent は以下のことのみ可能です：

artifacts/prd/prd.md を読み取る
artifacts/ui/ に書き込む
デザインシステムを生成するために ui-ux-pro-max スキルを使用する
3 ページを超えないプロトタイプを作成する

以下はできません：

他のファイルを読み取る
他のディレクトリに書き込む
技術スタックを決定する（これらは Tech フェーズで行う）
AI デフォルトスタイルを使用する（紫グラデーション、Inter フォント）

ステップ 4: ui-ux-pro-max デザインシステムを強制的に使用する（重要ステップ）

これは UI フェーズのコアステップです。AI アシスタントは必ずまず ui-ux-pro-max スキルを呼び出す必要があり、設計方向が明確であってもです。

ui-ux-pro-max スキルの役割：

自動デザインシステム推奨：製品タイプ、業界分野に基づいて最適なスタイルを自動的にマッチング
67 種類の UI スタイルを提供：ミニマリズムからネオブルータリズムまで
96 種類のカラーパレットを提供：業界とスタイル別にプリセット
57 種類のフォント組み合わせを提供：一般的な AI スタイル（Inter、Roboto）を回避
100 業界推論ルールを適用：製品ポジショニングに合わせた設計を保証

AI アシスタントが行うこと：

PRD から重要情報を抽出：製品タイプ、業界分野、ターゲットユーザー
完全なデザインシステム推奨を取得するために ui-ux-pro-max スキルを呼び出す
推奨されたデザインシステムを ui.schema.yaml とプロトタイプに適用する

このステップをスキップすると拒否されます

Sisyphus スケジューラは ui-ux-pro-max スキルが使用されたか検証します。使用されていない場合、UI Agent の出力は拒否され、再実行が必要になります。

デザインシステムには何が含まれますか？

yaml

design_system:
  style: "Glassmorphism"           # 選択したスタイル（例：ガラスモーフィズム、ミニマリズム）
  colors:
    primary: "#2563eb"             # プライマリカラー（主要アクションに使用）
    secondary: "#64748b"           # セカンダリカラー
    success: "#10b981"             # サクセスカラー
    warning: "#f59e0b"             # 警告カラー
    error: "#ef4444"               # エラーカラー
    background: "#ffffff"          # 背景カラー
    surface: "#f8fafc"            # サーフェスカラー
    text:
      primary: "#1e293b"           # プライマリテキスト
      secondary: "#64748b"         # セカンダリテキスト
  typography:
    font_family:
      headings: "DM Sans"          # 見出しフォント（Inter を回避）
      body: "DM Sans"              # 本文フォント
    font_size:
      base: 16
      lg: 18
      xl: 20
      2xl: 24
  spacing:
    unit: 8                        # スペーシングベース（8px グリッド）
  border_radius:
    md: 8
    lg: 12
  effects:
    hover_transition: "200ms"      # ホバー遷移時間
    blur: "backdrop-blur-md"       # ガラス効果

ステップ 5: インターフェース構造を設計する

AI アシスタントは PRD 内の機能要件に基づいて、インターフェース情報アーキテクチャ（ページとコンポーネント）を設計します。

インターフェース構造の例（ui.schema.yaml より）：

yaml

pages:
  - id: home
    title: "ホーム"
    type: list
    description: "すべてのプロジェクトリストを表示"
    components:
      - type: header
        content: "マイアプリ"
      - type: list
        source: "api/items"
        item_layout:
          - type: text
            field: "title"
            style: "heading"
          - type: text
            field: "description"
            style: "body"
        actions:
          - type: "navigate"
            target: "detail"
            params: ["id"]

  - id: detail
    title: "詳細"
    type: detail
    params:
      - name: "id"
        type: "number"

  - id: create
    title: "作成"
    type: form
    fields:
      - name: "title"
        type: "text"
        label: "タイトル"
        required: true
    submit:
      action: "post"
      endpoint: "/api/items"
      on_success: "navigate:home"

ページタイプ：

list：リストページ（例：ホーム、検索結果）
detail：詳細ページ（例：プロジェクト詳細の表示）
form：フォームページ（例：作成、編集）

ステップ 6: プレビュープロトタイプを作成する

AI アシスタントは HTML + CSS + JS を使用してプレビュー可能なプロトタイプを作成し、主要なインタラクションフローを示します。

プロトタイプの特徴：

ネイティブテクノロジーを使用（フレームワークに依存しない）
デザインシステム推奨の配色、フォント、効果を適用
すべてのクリック可能要素にホバー状態と cursor-pointer がある
モバイルファースト設計（375px と 768px でレスポンシブに正しく動作）
SVG アイコンを使用（Heroicons/Lucide）、emoji は使用しない

プレビュー方法：ブラウザで artifacts/ui/preview.web/index.html を開くと、プロトタイプを確認できます。

ステップ 7: UI 出力を確認する

UI Agent が完了したら、出力ファイルを確認する必要があります。

チェックポイント ✅：

ui.schema.yaml は存在しますか？
- ✅ ファイルが artifacts/ui/ ディレクトリに存在する
- ❌ 欠落またはパスが間違っている
デザインシステムは ui-ux-pro-max スキルを使用していますか？
- ✅ 出力または schema で明確に説明されている
- ❌ 独自に選択したデザインシステム
ページ数は 3 ページを超えていませんか？
- ✅ 1-3 ページ（MVP はコア機能に集中）
- ❌ 3 ページを超える
プロトタイプはブラウザで開けますか？
- ✅ ブラウザで preview.web/index.html を開くと正常に表示される
- ❌ 開けない、またはエラーが表示される
AI デフォルトスタイルは避けられていますか？
- ✅ 紫/ピンクのグラデーションがない
- ✅ Inter フォントを使用していない
- ✅ SVG アイコンを使用（emoji は使用しない）
- ❌ 上記の AI スタイルが出現する
すべてのクリック可能要素にインタラクションフィードバックがありますか？
- ✅ cursor-pointer とホバー状態がある
- ✅ トランジションがスムーズ（150-300ms）
- ❌ インタラクション表示がない、または即座に変化する

ステップ 8: 続行、再試行、または一時停止を選択する

確認後、CLI はオプションを表示します：

bash

操作を選択してください：
[1] 続行（Tech フェーズへ）
[2] 再試行（UI を再生成）
[3] 一時停止（後で続行）

プロトタイプを先にプレビューすることを推奨

AI アシスタントで確認する前に、ブラウザでプロトタイプを開き、設計が期待通りか検証してください。Tech フェーズに入ると、設計を変更するコストが高くなります。

よくある落とし穴

落とし穴 1: ui-ux-pro-max スキルを使用しない

誤った例：

AI アシスタントが独自にガラスモーフィズムスタイル、青色の配色を選択

結果：Sisyphus スケジューラが出力を拒否し、再実行を要求します。

推奨：

AI アシスタントは必ず ui-ux-pro-max スキルを呼び出し、推奨デザインシステムを取得する必要がある

落とし穴 2: AI デフォルトスタイルを使用する

誤った例：

紫/ピンクのグラデーション背景
Inter または Roboto フォント
UI アイコンとしての emoji

結果：デザインがプロフェッショナルでなく、AI 生成として識別されやすく、製品イメージに影響します。

推奨：

ui-ux-pro-max 推奨の 57 種類のフォント組み合わせから選択
SVG アイコンライブラリを使用（Heroicons/Lucide）
グラデーションとネオンカラーの乱用を避ける

落とし穴 3: ページ数が 3 ページを超える

誤った例：

5 ページを生成：ホーム、詳細、作成、編集、設定

結果：MVP スコープが制御不能になり、Tech フェーズと Code フェーズの作業量が大幅に増加します。

推奨：1-3 ページに制御し、コアユーザーフローに集中する。

落とし穴 4: プロトタイプにインタラクションフィードバックが欠けている

誤った例：

ボタンにホバー状態がなく、リンクに cursor-pointer がない

結果：ユーザーエクスペリエンスが悪く、プロトタイプがリアルではありません。

推奨：すべてのクリック可能要素に cursor-pointer とホバー状態（150-300ms トランジション）を追加する。

落とし穴 5: ライトモードのコントラストが不十分

誤った例：

ガラスカードの背景色 bg-white/10（透明すぎる）、テキストカラー #94A3B8（薄すぎる）

結果：ライトモードでコンテンツが見えず、アクセシビリティ基準を満たしていません。

推奨：

ガラスカードはライトモードで bg-white/80 以上を使用
テキストコントラスト比 >= 4.5:1（WCAG AA 基準）

落とし穴 6: プロトタイプと schema の不一致

誤った例：

schema では 2 ページを定義しているが、プロトタイプでは 3 ページを表示している

結果：Tech フェーズと Code フェーズで混乱が生じ、どちらを基準とすべきかわからなくなります。

推奨：プロトタイプと schema が完全に一致することを確認し、ページ数とコンポーネント構造が対応している必要がある。

レッスンサマリー

UI フェーズの核心はデザインシステムです：

入力：明確な PRD ドキュメント（artifacts/prd/prd.md）
プロセス：AI アシスタントが ui-ux-pro-max スキルを通じてプロフェッショナルなデザインシステムを生成
出力：ui.schema.yaml（デザインシステム + インターフェース構造）+ preview.web/index.html（プレビュー可能なプロトタイプ）
検証：デザインシステムがプロフェッショナルか、プロトタイプがプレビュー可能か、AI デフォルトスタイルを避けているかをチェック

重要な原則

❌ やらないこと：技術スタックを決定しない、フロントエンドコードを書かない、AI デフォルトスタイルを使用しない
✅ やることだけ：デザインシステムを生成する、インターフェース構造を設計する、プレビュー可能なプロトタイプを作成する

次のレッスン予告

次のレッスンでは フェーズ 4: Tech - 技術アーキテクチャの設計 を学びます。
学ぶ内容：
PRD と UI Schema に基づいて技術アーキテクチャを設計する方法
適切な技術スタックを選択する方法（Express + Prisma + React Native）
最小限で実現可能なデータモデルを設計する方法（Prisma Schema）
なぜ Tech フェーズは UI 実装の詳細に関与すべきではないのか

付録：ソースコードリファレンス

クリックしてソースコードの場所を表示

更新日：2026-01-29

機能	ファイルパス	行番号
UI Agent 定義	`agents/ui.agent.md`	1-98
UI Skill	`skills/ui/skill.md`	1-430
パイプライン定義（UI フェーズ）	`pipeline.yaml`	34-47
スケジューラ定義	`agents/orchestrator.checkpoint.md`	1-100+

重要な制約：

ui-ux-pro-max スキルの強制使用：ui.agent.md:33, 53-54
AI スタイル配色の禁止：ui.agent.md:36
emoji アイコンの禁止：ui.agent.md:37
cursor-pointer とホバー状態の必須追加：ui.agent.md:38
プロトタイプページは 3 ページを超えない：ui.agent.md:34
ネイティブ HTML/CSS/JS の使用：ui.agent.md:35

終了条件（pipeline.yaml:43-47）：

ui.schema.yaml が存在する
ページ数が 3 を超えない
プレビューページがブラウザで開ける
Agent が ui-ux-pro-max スキルを使用してデザインシステムを生成した

UI Skill コンテンツフレームワーク：

思考フレームワーク：目的、トーン、差別化、情報アーキテクチャ
デザインシステム生成ワークフロー：要件分析 → デザインシステム生成 → 補足検索 → 技術スタックガイドの取得
67 種類の UI スタイル：ミニマリズム、ニューモーフィズム、ガラスモーフィズム、ブルータリズムなど
業界推論ルール：100 ルール、製品タイプ別に自動的にデザインシステムを推奨
デザインシステムガイド：カラーシステム、タイポグラフィシステム、スペーシングシステム、コンポーネント仕様
デリバリー前チェックリスト：視覚品質、インタラクション、ライト/ダークモード、レイアウト、アクセシビリティ
決定原則：目的主導、モバイルファースト、アクセシビリティ、簡潔で限定的、プレビュー一致、ツール優先
やらないこと (NEVER)：AI スタイルフォント/配色、emoji アイコン、低コントラスト、3 ページを超えるなど

フェーズ 3: UI - インターフェース設計とプロトタイピング ​

学習後にできること ​

現在の課題 ​

この手法を使うタイミング ​

🎒 開始前の準備 ​

核心アプローチ ​

UI フェーズとは何か？ ​

なぜデザインシステムが必要か？ ​

出力ファイル構造 ​

ステップバイステップガイド ​

ステップ 1: PRD が完了していることを確認する ​

ステップ 2: パイプラインを UI フェーズまで進める ​

ステップ 3: AI アシスタントが UI Agent 定義を読み込む ​

ステップ 4: ui-ux-pro-max デザインシステムを強制的に使用する（重要ステップ） ​

ステップ 5: インターフェース構造を設計する ​

ステップ 6: プレビュープロトタイプを作成する ​

ステップ 7: UI 出力を確認する ​

ステップ 8: 続行、再試行、または一時停止を選択する ​

よくある落とし穴 ​

落とし穴 1: ui-ux-pro-max スキルを使用しない ​

落とし穴 2: AI デフォルトスタイルを使用する ​

落とし穴 3: ページ数が 3 ページを超える ​

落とし穴 4: プロトタイプにインタラクションフィードバックが欠けている ​

落とし穴 5: ライトモードのコントラストが不十分 ​

落とし穴 6: プロトタイプと schema の不一致 ​

レッスンサマリー ​

次のレッスン予告 ​

付録：ソースコードリファレンス ​

フェーズ 3: UI - インターフェース設計とプロトタイピング

学習後にできること

現在の課題

この手法を使うタイミング

🎒 開始前の準備

核心アプローチ

UI フェーズとは何か？

なぜデザインシステムが必要か？

出力ファイル構造

ステップバイステップガイド

ステップ 1: PRD が完了していることを確認する

ステップ 2: パイプラインを UI フェーズまで進める

ステップ 3: AI アシスタントが UI Agent 定義を読み込む

ステップ 4: ui-ux-pro-max デザインシステムを強制的に使用する（重要ステップ）

ステップ 5: インターフェース構造を設計する

ステップ 6: プレビュープロトタイプを作成する

ステップ 7: UI 出力を確認する

ステップ 8: 続行、再試行、または一時停止を選択する

よくある落とし穴

落とし穴 1: ui-ux-pro-max スキルを使用しない

落とし穴 2: AI デフォルトスタイルを使用する

落とし穴 3: ページ数が 3 ページを超える

落とし穴 4: プロトタイプにインタラクションフィードバックが欠けている

落とし穴 5: ライトモードのコントラストが不十分

落とし穴 6: プロトタイプと schema の不一致

レッスンサマリー

次のレッスン予告

付録：ソースコードリファレンス