diagram-export

Files (3)

• SKILL.md
• erd-grouped.json · examples/
• export-diagram.sh · scripts/

SKILL.md (first lines)

# Diagram Export

## Prerequisites

| Tool | Check | Install |
|------|-------|---------|
| Node.js >= 18 | `node --version` | [https://nodejs.org](https://nodejs.org) |
| npx | `npx --version` | Included with Node.js |
| mermaid-to-drawio (optional) | `command -v mermaid-to-drawio` | `npm install -g mermaid-to-drawio` |
| Lucid MCP (for lucid target) | Configured via Setup Agents UI OAuth flow | See Lucidchart section below |

> mermaid-cli is auto-downloaded via `npx -y @mermaid-js/mermaid-cli`. No manual install needed.

---

## First-party rendering (prefer this in an IDE conversation)

When the diagram model exists as `AgentDiagramData` JSON, render it with the built-in
command instead of hand-rolling `mermaid-cli` — it applies the ER/architecture layout and
connector routing and emits a standalone SVG/PDF the IDE can open directly:

```bash
# Build the model from real sources first (force-app metadata, an existing .drawio/.mmd/.md)
sf setup-agents diagram import -i force-app --from force-app --out model.json
# Render to a standalone SVG (or pdf) — no browser, no external service
sf setup-agents diagram render -i model.json -f svg -o diagram.svg
```

- Runs headless (no bridge, no web-console) — it is a plain CLI command the agent invokes
  during the conversation; the IDE (VS Code / Cursor) previews the resulting SVG/PDF natively.
- `-f`/`--format` accepts `mermaid | drawio | maxgraph-json | svg | pdf`.
- Use `mermaid-cli` (below) only for ad-hoc `.mmd` linting/preview when there is no
  `AgentDiagramData` model.

---

## CRITICAL: Mermaid Syntax Validation

**Always validate Mermaid syntax before exporting or embedding in any document.**
The validator is the rendering engine itself — run it explicitly:

```bash
# Lint a .mmd file — exit 0 = valid, exit non-zero = syntax error
npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o /tmp/lint-check.svg
echo "Exit code: $?"
```

**Guardrails (MANDATORY):**

1. **Before exporting:** always run the validator above. Never skip.
2. **After AI generation:** treat every generated diagram as untrusted until validated.
3. **When embedding in Markdown:** validate the fenced block contents, not just the text.
4. **On parse error:** read the error message carefully — it includes the exact line and
   character. Fix that specific location, then re-validate. Do NOT guess-fix blindly.
5. **Never suppress errors** with fallback to a simpler diagram without telling the user.

---

## Diagram Fidelity Classification (CRITICAL)

Classify every diagram task before drawing:

| Class | Meaning | Authoritative target |
|-------|---------|----------------------|
| `semantic` | Explain the idea, relationships, or architecture for review | Mermaid is usually enough |
| `inspired-by-reference` | Borrow structure or style from a source, without exact fidelity | Mermaid, draw.io, or Lucid |
| `recreation` | Reproduce a source PDF, image, Lucid, draw.io, or screenshot | draw.io XML / Lucid / measured SVG |

**Rules:**
- For `recreation`, acceptance is pixel-perfect source fidelity unless the user explicitly accepts an approximation.
- Structural similarity is not enough for a recreation.
- Mermaid is a semantic diagram target; do not present Mermaid as a pixel-perfect recreation when exact layout, connector anchors, icons, rotations, or styling matter.
- Escalate to draw.io XML or Lucid when exact geometry, connector bend points, line jumps, or manual label placement are acceptance criteria.
- For source-free diagrams, define a diagram contract before drawing: purpose, audience, nodes, groups, relationships, labels, reading flow, and expected connector endpoints.

### Post-Render Visual QA

After rendering, inspect the actual SVG/PDF/PNG output before handoff:

- Text fits inside every container.
- Containers are sized and balanced after real labels are placed.
- Connector endpoints visibly leave the intended source edge and land on the intended target edge.
- Arrowheads are visible and not hidden behind shapes.
- Lines do not cross labels, important symbols, or containers unless the source explicitly requires it.
- Labels have clearance from borders, connectors, and arrowheads.
- Whitespace is intentional and does not make the layout look broken.
- Editable source and rendered output are equivalent; do not make SVG-only fixes that cannot be regenerated.

Record residual fidelity gaps when the output is an approximation.

### Common Mermaid Errors and Fixes

| Error Pattern | Cause | Fix |
|--------------|-------|-----|
| `Parse error on line N` | Syntax mistake at that line | Read the `^` pointer, fix that token |
| `No diagram detected` | Missing or wrong diagram type declaration | Add `graph TD` / `sequenceDiagram` on line 1 |
| `UnknownDiagramError` | Unsupported diagram type | Check supported types at [mermaid.js.org/intro](https://mermaid.js.org/intro/) |
| `Duplicate node id` | Same node id defined twice | Rename one node |
| Edge label without content | `A -->|  | B` | Fill the label or remove pipes |

---

## Salesforce Architect Diagram Standards

Before generating any architecture diagram, consult the official Salesforce Architect
reference to choose the correct diagram type for the domain and audience.

### Reference Documentation (READ BEFORE DESIGNING)

| Resource | Purpose |
|----------|---------|
| [Diagram Gallery](https://architect.salesforce.com/diagrams) | Browse real-world Salesforce architecture diagram examples |
| [Introduction](https://architect.salesforce.com/docs/architect/reference-diagrams/guide/introduction) | When to use each diagram type |
| [Kit of Parts](https://architect.salesforce.com/docs/architect/reference-diagrams/guide/kit-of-parts.html) | Official shape vocabulary and notation |
| [Data Model Notation](https://architect.salesforce.com/docs/architect/reference-diagrams/guide/data-model-notation.html) | ERD conventions for Salesforce objects |
| [Capability Map](https://architect.salesforce.com/docs/architect/reference-diagrams/guide/section-capability-map.html) | Business capabilities by domain |
| [Solution Architecture](https://architect.salesforce.com/docs/architect/reference-diagrams/guide/section-solution-architecture.html) | Integration, component, and deployment views |
| [System Landscape](https://architect.salesforce.com/docs/architect/reference-diagrams/guide/section-system-landscape.html) | Cross-system context and boundaries |
| [Roadmap](https://architect.salesforce.com/docs/architect/reference-diagrams/guide/section-roadmap.html) | Phased delivery and release planning |

From jterratsdev/smart-deployment, BSD-3-Clause.

More from jterratsdev/smart-deployment