Figjam Diagram Generator

---
name: figjam-diagram-generator
description: >-
  Generates Mermaid.js diagrams in FigJam from requirements documents, user
  flows, state descriptions, or verbal input. Supports flowcharts, sequence
  diagrams, state diagrams, and gantt charts via the Figma MCP generate_diagram
  tool. Applies client-reviewed flow modeling conventions (shape vocabulary,
  actor naming, audit nodes, cross-system handoffs). Runs a 6-priority
  verification gate (accuracy, clarity, readability, completeness, conciseness,
  structure) before generating. Use when asked to: create a FigJam diagram,
  generate a user flow in FigJam, create a flowchart from requirements, build a
  sequence diagram, generate a state diagram, visualize a user flow, or any
  request involving Mermaid diagrams in FigJam.
---

# 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](mermaid-patterns.md) before generating any Mermaid syntax.

---

## Step 0: Resolve Input Source

Determine where the flow content comes from:

| Case | Input | Action |
|------|-------|--------|
| A | Requirements document path | Read the file. Proceed to Step 1. |
| B | Verbal description | Capture it. Proceed to Step 1. |
| C | FigJam board URL | Use `get_figjam` MCP tool (server: `user-figma`, fileKey from URL, nodeId `0:1`) to read existing content for context. Optional — only if user wants to reference what's already on a board. |
| D | No input provided | Ask: *"Which requirements doc or flow should I diagram?"* Stop until answered. |

**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:

| Signal in source | Diagram Type |
|-----------------|--------------|
| Sequential user actions with decision branches | `flowchart LR` |
| System-to-system interactions, request/response | `sequenceDiagram` |
| Entity with named states and transitions | `stateDiagram-v2` |
| Timeline with dates and durations | `gantt` |

User can override. If ambiguous, ask with AskQuestion.

---

## Step 3: Generate Mermaid Syntax

Read [mermaid-patterns.md](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:**

| Class | Fill | Stroke | Text | Shape | Meaning |
|---|---|---|---|---|---|
| `terminus` | `#D4EDDA` | `#28A745` | `#1E4620` | Stadium `(["..."])` | Start / End of a flow |
| `decision` | `#FFF3CD` | `#F59E0B` | `#664D03` | Diamond `{"..."}` | Decision / system check |
| `action` | `#CFE2FF` | `#0D6EFD` | `#084298` | Rectangle `["..."]` | Action / screen / processing |
| `notification` | `#FFE5CC` | `#FB923C` | `#7C2D12` | Rectangle `["..."]` | User-facing notification or in-app reminder |
| `errorPath` | `#F8D7DA` | `#DC3545` | `#58151C` | Rectangle `["..."]` | Error / fallback / degraded path |

**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](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?"