Mermaid GitHub Safe-Area

Use this skill when editing Mermaid diagrams for GitHub README rendering to prevent the bottom-right navigation/zoom controls from overlapping diagram content, using only %%{init: ...}%% configuration.

Constants

• CONTROLS_HEIGHT_PX = 110
• BUFFER_PX = 20
• SAFE_PX = 130

Use SAFE_PX as the minimum safe-area value.

Style keyword support: "handrawn style"

If the user asks for "handrawn style" or "hand drawn style":

• Always set a handwritten-style font stack via top-level fontFamily:
  • fontFamily = "virgil, excalifont, segoe print, bradley hand, chalkboard se, marker felt, comic sans ms, cursive"
• For flowcharts (and other supported types), also set look = "handDrawn".
• For sequence diagrams, do not set look (ignored/not supported there); rely on fontFamily only.

Rules

• The first non-empty line of every Mermaid block must be a valid init directive: %%{init: { ...valid JSON... }}%%.
• JSON booleans must be true/false, not quoted strings.
• Do not use spacer nodes or CSS; only Mermaid init config.

Flowcharts

• Ensure flowchart.diagramPadding >= SAFE_PX (default 130).
• This pads all sides; accept the tradeoff to avoid spacers/CSS.

Default example:

%%{init: {"flowchart": {"diagramPadding": 130}, "htmlLabels": true}}%%
flowchart TB
  Start --> State1 --> State2 --> End

Handrawn style example:

%%{init:{
  "look":"handDrawn",
  "fontFamily":"virgil, excalifont, segoe print, bradley hand, chalkboard se, marker felt, comic sans ms, cursive",
  "htmlLabels":true,
  "flowchart":{"diagramPadding":130}
}}%%
flowchart TB
  Start --> State1 --> State2 --> End

Sequence diagrams

• Ensure sequence.diagramMarginX >= SAFE_PX (protects right side).
• Ensure sequence.bottomMarginAdj >= SAFE_PX (protects bottom).
• Keep sequence.diagramMarginY modest (20-40). If missing, set to 30.

Default example:

%%{init: {"htmlLabels": true, "sequence": {"diagramMarginX": 130, "diagramMarginY": 30, "bottomMarginAdj": 130}}}%%
sequenceDiagram
  participant A
  participant B
  A->>B: Hello
  B-->>A: Hi

Handrawn style example:

%%{init:{
  "fontFamily":"virgil, excalifont, segoe print, bradley hand, chalkboard se, marker felt, comic sans ms, cursive",
  "htmlLabels":true,
  "sequence":{"diagramMarginX":130,"diagramMarginY":30,"bottomMarginAdj":130}
}}%%
sequenceDiagram
  participant A as Alice
  participant B as Bob
  A->>B: Hello Bob
  B-->>A: Hi Alice

Merging existing init directives

When an init directive already exists:

1. Parse the JSON.
2. Preserve unrelated keys.
3. Apply minimums by taking max(existing, SAFE_PX).
4. If the user requested handrawn style, apply the style settings described above.

Merge rules:

• Flowchart: flowchart.diagramPadding = max(existing, SAFE_PX).
• Sequence: sequence.diagramMarginX = max(existing, SAFE_PX) and sequence.bottomMarginAdj = max(existing, SAFE_PX).
• If sequence.diagramMarginY is missing, set it to 30.
• If handrawn style is requested:
  • Flowchart: set look = "handDrawn" and fontFamily = <handwritten font stack>.
  • Sequence: set fontFamily = <handwritten font stack> and do not set look.

Pseudocode:

SAFE_PX = 130
HAND_FONT = "virgil, excalifont, segoe print, bradley hand, chalkboard se, marker felt, comic sans ms, cursive"

if diagram_type == "flowchart":
    init.flowchart.diagramPadding = max(init.flowchart.diagramPadding or 0, SAFE_PX)
    if wants_handrawn_style:
        init.look = "handDrawn"
        init.fontFamily = HAND_FONT

if diagram_type == "sequenceDiagram":
    init.sequence.diagramMarginX  = max(init.sequence.diagramMarginX  or 0, SAFE_PX)
    init.sequence.bottomMarginAdj = max(init.sequence.bottomMarginAdj or 0, SAFE_PX)
    if init.sequence.diagramMarginY is missing:
        init.sequence.diagramMarginY = 30
    if wants_handrawn_style:
        init.fontFamily = HAND_FONT

Tuning guidance

• If overlap persists, increase SAFE_PX by +20 to +60.
• Prefer increasing:
  • Flowcharts: flowchart.diagramPadding
  • Sequence: sequence.bottomMarginAdj first, then sequence.diagramMarginX

Quick reference

• Flowchart (safe area): %%{init: {"flowchart": {"diagramPadding": 130}}}%%
• Sequence (safe area): %%{init: {"sequence": {"diagramMarginX": 130, "bottomMarginAdj": 130}}}%%
• Handrawn style keyword:
  • Flowchart: add look:"handDrawn" plus fontFamily:<stack>
  • Sequence: add fontFamily:<stack> only