This document establishes a company-wide standard for creating user flow diagrams. User flows are essential artifacts that help us visualize the complete path a user takes to accomplish a task.

❓ Why do we need a standard?

Clarity & Consistency: A single, shared language for diagrams eliminates ambiguity and ensures everyone—from designers to engineers to product managers—can understand the user's journey at a glance.
Efficiency: Standardized tools and templates accelerate the creation process and make collaboration seamless.
Quality: By focusing on user-centric actions and feedback, we ensure our diagrams accurately reflect the user experience, leading to better product decisions.

🧑‍💻 Mermaid

Mermaid is a text-based tool for generating diagrams and charts. We use it as the "source of truth" for our user flows because it is:

Easy to Edit: You can quickly modify a flow by changing a few lines of text, without needing to manually realign shapes.
Integration-Friendly: It can be embedded directly into documentation platforms like Confluence, Notion, or internal wikis.

Standard Shapes and Meanings

The following table defines the official shapes and their corresponding intents for all user flow diagrams. Sticking to these conventions is crucial for maintaining clarity and consistency.

Mermaid	Intent Type	Description	Shape
[/…/]	UI Trigger	UI action initiated by user (click, submit, etc.)	Parallelogram
[\…\]	UI Prompt	Request for user input or confirmation	Parallelogram alt
[…]	System Output	UI feedback shown to user	Rectangle
[[…]]	Processing	System logic or computational task	Double rectangle
{…}	Decision	Condition or branching logic (yes/no or success/fail)	Diamond
(((…)))	Error	Error state or user-facing error message	Double circle (octagon in Figma)

flowchart TD
	A[/UI Trigger/]
	B[\\UI Prompt\\]
	C[System output]
	D[[Processing]]
	E{Decision}
	F(((Error)))

👨‍🎨 FigJam

FigJam is our collaborative whiteboarding tool. While Mermaid is our source of truth, FigJam is our space for ideation, collaboration, and presentation.

The official FigJam template contains pre-built components for all our standard shapes, making it easy to build and discuss flows visually with the team. Use FigJam when:

Brainstorming initial flow ideas.
Collaborating in real-time with PLs, engineers, and other stakeholders.