Agentic Mermaid
Menu

Custom styles

Author JSON style files, validate them with the schema, and compare cookbook screenshots.

Custom styles are plain JSON files passed to --style. Keep them in source control, add a seed when the style uses sketch variation, and validate the file before using it from an untrusted source.

am render diagram.mmd --format png --style examples/styles/transit-route-map.style.json --seed 11 --output diagram.png

Use the public schema at /schemas/style-spec.schema.json. The same file is exported from the npm package as agentic-mermaid/style-spec.schema.json, so editors can map either the hosted URL or the package export.

Role styles and policy

Level 3: semantic role defaults. Put typography, padding, radii, line weight, and applicable paint under roles.node, roles.edge, roles.group, or another exact-style role. Fallback-only roles inherit one of those archetypes and are rejected as exact records rather than accepted as no-ops.

{
  "roles": {
    "node": { "fontSize": 16, "paddingX": 28, "cornerRadius": 8 },
    "edge": { "lineWidth": 2, "bendRadius": 10 }
  }
}

Level 4: category bindings and inspect-only constraints. Named semanticSlots can be selected through normalized category bindings. Constraints report warnings or errors from the final admitted scene; they never repaint or repair it.

{
  "semanticSlots": { "selected": { "fillColor": "#fecdd3", "cue": "outline" } },
  "bindings": [{ "channel": "category", "value": "Pro", "slot": "selected", "role": "pie-slice" }],
  "constraints": [{ "kind": "contrast", "action": "error", "minimum": 4.5 }]
}

am verify diagram.mmd --style brand.style.json

Authored Mermaid theme, config, element paint, and family semantics remain authoritative. For example, a Pie binding can style the Pro category but cannot select emphasis or alter wedge geometry. See the full style-authoring guide for the role applicability table, terminal projections, and verification behavior.

Cookbook examples

The package ships complete JSON files under examples/styles/. They cover the clusters that work with the current StyleSpec plus one deliberately incomplete design-system prototype.

cupertino-prototype.style.json is documentation-only: it is not registered or advertised as a built-in Style. Load the file explicitly and pass --options '{"shadow":true}' to exercise its palette, weight-based role typography, surface-first border policy, concentric corner radii, 16-unit connector bends, and the shared shadow render option. It remains intentionally incomplete: bundled Inter stands in for SF Pro, and the static renderer does not claim Apple's motion/spring language or a designed dark companion.

Documentation-only Cupertino-inspired public StyleSpec prototype
cupertino-prototype.style.json uses public role geometry, elevation, and inspect-only constraints to demonstrate concentric corner curves and rounded connector bends; it is not an Apple product, an endorsed implementation, or a built-in Agentic Mermaid Style.
Documentation-only Vercel-inspired public StyleSpec prototype
vercel-inspired-prototype.style.json uses public role styles, XYChart category bindings, semantic slots, and inspect-only constraints; it is not a Vercel product, an endorsed implementation, or a built-in Agentic Mermaid Style.
Documentation-only Cloudflare Workers-inspired public StyleSpec prototype
cloudflare-workers-inspired-prototype.style.json uses public role styles, Gantt section bindings, visible non-color cues, semantic slots, and inspect-only constraints; it is not a Cloudflare product, an endorsed implementation, or a built-in Agentic Mermaid Style.
Transit route map custom style
transit-route-map.style.json stresses thick connectors, rounded bends, compact station labels, and group labels.
Mid-century report custom style
mid-century-report.style.json uses palette, solid fills, typography, corners, and section bands without a custom renderer.
Star chart atlas custom style
star-chart-atlas.style.json tests dark-page tokens, grid backdrop, pale strokes, and serif labels.

Custom fonts

A Style's font field names a CSS family or stack; it does not load a font file. SVG declares the family, while local PNG rendering resolves bundled faces plus caller-provided directories. Use --security strict for an SVG with no external font request, or pass --font-dirs when rendering an unbundled family to PNG.

am render diagram.mmd --format svg --style brand.style.json --security strict --output diagram.svg
am render diagram.mmd --format png --style brand.style.json --font-dirs ./fonts --output diagram.png

Library callers use renderMermaidPNG(source, { style, fontDirs: ['./fonts'] }); loadSystemFonts: true opts into OS-installed faces at the cost of machine-dependent output. Local MCP render_png accepts fontDirs and loadSystemFonts. Hosted MCP has no filesystem font input, so use a local surface when a custom face is required.

Validation

The schema catches file shape in editors. Runtime code should still call validateStyleSpec(json); the CLI does this for .json files passed through --style.

Docs index