excalidraw-diagrams

Excalidraw Diagram Guidelines

These rules produce clean, readable, customer-facing diagrams embedded as inline SVG in the Tigris docs site.

CRITICAL — Read Before Writing Any Diagram

NEVER use label properties on shapes. This is the #1 source of broken diagrams. The label property causes text to overflow and clip outside boxes. Always create a separate text element positioned inside the shape. See the example below.

Embedding Pattern

Diagrams are embedded as React components that render inline SVG. Each diagram has three parts:

1. JSON data file in src/components/diagrams/data/<name>.json — an array of Excalidraw-style element objects
2. Wrapper component in src/components/diagrams/<Name>Diagram.tsx — thin wrapper that imports the JSON and passes it to ExcalidrawDiagram
3. MDX import in the doc page — imports the wrapper and renders it inside a <div className="mermaid-frame">

Wrapper component template

import React from "react";
import ExcalidrawDiagram from "./ExcalidrawDiagram";
import elements from "./data/<name>.json";

export default function <Name>Diagram() {
  return <ExcalidrawDiagram elements={elements} />;
}

MDX usage

Add a mermaid-syntax HTML comment above the diagram for agent readability, then render the component:

{/_ <!-- Mermaid UML description for AI agents:
graph LR
  A[Component] --> B[Component] --> _/}

<div className="mermaid-frame">
  <NameDiagram />
</div>

JSON Data Format — Correct Example

This shows the RIGHT way to put text inside a box — as a separate text element, not a label:

[
  {
    "type": "rectangle",
    "id": "mybox",
    "x": 50,
    "y": 100,
    "width": 200,
    "height": 55,
    "backgroundColor": "#142229",
    "fillStyle": "solid",
    "roundness": { "type": 3 },
    "strokeColor": "#2a4050",
    "strokeWidth": 2
  },
  {
    "type": "text",
    "id": "myboxlbl",
    "x": 75,
    "y": 113,
    "text": "My Label",
    "fontSize": 16,
    "fontFamily": 1,
    "strokeColor": "#c8d6de"
  }
]