Figjam Diagram Generator

FigJam Diagram Generator

Non-Negotiables

• NEVER fabricate flow steps not in the source. Every node must trace to the source document.
• NEVER call generate_diagram before completing the Step 4 verification gate.
• NEVER use create_new_file before generate_diagram — it creates its own FigJam file.
• All flows for one feature go into ONE generate_diagram call using subgraphs.
• Read mermaid-patterns.md before generating any Mermaid syntax.

Step 0: Resolve Input Source

Determine where the flow content comes from:

URL parsing for FigJam boards:

• figma.com/board/:fileKey/:fileName?node-id=:nodeId → fileKey is the segment after /board/, nodeId converts - to :

Step 1: Identify Flows to Diagram

1. Scan the source for labeled flows (e.g., **Flow UF-1:**, **Flow UF-2:**, numbered step sequences under flow headings).
2. Present the list to the user via AskQuestion. Ask which to generate (one, some, or all).
3. For each selected flow, extract:
   • Flow name and ID
   • Numbered steps
   • Decision points and branch conditions
   • Actors involved (Officer, System, DM, etc.)
   • Error/alternative paths
   • FR references
   • Notification text and UI copy (verbatim where specified)
   • Audit/compliance data fields mentioned
4. Multi-actor decomposition: If a flow involves actors across different systems (e.g., Officer in MyConnect + DM in WFM), split into separate per-actor subgraphs with explicit handoff points. Title each: [Feature] - [Actor] [action] flow in [System].

Step 2: Select Diagram Type

Auto-detect per flow:

User can override. If ambiguous, ask with AskQuestion.

Step 3: Generate Mermaid Syntax

Read mermaid-patterns.md for shape mapping, edge patterns, and working examples.

Flowchart conventions

Shapes:

• (["..."]) stadium — start/end states (actor actions that begin or end the flow)
• {"..."} diamond — decisions, system checks
• ["..."] rectangle — actions, screens, system behaviors, notifications
• [("...")] cylinder — audit/data storage

Edges:

• -->|"label"| — decision outcomes, user actions (use descriptive labels, not bare Yes/No)
• --> — simple sequential connection
• -.->|"label"| — cross-subgraph handoff (dotted)

Subgraphs:

• One subgraph per flow/actor: subgraph flowId ["Feature - Actor action flow in System"]
• Cross-flow handoffs as dotted edges between subgraphs

Content in nodes:

• Include verbatim UI copy when the source specifies it
• Show affordances: "Click: YES / NO", "Provide Reason: ___"
• Include conditional display logic: "(not shown on subsequent clock-outs)"
• Notification nodes include content summary and follow-up action

Audit nodes:

• When the source mentions compliance data, add a cylinder listing stored fields

Standard Color Palette (flowcharts — always apply)

Every user flow flowchart must include the following classDef block and class assignments. Do NOT skip this for any flowchart. No color styling in gantt/sequence diagrams.

Color legend:

Classification rules:

• terminus — every stadium node (flow start and end)
• decision — every diamond node
• notification — rectangles that compose/send push notifications, display in-app reminders or alerts to the user
• errorPath — rectangles that show offline banners, cached/stale data, fallback states, or paths where the normal flow cannot proceed
• action — all remaining rectangles

Classdefs to append after all subgraphs and cross-subgraph edges:

classDef terminus fill:#D4EDDA,stroke:#28A745,stroke-width:2px,color:#1E4620
classDef decision fill:#FFF3CD,stroke:#F59E0B,stroke-width:2px,color:#664D03
classDef action fill:#CFE2FF,stroke:#0D6EFD,stroke-width:2px,color:#084298
classDef notification fill:#FFE5CC,stroke:#FB923C,stroke-width:2px,color:#7C2D12
classDef errorPath fill:#F8D7DA,stroke:#DC3545,stroke-width:2px,color:#58151C

class <terminus node IDs> terminus
class <decision node IDs> decision
class <action node IDs> action
class <notification node IDs> notification
class <errorPath node IDs> errorPath

MCP hard constraints

• All text in double quotes for flowchart/graph
• No emojis, no \n, no end as ID/className
• Subgraph IDs: camelCase or underscores, no spaces
• No color styling in gantt/sequence; no notes in sequence
• LR direction default for flowcharts

Step 4: Verify and Fix

Mandatory gate. Run all checks in priority order. Fix issues silently. Do NOT call generate_diagram until all checks pass.

Priority 1: Accuracy

The flow must faithfully represent the source.

• Every decision condition matches the source exactly (thresholds, time windows, actor responsibilities). No invented or rounded values.
• No fabricated steps. Every node traces to a step, business rule, or FR in the source.
• Actor attribution is correct. Actions assigned to the right actor (Officer vs System vs DM).
• Decision branch outcomes match the source logic. Not inverted, not simplified away, not merged.
• FR references in node labels are correct. "(FR-5)" corresponds to actual FR-5 content.
• Notification text, UI copy, and conditional logic match the source verbatim where specified.

Fix: Correct mismatched values, swap actors, fix FR references by re-reading the source. Remove fabricated steps.

Priority 2: Clarity

A stakeholder can follow the flow without the requirements doc.

• Every node label is self-explanatory. No vague labels ("System processes request", "Next step").
• Decision diamonds state the specific question ("Shift starts within 60 min?" not "Time check").
• Edge labels explain "why" when a path skips steps or leads to unexpected outcomes.
• Actors named consistently throughout. Same term every time.
• Conditional display notes included where behavior isn't obvious.

Fix: Rewrite vague labels using source context. Standardize actor names across all nodes.

Priority 3: Readability

Visual layout is clean and scannable in FigJam.

• LR direction. Entry node defined first in code (Mermaid places first-defined leftmost).
• No back-links (edges from later to earlier nodes). Remove if detected.
• Node labels are 5-15 words. Not cryptic, not compressed.
• Balanced branching. If one path has 8 nodes and another has 1, check for missing detail.
• Total nodes per subgraph does not exceed 20.
• Consistent label length within a subgraph.

Fix: Remove back-links. Truncate long labels. Split oversized subgraphs. Add nodes to short branches if source warrants it.

Priority 4: Completeness

All paths from the source are represented.

• Every numbered step in the source has a node or edge.
• Alternative and error paths from the source are included, not just the happy path.
• Time-based conditions captured (same-day exceptions, batch windows, pay cycle boundaries).
• Notification content variants included where source specifies them.
• Cross-flow handoffs exist where one flow triggers another.
• Audit/storage nodes present when source mentions compliance data.

Fix: Add missing nodes from the source. Report: "Added nodes for [items] from the requirements."

Priority 5: Conciseness

No redundant or over-detailed nodes.

• No duplicate nodes conveying the same information differently.
• No unnecessary intermediate nodes adding no decision or action ("System receives data" + "System processes data" → combine).
• Labels are tight. Strip filler ("then", "next", "the system will") without losing meaning.
• Subgraphs with 15+ nodes reviewed for merge opportunities.

Fix: Merge duplicates, remove filler nodes, tighten labels. Do not remove nodes carrying distinct meaning.

Priority 6: Structure/Format

Mermaid syntax is valid and shapes match conventions.

• All text in double quotes (flowchart/graph).
• No emojis, no \n, no end as ID/className.
• Diagram type is supported: flowchart, graph, sequenceDiagram, stateDiagram-v2, gantt.
• No color styling in gantt/sequence. No notes in sequence.
• Subgraph IDs use camelCase/underscores.
• Correct shapes: stadium for start/end, diamond for decisions, rectangle for actions, cylinder for audit.
• Subgraph titles follow [Feature] - [Actor] [action] flow in [System].
• Decision edge labels describe outcomes, not bare "Yes/No".
• Standard color palette applied: all 5 classDef blocks present; every node ID assigned to exactly one class; no node left unclassified.

Fix: Add missing quotes, remove emojis, rename reserved IDs, swap wrong shapes, add missing classDef/class assignments. All silent.

After all checks pass → proceed to Step 5.

Step 5: Call Figma MCP

Call CallMcpTool:

• server: user-figma
• toolName: generate_diagram
• arguments:
  • name: Feature name (e.g., "My Schedule User Flows")
  • mermaidSyntax: The verified Mermaid code with subgraphs
  • userIntent: Brief description of what was diagrammed

All flows for one feature go into ONE call using subgraphs. Cross-system actor flows get separate subgraphs with dotted handoff edges.

If generate_diagram returns an error, check the error message against the MCP constraints in mermaid-patterns.md, fix the syntax, and retry once.

Step 6: Report Results

Present to the user:

• Feature name and flows generated
• Number of subgraphs and total node count
• FigJam link (from the MCP response)
• If fixes were applied in Step 4: "Fixed: [list of corrections]"
• Note: generate_diagram creates its own FigJam file. To place on an existing board, copy-paste from the generated file.
• Ask: "Would you like any adjustments to readability, detail level, or missing paths?"