This content originally appeared on DEV Community and was authored by Constanza Diaz
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.
To enrich it, I pasted my previous flow and asked Claude to integrate both. That gave me structure + detail.
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:
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
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
.mdor.mmdin 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.
This content originally appeared on DEV Community and was authored by Constanza Diaz
Constanza Diaz | Sciencx (2025-10-14T21:43:23+00:00) From Prompt to Practical: Evolving HandyFEM’s User Flow with Claude.ai + Mermaid.live. Retrieved from https://www.scien.cx/2025/10/14/from-prompt-to-practical-evolving-handyfems-user-flow-with-claude-ai-mermaid-live/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.