# Mermaid Target Strategy

Task: DIAGRAM-MERMAID-TARGET-STRATEGY
Date: 2026-05-16

## Position

Mermaid should be supported as the default semantic diagram target for docs,
architecture notes, pull requests, and offline agent evidence. It is not the
right target for high-fidelity recreation of PDF, Lucid, or presentation assets
where exact geometry, icon placement, connector routing, line jumps, or manual
label positioning matter.

When the user asks for a recreation, the acceptance target is pixel-perfect
source fidelity unless they explicitly accept an approximation. In that mode,
Mermaid can be used only as a semantic companion artifact; it is not the
authoritative recreation target.

Use this target order:

1. Mermaid first when the goal is explainability, reviewability, markdown-native
   documentation, or fast validation.
2. draw.io XML when the goal is editable high-fidelity layout, controlled
   connector anchors, bend points, line jumps, rotated labels, and SVG parity.
3. Lucid/Lucidspark when the goal is collaborative editing, stakeholder review,
   live boards, or use of a visual tool already owned by the team.

## Decision Matrix

| Diagram family | Mermaid fit | Recommended Mermaid type | Escalate to draw.io/Lucid when |
| --- | --- | --- | --- |
| Swimlane workflow | Medium | `flowchart` with subgraphs | Equal lane sizing, exact header styling, lane icons, or complex retry routing are required. |
| Technology roadmap | Medium | `gantt` | Cards must be staggered freely, include component icon legends, or align to a branded roadmap template. |
| Timeline infographic | Medium-high | `timeline` or `flowchart` | The visual is a presentation infographic with alternating cards, decorative icons, or precise spacing. |
| Layered enterprise architecture | Medium | `flowchart` with subgraphs | The diagram has many system cards, badges, layer rails, dense integration lines, or needs pixel-level readability. |
| UML state machine | High for semantics, low for recreation | `stateDiagram-v2` | The task is to recreate a reference diagram with exact arrows, labels, internal actions, history markers, or line crossings. |
| Sequence/integration | High | `sequenceDiagram` | Stakeholder-facing visual branding or custom swimlanes are required. |
| Data model | High | `erDiagram` | Crow's-foot styling, domain colors, or physical layout are part of the deliverable. |

## Mermaid Implementation Rules

- Classify the work before authoring:
  - `semantic`: explain the idea; Mermaid is usually enough.
  - `inspired-by-reference`: borrow structure/style; Mermaid may be enough if
    visual fidelity is not acceptance criteria.
  - `recreation`: reproduce the source; use draw.io/Lucid as the authoritative
    target and validate pixel-perfect gaps.
- Start from a diagram contract: purpose, audience, required elements, grouping,
  relationships, reading flow, and validation criteria.
- Preserve semantics over visual fidelity. If Mermaid cannot express exact
  placement, document the approximation.
- Prefer native Mermaid types:
  - `flowchart` for workflows, swimlanes, layered architecture, component maps.
  - `gantt` for roadmaps with actual dates.
  - `timeline` for milestone narratives.
  - `stateDiagram-v2` for lifecycle/state logic.
  - `sequenceDiagram` for integration order.
  - `erDiagram` for entity relationships.
- Keep labels short. Mermaid text wrapping is renderer-dependent.
- Avoid depending on exact connector paths. Mermaid owns layout.
- Use subgraphs as semantic groups, not as guaranteed layout containers.
- Run Mermaid lint/render validation before publishing.
- Capture residual gaps in the experiment or evidence file.

## Escalation Rules

Escalate from Mermaid to draw.io/Lucid when any of these are acceptance criteria:

- source-reference fidelity, near-pixel recreation, or pixel-perfect recreation.
- exact lane sizes, timeline card positions, or layer rails.
- explicit connector anchors, bend counts, line jumps, or no-line-over-label guarantees.
- rotated labels or non-horizontal text.
- branded icon libraries, dense badges, or presentation-quality visual hierarchy.
- manual stakeholder editing in a visual canvas.
- rendering must match screenshots across tools, not only describe the architecture.

## Validation Strategy

For Mermaid:

- validate syntax with `orchestra diagrams lint --file <diagram.mmd>`.
- render to SVG where local Mermaid tooling is available.
- visually inspect the rendered output for nonblank content, readable labels, and
  grouping semantics.
- document known loss versus the source SVG/draw.io/Lucid output.

For draw.io/Lucid:

- for recreation, compare source and output as a pixel-perfect review, not only
  as a semantic review.
- keep editable source and rendered SVG equivalent.
- run post-render visual QA for text fit, connector endpoints, z-order, line
  overlaps, and label clearance.
- capture screenshots as evidence.

## Experiment Mapping

The recent SVG experiments now have Mermaid semantic counterparts:

- `docs/diagrams/experiments/swimlane/diagram.mmd`
- `docs/diagrams/experiments/roadmap/diagram.mmd`
- `docs/diagrams/experiments/timeline/diagram.mmd`
- `docs/diagrams/experiments/sfdc-implementation/diagram.mmd`

These Mermaid files should be reviewed as semantic approximations, not visual
replacements for the SVG experiments.