Documentation

Everything you need to know about diagrams.love — the AI-native diagramming tool.

What is diagrams.love?

diagrams.love is an AI-powered diagram editor. Create flowcharts, system architecture diagrams, user journey maps, process flows — anything with visual structure. Describe what you need in plain language and AI builds it instantly, or use the canvas editor to draw manually.

Create Your First Diagram

There are multiple ways to create a diagram. Choose whichever fits your workflow:

1. 1

   Open the Canvas

   Go to /canvas (or click Open Canvas in the nav). Sign in — it only takes a moment.

2. 2

   Choose your creation method

   AI: Open the AI chat panel, describe what you need — AI builds the diagram.
   Manual: Double-click the canvas to add cards, drag between cards to create connections.

3. 3

   Customize & Share

   Change colors, add tags, rename cards. Then hit Share to get a public link anyone can open.

Canvas Basics

The canvas is an infinite whiteboard. Here's how to navigate:

Cards & Connections

Element Types

• Card — standard block with title, description, tags, and color. The most common element type.
• Condition (Diamond) — decision point for branching logic. Use for Yes/No forks in a flow.
• ASCII — monospace text card for wireframes and text layouts. Great for sketching UI screens.
• HTML — rich card with live HTML content — buttons, forms, animations. Use for interactive mockups.
• iFrame — embed any URL directly on the canvas — live websites, Figma prototypes, data dashboards.

Creating Connections

1. Hover over any card — connection handles appear on the edges
2. Drag from a handle to another card to create an arrow
3. Double-click a connection line to add a label
4. Right-click a connection to delete it or change direction

Editing Cards

Click a card to open the detail panel on the right. You can edit:

• Title and description
• Color (10 named values)
• Tags (custom labels per diagram)
• Date field
• Card type (Card, Condition, ASCII, HTML, iFrame)

Colors & Tags

Color System

Each card has a single color field. Choose from 10 named colors — these control the card's visual accent (border and fill are unified under one color value).

Tags

Tags are custom labels you add to cards. Each diagram has its own tag set — tags are per-diagram, not global. Use them to filter, categorize, or track state (e.g. "in_progress", "system", "external").

To create a tag: open any card, click the Tags field, type a name and press Enter. Tag colors are assigned automatically based on the tag name for visual consistency across cards.

Keyboard Shortcuts

Managing Diagrams

The dashboard is your home base — a list of all diagrams you own or have access to. All diagrams are private by default and only visible to you.

Projects & Subprojects

Projects are folders that let you organize diagrams into groups. You can nest projects inside other projects to create a tree hierarchy.

Working with Projects

• Create a project from the dashboard sidebar — give it a name and it appears in the left panel
• Drag and drop diagrams from the main list into a project folder
• Create sub-projects by nesting a project inside another project
• Rename or delete projects via right-click. Deleting a project does not delete the diagrams inside — they move back to the root level
• Via MCP: use list_projects, create_project, and move_schema_to_project to manage projects programmatically

Share via Link

Every diagram can be shared via a public read-only link. Recipients can view the diagram in full without creating an account.

How to Share

1. Open a diagram on the canvas
2. Click the Share button in the toolbar
3. Choose "Via Link" — the public link is copied to clipboard
4. Anyone with the link can open and view your diagram

Invite Collaborators

You can invite specific people to a diagram by email. Collaborators must have a diagrams.love account.

Access Roles

To manage collaborators: open the Share popup on a diagram, go to the "People" tab, enter an email, choose a role, and send the invite. The owner can revoke access at any time.

Edit Links

Edit links let you share a diagram as editable without requiring the recipient to have an account. Available on Pro and Max plans. Generate an edit link from the Share popup — anyone with the link gets Editor access.

Presentation Mode

Presentation mode turns your diagram into a clean fullscreen view — perfect for walkthroughs, demos, and meetings.

• Hides the toolbar and editing UI
• Clean background, focused on the diagram
• Works on shared links too — send the presentation URL directly
• Works on any screen — desktop, tablet, projector

To enter: click the Present button in the toolbar, or add ?present=1 to any diagram URL.

Export Formats

The JSON export is powerful — send it to ChatGPT or Claude, ask them to modify it, then reimport the updated JSON. This is the AI Edit workflow.

AI Chat

The AI chat panel is built into the canvas editor. Open it from the toolbar (AI button). You can:

• Describe a process or system — AI creates a full diagram
• Ask AI to modify the existing diagram ("add an error state", "split this step into two")
• Ask questions about your diagram structure
• Request analysis, suggestions, or missing steps

AI Generation

diagrams.love supports 400+ AI models via OpenRouter. Your prompt produces a structured JSON diagram which renders instantly on canvas.

Example Prompts

• "User registration flow with email verification and role selection"
• "E-commerce checkout process including payment failure handling"
• "CI/CD pipeline from commit to production deployment"
• "Customer support ticket lifecycle from open to resolved"

AI Edit Workflow

Use external AI tools (ChatGPT, Claude) to edit diagrams:

1. Export your diagram as JSON (Export button)
2. Paste the JSON into ChatGPT or Claude with your edit request
3. Copy the returned JSON
4. Import it back into diagrams.love (Import from JSON button)

MCP Integration

The MCP (Model Context Protocol) server lets AI tools like Claude Desktop, Cursor, and Windsurf create and edit diagrams directly — no copy-pasting JSON. Available on Pro and Max plans.

Quick Start

1. 1

   Get your token

   Open Profile & Settings and copy your token from the "MCP Integration" section.

2. 2

   Add to your MCP client config

   Add this block to your MCP client config (e.g. ~/.claude.json for Claude Code):

   ~/.claude.json Copy

   {
     "mcpServers": {
       "diagrams-love": {
         "command": "npx",
         "args": ["-y", "diagrams-love-mcp"],
         "env": {
           "DIAGRAMS_TOKEN": "your_token_here"
         }
       }
     }
   }

3. 3

   Restart your MCP client

   Restart Claude Code, Cursor, Windsurf, or your other MCP client. The diagrams-love server is now available.

Available Commands

All commands are available as MCP tools. When used via Claude Code they are prefixed automatically (e.g. mcp__diagrams-love__list_schemas).

JSON Diagram Format

Diagrams are plain JSON. Each element in the elements array follows this structure:

{
  "id": "unique_id",
  "type": "card",        // card | condition | ascii | html | iframe
  "title": "Card Title",
  "color": "blue",       // color name (see Colors section)
  "tags": ["tag1"],
  "description": "Description text",
  "content": "...",      // REQUIRED for ascii/html/iframe types
  "connections": [
    {"to": "target_id", "label": "optional label"}
  ]
}

Full Example

{
  "name": "User Registration",
  "elements": [
    {
      "id": "start",
      "type": "card",
      "title": "Registration Form",
      "color": "green",
      "tags": ["user"],
      "description": "User fills email and password",
      "connections": [{"to": "validate", "label": "submit"}]
    },
    {
      "id": "validate",
      "type": "condition",
      "title": "Valid?",
      "color": "yellow",
      "connections": [
        {"to": "save", "label": "yes"},
        {"to": "error", "label": "no"}
      ]
    },
    {
      "id": "save",
      "type": "card",
      "title": "Save to DB",
      "color": "blue",
      "description": "Create user record",
      "connections": [{"to": "success"}]
    },
    {
      "id": "error",
      "type": "card",
      "title": "Show Error",
      "color": "red",
      "connections": [{"to": "start", "label": "retry"}]
    },
    {
      "id": "success",
      "type": "card",
      "title": "Success",
      "color": "green"
    }
  ]
}

Colors in JSON

Use color names (not hex values) for the color field. Valid values: default, blue, green, orange, purple, red, teal, yellow, gray, black.

Frequently Asked Questions

Troubleshooting

MCP token not working?

• Tokens don't expire unless manually revoked — check Profile
• Make sure you copied the entire token (no trailing spaces)
• MCP requires Node.js 18 or newer — check with node --version

MCP not connecting?

• Check JSON syntax in your config file — even a trailing comma breaks it
• The environment variable must be named exactly DIAGRAMS_TOKEN
• MCP requires Pro or Max plan — Free plan cannot use MCP
• After editing the config, fully restart your MCP client (not just reload)

AI chat not responding?

• Check your AI credits balance in Profile → AI Settings
• Free plan: $3 one-time credits — upgrade to Pro or Max when depleted
• Try a different AI model — some may be temporarily unavailable on OpenRouter

Canvas not loading?

• Hard refresh the page: Ctrl+Shift+R (or Cmd+Shift+R on Mac)
• Check your internet connection — the canvas requires a live connection to load and save
• Try opening the diagram in a new browser tab

Need more help?

MCP package on npm: diagrams-love-mcp.