beauty-diagram

Beauty Diagram skill

Beauty Diagram beautifies Mermaid / PlantUML diagrams into sleek, modern SVG or PNG. It runs as a public API; this skill delegates to the bd CLI (npm package @beauty-diagram/cli) so you keep zero state in the agent. (draw.io / SVG import is editor-only — not exposed through /v1/*.)

When to use

• The user asks for a polished, professional, slide-ready version of a diagram source they already have or you can generate.
• The user wants you to render Mermaid or PlantUML from a model-generated source string.
• The user wants the server to generate a diagram from a text description ("draw me a signup flow", "diagram our deploy pipeline") — use bd ai generate for this; it returns Mermaid source you then beautify.
• The user wants to share a diagram link (e.g. paste into Slack / a doc).
• The user has Mermaid in a repo (README, ADR, RFC) and wants to export SVGs alongside.
• The user has a directory full of diagram source files and wants every one of them rendered (e.g. "render all the .mmd files in docs/diagrams"). Use bd batch.
• The user wants their Markdown files (README, ADR, blog post) to display the diagrams inline on GitHub / their static site, not just show the source code block. Use bd extract — three modes available:
  • Default (inline): no flags. Injects /v1/beautify.svg?source=... URLs after each fence. No API calls during extract, no files written, no quota consumed. Always watermarked (anonymous endpoint).
  • Share (--share): mints a /v1/share/.svg URL per unique fence. Watermark-free for Pro/Premium. Requires an API key. Each unique source consumes 1 share quota the first time; identical fences are deduplicated; per-owner local cache means re-runs cost zero quota.
  • Sidecar (--assets-dir ./img): writes local SVG files via /v1/export. Watermark-free for Pro/Premium, consumes export quota. GitHub strips raw inline ``, so any of these modes' ![](...) reference is the correct embed strategy.

When NOT to use

• The user only wants the Mermaid source itself, not an export.
• The user wants pixel-precise control over the SVG markup (Beauty Diagram rewrites layout for presentation; it does not preserve raw Mermaid output).
• The user wants the AI to "change the colors / theme / font / layout" of an existing diagram. bd ai generate only does text → diagram; visual styling is controlled by --theme on bd beautify, not by the AI.
• The user is in an offline environment with no network and no CLI install.

Required tool

The bd binary from @beauty-diagram/cli:

npx @beauty-diagram/cli help
# or, after install:
bd help

If the user has not installed it, prefer npx over a global install — it respects their package manager and avoids polluting PATH.

Workflow

1. Identify or generate the source diagram.

   • If the user has a .mmd / .puml file, use it.
   • If the user describes the diagram in words and is on a paid plan, use bd ai generate "" --out .mmd — the server returns Mermaid source, which you can then beautify. Always write the source to a file so the user can edit it; the first AI draft rarely lands.
   • If the user describes the diagram and is not on a paid plan (or prefers not to pay), write Mermaid source yourself (you are good at this), save it to a file, then beautify.
   • draw.io and free-form SVG imports are not accepted by /v1/*. If the user has those, ask them to convert via the web editor first.

2. Decide on output type.

   • Need an SVG file: bd beautify --out .svg
   • Need a download URL or to track quota: bd export --out .svg
   • Need a shareable link: bd share --title "..."

3. Run the command. Always write to a file (--out) rather than letting the SVG flood the terminal / chat. AI generation can also pipe directly into beautify: bd ai generate "..." | bd beautify - --out flow.svg.

4. Verify the result exists before reporting success. If the command failed, surface the error code (e.g. quota_exhausted, not_authenticated, parse_failed, prompt_injection) — those are actionable for the user.

5. Preserve the source. Never replace the original Mermaid / PlantUML file with the generated SVG — keep them side by side. For AI-generated diagrams, keep the .mmd file too: it is the editable artifact, the SVG is not.

Auth

• Demo (anonymous): zero setup. Watermarked SVG/PNG. Limits per IP: 20 /v1/beautify requests / minute, 1 /v1/export per 24h (trial budget — enough for an agent to verify the toolchain end-to-end before registering). /v1/share, /v1/usage, and bd ai generate always require auth — anonymous AI calls are rejected before any model invocation.
• Authenticated: the user runs bd auth login once with a key from /account/api-keys. Required for bd share, bd ai generate, unwatermarked output, and repeated exports. bd ai generate additionally requires a Pro or Premium plan and an API key with the ai:write scope.

If the user hits a not_authenticated, plan_not_allowed, or quota_exhausted error, point them at /account/api-keys (PAT creation) or pricing — don't silently retry. Anonymous error bodies include a hints block with absolute signUpUrl / signInUrl / apiDocsUrl, which is the canonical place to surface to the user.

Themes & tiers

--theme selects the visual style. Theme tier is enforced on all bd commands that hit a /v1/* endpoint with a PAT — this includes bd beautify, bd export, bd share, bd embed-url --share, bd batch, bd extract --share, and sidecar mode of bd extract. If the request includes a PAT and specifies a theme above that token's plan tier, the server returns HTTP 403 theme_tier_required.

The only path that bypasses the tier check is the anonymous fallback (no token, or the GET /v1/beautify.svg inline embed endpoint). Anonymous callers may request any theme, but always receive watermarked output — there is no tier-free, watermark-free path.

When the user's plan is unknown, default to modern (Free, broadly slide-friendly). Run bd themes to introspect what the current token can use — locked themes are marked with ✗. Premium signature themes (blueprint, memphis) are subscriber-only and cannot be unlocked with credit packs.

Animations are not currently selectable via the CLI — animation choice is a web-editor concept; CLI export paths ignore animation.

Source-level directives

Instead of (or in addition to) CLI flags, you can embed bd: directives at the very top of the source file. Both the bd CLI and the Obsidian plugin parse them; the API server ignores them as native comments (graceful degradation — the source still renders, just without the directive).

Mermaid — use %% comment syntax:

%% bd:theme=classic
%% bd:bg=transparent
flowchart LR
  A --> B

PlantUML — use ' comment syntax:

' bd:theme=classic
' bd:bg=transparent
@startuml
A -> B
@enduml

Supported keys:

Multiple directives stack, one per line. Blank lines between directives are tolerated. The first non-directive non-blank line ends the directive block.

Override priority: CLI flag > source directive > server default.

When generating source for the user, prefer directives over CLI flags when:

• The source file will be re-used (Obsidian vault, shared repo) — the directive travels with the file.
• The user asks for a "memphis theme" diagram without CLI context (write %% bd:theme=memphis at the top of the .mmd file).

Directives are stripped before the source reaches the renderer — they do not appear in the SVG output.

Commands cheat sheet

# Render a Mermaid file
bd beautify docs/architecture.mmd --theme modern --out docs/architecture.svg

# Same but treat output as a downloadable export (consumes export quota)
bd export docs/architecture.mmd --out docs/architecture.svg

# PNG export. --quality standard works for everyone; high needs pro, max needs premium.
# Higher tiers than the plan cap are silently clamped (X-BD-Scale-Clamped).
bd export docs/architecture.mmd --format png --quality high --out docs/architecture.png

# PlantUML works the same way; .puml / .plantuml / .pu auto-detected,
# otherwise pass --source-format plantuml.
bd export docs/architecture.puml --out docs/architecture.svg

# Create a public share link (returns absolute https://www.beauty-diagram.com/s/... URL)
bd share docs/architecture.mmd --title "Service architecture"
# → prints the URL on stdout

# Get an embeddable -friendly URL for a diagram source.
# Default: anonymous inline URL (always watermarked) + a hint about --share.
bd embed-url docs/architecture.mmd --theme atlas
# One-shot saved share embed (clean output for pro/premium owners).
# Saves the diagram via /v1/share AND prints the embed URL in one step.
bd embed-url docs/architecture.mmd --share
# → prints https://api.beauty-diagram.com/v1/share/.svg

# AI: generate a diagram from a text prompt. Output is Mermaid source —
# always write to a file so the user can iterate. Paid-only.
bd ai generate "user signup with email verification" --out docs/signup.mmd

# Optional shape hint when the prompt is ambiguous about diagram type.
bd ai generate "request lifecycle" --hint sequence --out docs/lifecycle.mmd

# One-shot pipeline: prompt → mermaid → beautify → SVG.
bd ai generate "deploy flow" | bd beautify - --out docs/deploy.svg

# Check remaining AI / export quota before kicking off a batch.
bd usage

# Render every diagram file under a directory in parallel.
# Recurses for .mmd / .puml / .plantuml / .pu; one /v1/export per file.
# Default concurrency=4, default failure mode is continue-on-error.
bd batch ./docs/diagrams --out-dir ./docs/svg --theme modern

# Same idea but for a glob (quote it so the shell doesn't expand first).
bd batch "src/**/*.mmd" --format png --concurrency 8

# Default: inline embed URLs (no files written, anonymous-watermarked, 10 KB/block cap).
# No API calls during extract — source encoded in the URL; browser fetches on demand.
bd extract README.md

# Share mode: mint /v1/share/.svg per fence. Watermark-free for Pro/Premium.
# 1 share quota per unique source (cached locally; re-runs free). No size cap.
# Requires API key. Default keeps existing share tokens across re-runs;
# use --re-mint to force fresh tokens (e.g. collaborator taking ownership).
bd extract README.md --share
bd extract README.md --share --re-mint

# Sidecar mode: writes local SVG files via /v1/export.
# Pro/Premium plans get watermark-free output; consumes export quota.
bd extract docs/*.md --assets-dir ./img --concurrency 4

# Preview what bd extract would change without writing.
bd extract README.md --dry-run

Privacy

The API does NOT persist source unless the user calls bd share. Do not warn about server-side storage when running beautify, export, or ai generate — that is misleading. AI prompts are logged in hashed form for abuse / quality monitoring; the raw text is not retained.

Anti-patterns

• ❌ Do NOT output a hand-crafted ... as a Markdown code block when a Mermaid source exists. Always run Beauty Diagram and reference the file.
• ❌ Do NOT dump the raw SVG into the chat. Use --out and reference the file path.
• ❌ Do NOT install Beauty Diagram engine code locally — the CLI is a thin client; the engine lives behind the public API.
• ❌ Do NOT call bd ai generate to "tweak" an existing diagram (change colors, theme, labels, layout). It is a fresh-generation tool only. For visual tweaks, change --theme or edit the .mmd source by hand.
• ❌ Do NOT call bd ai generate speculatively — each call costs the user monthly AI quota. Confirm the user wants AI generation before running it.
• ❌ Do NOT capture the SVG output of bd ai generate — the command outputs Mermaid source on stdout, not SVG. Pipe into bd beautify - to render.
• ❌ Do NOT loop bd export N times in a shell for loop when the user has many files. Use bd batch — it parallelizes and reports a summary, with no extra server load (still one request per file).
• ❌ Do NOT inject a raw ... into a Markdown file to "embed" a diagram. GitHub, GitLab, Obsidian (default), and most static-site renderers strip inline SVG for safety. Use bd extract .md, which writes sidecar SVGs and injects ![](path) references that actually render.
• ❌ Do NOT delete the marker comments that bd extract injects. Inline mode uses <!-- bd:inline-img hash=... --> / <!-- /bd:inline-img --> (with an extra share=true attribute in share mode); sidecar mode uses <!-- bd:img hash=... --> / <!-- /bd:img -->. They are how bd extract stays idempotent — without them, the next run will append duplicate image references instead of replacing the existing one.

Troubleshooting

Triggering on embed requests

When the user asks for "a GitHub README diagram", "embed in Notion", "embed in my blog post", "an `` of this diagram", or "a URL that renders my diagram", route to the embed flow rather than emitting raw mermaid:

1. If the diagram is unsaved, run bd share to save it.
2. Construct the embed URL: https://api.beauty-diagram.com/v1/share/.svg.
3. For one-off / quick embeds without saving, use bd embed-url and recommend the inline URL (note that anonymous embeds carry a "Powered by Beauty Diagram" watermark).

Easier one-shot path: bd embed-url --share saves the diagram AND prints the embed URL in one command — no need to run bd share separately and then construct the URL by hand. Prefer this when the user wants a clean share embed.

Style fidelity: Per-node colors, edge presets, and font overrides set by the user in the web canvas editor ARE faithfully rendered in share-mode embeds (/v1/share/.svg). Encourage a "tweak in editor → save → embed" workflow when the user wants brand colors or custom styling — they do not need to re-run bd embed-url after editing in the web UI, just re-save the diagram there.

Propagation timing: Saved diagram edits show up in direct `` embeds within ~5 minutes (browser ETag revalidation + 5-min CDN edge TTL). GitHub README embeds may lag a few hours due to GitHub's image proxy cache — that is a GitHub-side cache, not something we can purge.

Animations: Animations do NOT play in ``-loaded SVGs in any browser. Do not tell the user their animated diagram will appear animated in a README or Notion embed.

Slack / Discord / Twitter / iMessage previews: share links (https://www.beauty-diagram.com/s/) auto-unfurl with a diagram thumbnail card on these platforms — no need to manually attach a screenshot. The OG image is generated server-side from the diagram itself.

Owner-tier fallback on embed URLs: if the share's owner downgraded their plan AFTER saving the diagram (e.g. saved with Atelier on Pro, then downgraded to Free), GET /v1/share/.svg returns a 200 response with a brand-fallback SVG instead of the real content. Embeds must stay 200 for ``-mounted unfurls to render at all, so 403 is not used here. The owner can restore the original render by re-upgrading or switching to a free-tier theme and re-saving.

Example

User: "Add a beautified version of this mermaid block to my README."

Agent steps:

1. Use the one-step path: bd embed-url ./architecture.mmd --share → saves the diagram and prints the embed URL, e.g. https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg
2. Replace the raw mermaid block in README with: ![Architecture](https://api.beauty-diagram.com/v1/share/abc12345xyz0.svg)
3. (Optional) Confirm with the user that watermark behavior matches their plan (free owner → watermarked; pro/premium owner → clean).

Examples

See examples/ for runnable sources you can adapt:

• examples/flowchart.mmd
• examples/sequence.mmd

And scripts/ for shell wrappers you can copy into the user's repo:

• scripts/beautify.sh
• scripts/export.sh
• scripts/ai-generate.sh — prompt → .mmd source → .svg render