Jetpack ComposeのUIフローをMermaidとAIで設計する

はじめに

Jetpack Composeアプリの設計をAIと一緒にやるとき、どうやってUIフローを伝えますか？

• スクリーンショットをAIに貼る
• FigJamやMiroで図を描く
• 口頭で説明する

どれも情報が欠けるか、AIが扱いにくい形式です。

Mermaid（テキストフロー記法） を使うと、UIフローをコードとして管理しながら、AIに直接渡せる形式で持てます。

ツール比較：何がAIに一番伝わるか

Mermaidが強い理由:

• テキストなのでそのままプロンプトに貼れる
• Gitで差分管理できる
• Compose Navigationの構造と対応しやすい
• AIが生成・修正しやすい

Mermaidの基本書き方

Mermaid UIフローの本質は「画面（Screen）＝ノード、遷移＝矢印」です。

最小構成

flowchart TD
    Home --> Detail
    Detail --> Edit

条件付き遷移

flowchart TD
    Home --> Detail
    Detail -->|habitId必須| Edit
    Edit -->|ログイン済みのみ| Confirm
    Confirm --> Home

状態を入れる（重要）

UIフローは「状態」でUXが変わります。状態を明示すると設計の破綻が見えやすくなります。

flowchart TD
    Home["Home\n[state: listLoaded]"]
    Detail["Detail\n[state: habitSelected]"]
    Edit["Edit\n[state: formDirty]"]

    Home --> Detail
    Detail --> Edit
    Edit -->|保存| Home
    Edit -->|キャンセル| Detail

Compose Navigationとの対応

Mermaidの書き方をJetpack Compose Navigationに対応させると設計が明確になります。

flowchart TD
    NavGraph["NavGraph"]
    NavGraph --> Home
    NavGraph --> Detail
    NavGraph --> Edit

    Home -->|"navigate(Detail)"| Detail
    Detail -->|"navigate(Edit)"| Edit
    Edit -->|"popBackStack()"| Detail

// Mermaidの構造をそのままNavigationに反映
NavHost(navController, startDestination = "home") {
    composable("home") { HomeScreen(navController) }
    composable("detail/{habitId}") { DetailScreen(navController) }
    composable("edit/{habitId}") { EditScreen(navController) }
}

タブ・BottomNavの表現

Mermaidはタブの表現が得意ではありません。タブは「画面遷移」ではなく「UI状態」だからです。

しかし表現方法はあります。

方法1: 分岐ノードで表現（最もシンプル）

flowchart TD
    App --> Home
    App --> Search
    App --> Profile
    Home --> Detail

方法2: subgraphで囲う（視覚的にわかりやすい）

flowchart TD
    subgraph BottomNav
        Home
        Search
        Profile
    end

    Home --> Detail
    Detail --> Edit

方法3: 状態として表現（Compose的に正確）

flowchart TD
    MainScreen["MainScreen\n[selectedTab: Home|Search|Profile]"]
    MainScreen -->|tab=Home| HomeContent
    MainScreen -->|tab=Search| SearchContent
    MainScreen -->|tab=Profile| ProfileContent
    HomeContent --> Detail

「タブは状態」という考え方

Mermaidで無理やり全部を表現しようとすると破綻します。

正しいレイヤー分離:

flowchart TD
    subgraph "Main (BottomNav)"
        Home
        Search
        Profile
    end

    Home -->|"navigate(Detail)"| Detail
    Detail -->|"navigate(Edit)"| Edit
    Edit -->|"popBackStack"| Detail

これがJetpack Compose NavigationのBottomNavを含む現実的なモデルです。

AIに渡す実用フォーマット

以下のフォーマットでClaude Codeに渡すと、UIフロー・状態・制約をまとめて伝えられます。

UI Flow (Mermaid):
flowchart TD
    Home --> Detail
    Detail -->|habitId必須| Edit
    Edit -->|保存| Home

State:
- Home: listLoaded
- Detail: habitSelected
- Edit: formDirty

Constraint:
- Compose Material3
- state hoisting
- BottomNav: Home/Search/Profile

このフォーマットをClaude Codeに貼ると：

• Navigation設計のレビューができる
• ViewModel設計の提案が得られる
• UXフローの問題点を指摘してもらえる

よくあるミス

❌ 抽象すぎてわからない

flowchart TD
    A --> B
    B --> C

画面名が入っていないと何も伝わりません。

❌ UIと状態が分離されていない

画面遷移と状態変化を混在させると設計が見えにくくなります。Mermaidは「画面遷移」だけに絞るのが読みやすいです。

❌ タブを全部遷移で書こうとする

タブは状態切り替えなので、画面遷移として書くと構造が歪みます。subgraphやstate表現に留めます。

まとめ

Mermaid + Claude Codeの組み合わせは、UIフロー設計を「AIと一緒に考えながら書く」ことを可能にします。figmaやスクショよりもずっと高速にイテレーションできます。