Designing Jetpack Compose UI Flow with Mermaid and AI

Introduction

When you're designing a Jetpack Compose app with AI, how do you communicate the UI flow?

• Paste screenshots into the AI
• Draw diagrams in FigJam or Miro
• Describe it verbally

Each of these is either missing information or in a format that's hard for AI to work with.

Mermaid (a text-based flow notation) lets you manage UI flow as code while keeping it in a format you can pass directly to AI.

Tool Comparison: What Communicates Best to AI

Why Mermaid works so well:

• It's text, so you can paste it directly into a prompt
• Diffs can be tracked in Git
• Maps naturally to Compose Navigation structure
• AI can generate and modify it easily

Mermaid Basics

The essence of Mermaid UI flow is screens (Screen) = nodes, transitions = arrows.

Minimal Example

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

Conditional Transitions

flowchart TD
    Home --> Detail
    Detail -->|habitId required| Edit
    Edit -->|logged in only| Confirm
    Confirm --> Home

Including State (Important)

UI flow UX changes based on state. Making state explicit surfaces design problems early.

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

    Home --> Detail
    Detail --> Edit
    Edit -->|save| Home
    Edit -->|cancel| Detail

Mapping to Compose Navigation

Aligning your Mermaid diagram with Jetpack Compose Navigation makes your design explicit.

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

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

// Reflect the Mermaid structure directly in Navigation
NavHost(navController, startDestination = "home") {
    composable("home") { HomeScreen(navController) }
    composable("detail/{habitId}") { DetailScreen(navController) }
    composable("edit/{habitId}") { EditScreen(navController) }
}

Representing Tabs and BottomNav

Mermaid isn't naturally suited for tabs — because tabs are UI state, not screen transitions.

That said, there are workable approaches.

Option 1: Branching Nodes (Simplest)

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

Option 2: subgraph (Visually Clear)

flowchart TD
    subgraph BottomNav
        Home
        Search
        Profile
    end

    Home --> Detail
    Detail --> Edit

Option 3: Represent as State (Most Accurate for Compose)

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

Tabs Are State, Not Transitions

Forcing everything into transitions makes your Mermaid diagram fall apart.

The right layer separation:

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

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

This is a realistic model for Jetpack Compose Navigation with BottomNav.

A Practical Format for AI

Passing this format to Claude Code lets you communicate UI flow, state, and constraints all at once:

UI Flow (Mermaid):
flowchart TD
    Home --> Detail
    Detail -->|habitId required| Edit
    Edit -->|save| Home

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

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

With this format, Claude Code can:

• Review your Navigation design
• Suggest a ViewModel structure
• Flag UX flow problems

Common Mistakes

Too Abstract to Be Useful

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

Without screen names, nothing is communicated.

Mixing UI and State

Blending screen transitions with state changes makes the design hard to read. Keep Mermaid focused on transitions only.

Trying to Express Tabs as Transitions

Tabs are state switches, not screen transitions. Writing them as transitions distorts the structure. Keep them in subgraphs or state representations.

Summary

Mermaid + Claude Code makes it possible to design UI flow by "thinking alongside AI as you write." Iteration is far faster than with Figma or screenshots.