Why Your GitHub README Diagrams Look Amateur (and the 4 Fixes That Take 10 Minutes)

TL;DR
If your README diagrams look like every other open-source repo's, that's because they all use the same four defaults. Switching to theme: 'base' plus tuning four properties takes under ten minutes and produces a diagram that looks intentional. This is a follow-up to last week's SVG rendering deep-dive.

The four defaults that ruin your diagrams

1. Pastel pink/blue palette — the default theme is from a 2014 Bootstrap-era moodboard. It signals "I copy-pasted from the docs."
2. Curved edges (basis) — works for organic flows, terrible for technical diagrams. Lines that should be crisp end up wavy.
3. Default font — varies wildly by viewer. Looks fine in the GitHub editor preview, looks like Times New Roman in your CI artifact.
4. Hardcoded background — light theme on a dark page, or vice versa. The diagram becomes a rectangle.

Each takes one config change to fix.

Fix 1: Switch to base theme

%%{init: {'theme':'base'}}%%
flowchart LR
  A --> B --> C

base is the only theme that exposes themeVariables for full control.

Fix 2: Set six theme variables

%%{init: {
  'theme':'base',
  'themeVariables': {
    'primaryColor': '#1e293b',
    'primaryTextColor': '#f8fafc',
    'primaryBorderColor': '#475569',
    'lineColor': '#94a3b8',
    'fontFamily': 'system-ui, sans-serif',
    'fontSize': '14px'
  }
}}%%

Six variables. That's the entire customization surface you actually need. Mermaid exposes around fifty in total, but the ones above cover 90% of the visual identity of a diagram. Ignore the rest unless you have a specific reason.

Fix 3: Linear edges

%%{init: {'flowchart': {'curve': 'linear'}}}%%

For hierarchies, use step. For organic flows, keep basis. For everything else, linear.

Fix 4: Light/dark adaptive embed

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./diagrams/auth-flow-dark.svg">
  <img alt="Auth flow" src="./diagrams/auth-flow-light.svg">
</picture>

GitHub READMEs respect prefers-color-scheme. Ship two SVGs and let GitHub pick.

A small but important caveat: this only works for pre-rendered SVGs that you commit to the repo. Inline mermaid code blocks in your README can't use <picture> — they're rendered by GitHub's own Mermaid runtime at view time, with no hook for swapping based on theme. If you want adaptive diagrams in a README, you have to render to SVG first.

Putting all four together

Here's the minimum viable beautified README diagram, end to end:

---
config:
  theme: base
  themeVariables:
    primaryColor: '#1e293b'
    primaryTextColor: '#f8fafc'
    primaryBorderColor: '#475569'
    lineColor: '#94a3b8'
    fontFamily: 'system-ui, sans-serif'
    fontSize: '14px'
  flowchart:
    curve: linear
---
flowchart LR
  A[Client] --> B{Auth?}
  B -->|Yes| C[API]
  B -->|No| D[Login]
  C --> E[(Database)]

The frontmatter form (---\nconfig:\n ...) is Mermaid v11's preferred syntax. The older %%{init: {...}}%% directive still works and is what you'll see in most blog posts — pick whichever your renderer is happy with.

When DIY stops being worth the time

Everything above works. I've shipped this exact pipeline.

But the moment you have more than a handful of diagrams, or you want a different look for slides vs. docs vs. PRs, you're maintaining a config file. And every new contributor to the repo needs to know about it. That's where I personally tap out.

Three signals it's time to graduate from hand-tuned themes:

1. You're copy-pasting the same themeVariables block across multiple repos.
2. You want a different look for a slide deck than for the README, but the diagram source stays the same.
3. Someone non-technical on the team needs to make a diagram and you don't want to teach them YAML frontmatter.

---

The shortcut: Paste, pick a theme, export

Beauty Diagram is a web editor for Mermaid, PlantUML, and draw.io. Paste your source, pick from 9 production themes, export SVG or PNG. No themeVariables to maintain. (Disclosure: I work on it.)

→ Open the editor

---

The fastest path is the web editor:

1. Paste your Mermaid source on the left.
2. Pick a theme from nine: classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, atelier. Each one is a complete design language — palette, typography, edge style, node treatment — not just a colour swap.
3. Export SVG (vector for repos) or PNG (standard / high / max quality for slides).
4. Share to get a public hot-linkable URL that updates when the source is edited — drop it into Notion or Linear without re-uploading.

The same renderer is also a CLI if you'd rather automate the README pipeline:

# Render once, ship to your repo
npx @beauty-diagram/cli beautify flow.mmd --theme modern --out flow.svg

# Or render light + dark in one go for the <picture> embed
npx @beauty-diagram/cli beautify flow.mmd --theme modern   --out flow-light.svg
npx @beauty-diagram/cli beautify flow.mmd --theme obsidian --out flow-dark.svg

The CLI exposes the same nine themes (bd themes lists them). It does not expose per-variable overrides — the philosophy is that the theme is the choice; you don't tune a theme, you pick a different one.

Wrap-up

The README-diagram embarrassment problem is fixable in ten minutes. The four fixes, recapped:

• theme: 'base' — only theme that accepts overrides.
• Six themeVariables — primaryColor, primaryTextColor, primaryBorderColor, lineColor, fontFamily, fontSize.
• flowchart.curve: linear — sharp edges for technical diagrams.
• <picture> + prefers-color-scheme — adaptive light/dark, GitHub-native.

Most repos haven't done it because nobody told them where to look. Now you know.

If this was useful, drop a ❤️ and follow — I'm posting weekly on diagrams, docs, and developer ergonomics. Next week: how to embed Mermaid diagrams in Notion (the four working approaches in 2026).

What's the worst-looking diagram in a README you've actually opened a PR against? Drop a link in the comments — I'm collecting examples for a future post.