readable-mermaid: Automatic readability optimization for Sequence Diagram

[missmoss]

Complex diagrams are unreadable at default settings — a case for automatic readability optimization

The problem

For simple diagrams (≤4 participants, short labels), Mermaid's default rendering is perfectly fine. But once a diagram exceeds ~5-6 components, the output becomes very difficult to read. Text shrinks, spacing gets tight, and the diagram requires zooming and horizontal scrolling to parse.

Here's a fairly typical sequence diagram — 10 participants, 20 messages, nothing extreme by real-world standards:

sequenceDiagram
    autonumber
    participant User as User
    participant Frontend as Frontend
    participant Gateway as API Gateway
    participant Auth as Auth Service
    participant Project as Project Service
    participant Orchestrator as Orchestrator
    participant Queue as Job Queue
    participant Worker as Worker
    participant Artifact as Artifact Store
    participant DB as Metadata DB

    User->>Frontend: Open release workflow and confirm deployment options
    Frontend->>Gateway: Submit release request with environment, commit, and rollout policy
    Gateway->>Auth: Validate session, team membership, and deploy permissions
    Auth-->>Gateway: Return identity, scopes, and approval context
    Gateway->>Project: Load service configuration, release template, and environment defaults
    Project-->>Gateway: Return normalized release settings and dependency graph
    Gateway->>DB: Create release record with pending status and full request snapshot
    DB-->>Gateway: Persisted release id and audit metadata
    Gateway->>Orchestrator: Start release planning with release id and deployment graph
    Orchestrator->>Queue: Enqueue rollout preparation job with ordered execution plan
    Queue-->>Worker: Dispatch rollout preparation task to worker pool
    Worker->>Artifact: Resolve build artifact, manifest, and signed provenance bundle
    Artifact-->>Worker: Return artifact uri, digest, and verification result
    Worker->>DB: Update release state to prepared with artifact and validation summary
    DB-->>Worker: Persist prepared state and timestamps
    Worker-->>Orchestrator: Preparation complete with rollout checkpoints and health gates
    Orchestrator->>Queue: Enqueue execution job for staged rollout and live monitoring
    Queue-->>Worker: Dispatch execution task with rollout batches and abort thresholds
    Worker->>DB: Persist rollout progress, partial completion, and final succeeded status
    DB-->>Frontend: Surface final release status for UI refresh and follow-up actions

Paste that into the Mermaid Live Editor and try reading it at normal zoom. The text is barely legible.

This matters because these are exactly the diagrams that show up in real technical design documents — and in my experience, reviewers often skip over them because the cognitive cost of zooming and panning is too high.

Why existing tools focus on aesthetics, not readability

The current ecosystem offers themes, color palettes, and visual editors. These improve how a diagram looks, but they don't address the core issue: text is too small to read at normal zoom when the diagram has more than a handful of components. Most editors don't even expose font size as a configurable option.

There's a technical reason for this. Changing colors is stateless — swapping a hex code doesn't affect any other element's position. But the moment you touch font size or spacing, elements start affecting each other: larger text may overlap adjacent arrows, wider nodes may collide with neighbors, taller headers shift lifeline start positions. It's a cascading layout problem, and it's much harder to solve than theming. A naive "just make the font bigger" on the SVG doesn't work — things overlap immediately.

A different approach: render from source with readability-first layout

Instead of patching Mermaid's SVG output, readable-mermaid parses the .mmd source directly and renders it with a custom layout engine built for readability. It doesn't use the Mermaid library at render time — just the .mmd syntax as input format.

The approach:

1. Custom layout engine — parse the .mmd source directly and render with its own layout logic, rather than patching Mermaid's SVG output. This means spacing, font sizes, and element positioning are all computed for readability from the start.
2. Sequence-specific heuristics — when participant headers would overlap (common at 6+ participants or with long labels), stagger them into multiple rows to reclaim horizontal space.
3. Doc-ready output — one command in, a readable SVG and PNG out.

The tool

readable-mermaid — a zero-config CLI. One command in, doc-ready SVG and PNG out. Runs locally using your system's installed Chrome, no network calls.

readable-mermaid input.mmd

[readable-mermaid REPO LINK]

Would love to hear if others have run into this, and whether there's been discussion about a post-render readability pass as part of the Mermaid pipeline.

[DavidSeptimus]

Configurable actorFontSize and messageFontSize not working is part of longstanding bug that results in the default font size overriding the custom sizes first reported in #3990.

Fixing this requires a bug fix, not some post-processing CLI.