DEV Community

Cover image for From Prompt to Practical: Evolving HandyFEM’s User Flow with Claude.ai + Mermaid.live
Constanza Diaz
Constanza Diaz

Posted on

From Prompt to Practical: Evolving HandyFEM’s User Flow with Claude.ai + Mermaid.live

#ux #tooling #productivity #ai

I’m building HandyFEM, a directory + marketplace connecting women professionals in construction and repairs with clients. In my previous post, I sketched an initial user flow using Figma and ChatGPT. This time I pushed further: I briefed Claude with the full app context and iterated toward a color-coded, developer-ready UI/navigation diagram using Mermaid.

This post documents what I tried, what failed, and what finally worked—so you can reproduce the setup without losing hours to tooling dead ends.

Goal

Create a single source of truth for HandyFEM’s navigation and user journeys—clear enough for stakeholders, and concrete enough for developers to implement screens, forms, and decisions.

Attempt 1: RapidChart (didn’t pan out)

I first tried to auto-generate the diagram via RapidChart prompts. Multiple attempts—including smaller subsets—didn’t render a chart at all. Interesting idea, but in my case it wasn’t reliable enough to ship.

Tooling takeaway: if your diagram generator is brittle, switch to a text-based standard you can version-control.

Pivot: Mermaid for reproducible, versioned diagrams

Claude suggested alternatives, and I decided to give Mermaid a try. It immediately produced a decent first draft—already more complete than my earlier diagram, even if it lacked some visual cues.

First attempt of Mermaid code made by Claude.ai

To enrich it, I pasted my previous flow and asked Claude to integrate both. That gave me structure + detail.

Asking Claude to integrate both charts

The final diagram (color-coded for quick scanning)

Legend:

  • Yellow = Buttons.
  • Light blue = Forms.
  • Teal = Screens.
  • Purple = Decision points.
  • Blue = Professional UI.
  • Green = Client UI.
  • Red = Admin UI.
  • Gray = System processes.

This mapping keeps discussions concrete. Designers and developers can point to the exact element in the flow and agree on behavior.

Note: I iterated a few times in Claude to complete the admin path.

The image below is a small screenshot just for reference.

UI/Navigation flow and User journey flow:

Final UI/Navigation flow diagram (unreadable)

Full size:

Minimal, reproducible snippet (Mermaid)

Here’s a simplified fragment that captures the pattern I used—screens, forms, decisions, and role-scoped branches. You can drop this into any Mermaid-enabled markdown and expand it for your app.

flowchart TD
  %% Legend-inspired classes
  classDef screen fill:#0fb,stroke:#066;       %% Teal
  classDef form fill:#b3e5fc,stroke:#0288d1;   %% Light blue
  classDef decision fill:#b39ddb,stroke:#512da8; %% Purple
  classDef button fill:#ffeb3b,stroke:#f57f17; %% Yellow
  classDef pro fill:#90caf9,stroke:#1565c0;    %% Blue (Professional UI)
  classDef cli fill:#a5d6a7,stroke:#2e7d32;    %% Green (Client UI)
  classDef admin fill:#ef9a9a,stroke:#c62828;  %% Red (Admin UI)
  classDef system fill:#bdbdbd,stroke:#616161; %% Gray (System)

  %% Entry
  A[Landing Screen]:::screen --> B{Choose role}:::decision

  %% Client path
  B -->|Client| C[Client Dashboard]:::screen
  C --> D[Search Professionals Form]:::form
  D --> E[Results Screen]:::screen
  E --> F[Request Quote Button]:::button
  F --> G[Request Form]:::form
  G --> H[System: Notify matched pros]:::system

  %% Professional path
  B -->|Professional| P[Pro Dashboard]:::screen
  P --> Q[Complete Profile Form]:::form
  Q --> R[Verify Identity Button]:::button
  R --> S[System: KYC check]:::system
  S --> T{Approved?}:::decision
  T -->|Yes| U[Receive job requests]:::screen
  T -->|No| V[Manual review]:::admin

  %% Admin path
  B -->|Admin| A1[Admin Panel]:::admin
  A1 --> A2[Moderate Listings]:::admin
  A1 --> A3[Resolve Disputes]:::admin
Enter fullscreen mode Exit fullscreen mode

simplified chart

Why this helps:

  • Text-as-diagram means you can version the flow in Git, review it in pull requests, and co-edit with your team.
  • Color classes encode semantics you can reuse across large diagrams.
  • Branching by role makes gaps obvious and audit-able.

Practical notes

  • Prompt shape matters. My best results came from supplying Claude with the app glossary, roles, and UI primitives (screen, form, decision, button, system).
  • Iterate role by role. I filled Client and Professional paths first, then Admin.
  • Keep it modular. Break huge flows into linked sub-diagrams per feature if your tool or host chokes on size.
  • Treat it like code. Store the .md or .mmd in your repo and make changes via PRs.

What I’ll do next

  • Split the mega-diagram into feature-level Mermaid files.
  • Connect each node to issue links or Figma frames for implementation hand-off.
  • Add acceptance criteria to decisions and forms to reduce ambiguity during dev.

If you’re mapping a complex app, pairing a capable LLM with Mermaid gives you speed, structure, and a durable artifact your team can actually build from.

Top comments (0)