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. Ignore the docs' fifty.

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.

Wrap-up

The README-diagram embarrassment problem is fixable in ten minutes. Most repos haven't done it because nobody told them where to look. Now you know.

Next week: how to embed Mermaid diagrams in Notion (the four working approaches in 2026).