Make a Mermaid diagram readable on a phone

A sharp export can still be unreadable. Consider a diagram with a 1,200-pixel logical width displayed in a 360-pixel article column. It is reduced to 30% of its original size. A label that was 16 pixels tall becomes roughly 4.8 pixels tall. Exporting more pixels improves sharpness, but it cannot make that label occupy more space on the page.

The remedy is to change the composition before choosing the export scale. This worked example uses an illustrative approval workflow, not a record of a real organization's process.

Start with the relationship you need to preserve

An author submits a draft. A reviewer either approves it for publication or asks for revision. Revision returns to the same review step. A mobile redesign must keep that return path; removing it to make the diagram smaller changes the meaning.

Here is the wide version:

flowchart LR
    draft["Author prepares draft"] --> review{"Reviewer approves?"}
    review -->|Yes| publish["Publish the approved article"]
    review -->|No| revise["Author addresses review comments"]
    revise --> review

Look at the diagram at your intended reading width, not only on a desktop preview canvas. The long labels and left-to-right flow consume horizontal space that the mobile article cannot provide.

Change direction and move explanation into prose

Switch to top-to-bottom flow, shorten the action labels, and explain the workflow beside the figure. TD requests a vertical layout; it is not a promise that every branch will occupy a single column.

flowchart TD
    accTitle: Article review workflow
    accDescr: A draft goes to review. Approval leads to publication. Revision returns to review.
    draft["Draft"] --> review{"Approved?"}
    review -->|Yes| publish["Publish"]
    review -->|No| revise["Revise"]
    revise --> review

In this version, “Revise” means the author addresses the review comments and submits the draft again. The loop says where that draft goes. The diagram no longer has to carry the whole explanation inside each box.

Mermaid documents direction settings in its flowchart reference. The accessibility reference describes accTitle and accDescr. Keep an equivalent caption in the destination article too: when you use a PNG, SVG accessibility metadata does not travel with the pixels.

Split details when changing direction is not enough

If the review step includes legal review, image checks, and technical validation, ask whether readers need all those details in the overview. You can make a second diagram called “Inside review” and keep the overview focused on the decision and its outcomes.

Keep names consistent across both diagrams. If the overview says “Review” and the detail says “Quality gate,” a reader may not realize they are the same step. State how the detail returns to the overview: approved drafts proceed to publication; drafts needing changes return to revision.

Sequence diagrams and Gantt charts often need their horizontal axis. For those, a horizontally scrollable preview may be more honest than squeezing every participant or date onto a phone screen. When exporting a static image, reduce the participant set or publish separate phases with explicit handoff points.

Choose export settings after the layout works

For a blog platform that expects a bitmap, use PNG and choose a scale appropriate for the intended display width. If the diagram will display at 360 CSS pixels, a 720-pixel-wide export provides two image pixels per CSS pixel. That is a practical starting point, not a guarantee of legibility.

Use a solid light background if you cannot predict the destination's theme. Transparent exports can lose contrast against a dark page. If the destination supports SVG correctly, use SVG for scaling, then check text and fonts in that destination. See the export guide for the tradeoffs.

Check the actual embedded result

Paste the image into a draft of the article and open that draft at the target width. Read the longest label, follow the revision loop, and check that Yes and No remain attached to the right branches. Confirm that no arrow or caption is clipped.

If readers need pinch-to-zoom to understand the main decision, simplify or split the diagram again. A higher-resolution file is useful only after the design gives the text enough room.