593 lines
19 KiB
Markdown
593 lines
19 KiB
Markdown
# External Libraries (CDN)
|
||
|
||
Optional CDN libraries for cases where pure CSS/HTML isn't enough. Only include what the diagram actually needs — most diagrams need zero external JS.
|
||
|
||
## Mermaid.js — Diagramming Engine
|
||
|
||
Use for flowcharts, sequence diagrams, ER diagrams, state machines, mind maps, class diagrams, and any diagram where automatic node positioning and edge routing saves effort. Mermaid handles layout — you handle theming.
|
||
|
||
Do NOT use for dashboards — CSS Grid card layouts with Chart.js look better for those. Data tables use `<table>` elements.
|
||
|
||
**CDN:**
|
||
```html
|
||
<script type="module">
|
||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
|
||
|
||
mermaid.initialize({ startOnLoad: true, /* ... */ });
|
||
</script>
|
||
```
|
||
|
||
**With ELK layout** (required for `layout: 'elk'` — it's a separate package, not bundled in core):
|
||
```html
|
||
<script type="module">
|
||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
|
||
import elkLayouts from 'https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk/dist/mermaid-layout-elk.esm.min.mjs';
|
||
|
||
mermaid.registerLayoutLoaders(elkLayouts);
|
||
mermaid.initialize({ startOnLoad: true, layout: 'elk', /* ... */ });
|
||
</script>
|
||
```
|
||
|
||
Without the ELK import and registration, `layout: 'elk'` silently falls back to dagre. Only import ELK when you actually need it — it adds significant bundle weight. Most simple diagrams render fine with dagre.
|
||
|
||
### Deep Theming
|
||
|
||
Always use `theme: 'base'` — it's the only theme where all `themeVariables` are fully customizable. The built-in themes (`default`, `dark`, `forest`, `neutral`) ignore most variable overrides.
|
||
|
||
```html
|
||
<script type="module">
|
||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
|
||
|
||
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
|
||
mermaid.initialize({
|
||
startOnLoad: true,
|
||
theme: 'base',
|
||
look: 'classic',
|
||
themeVariables: {
|
||
// Background and surfaces — teal/slate palette (not violet/indigo!)
|
||
primaryColor: isDark ? '#134e4a' : '#ccfbf1',
|
||
primaryBorderColor: isDark ? '#14b8a6' : '#0d9488',
|
||
primaryTextColor: isDark ? '#f0fdfa' : '#134e4a',
|
||
secondaryColor: isDark ? '#1e293b' : '#f0fdf4',
|
||
secondaryBorderColor: isDark ? '#059669' : '#16a34a',
|
||
secondaryTextColor: isDark ? '#f1f5f9' : '#1e293b',
|
||
tertiaryColor: isDark ? '#27201a' : '#fef3c7',
|
||
tertiaryBorderColor: isDark ? '#d97706' : '#f59e0b',
|
||
tertiaryTextColor: isDark ? '#fef3c7' : '#27201a',
|
||
// Lines and edges
|
||
lineColor: isDark ? '#64748b' : '#94a3b8',
|
||
// Text
|
||
fontSize: '16px',
|
||
fontFamily: 'var(--font-body)',
|
||
// Notes and labels
|
||
noteBkgColor: isDark ? '#1e293b' : '#fefce8',
|
||
noteTextColor: isDark ? '#f1f5f9' : '#1e293b',
|
||
noteBorderColor: isDark ? '#fbbf24' : '#d97706',
|
||
}
|
||
});
|
||
</script>
|
||
```
|
||
|
||
**FORBIDDEN in Mermaid themeVariables:** `#8b5cf6`, `#7c3aed`, `#a78bfa` (indigo/violet), `#d946ef` (fuchsia). Use teal, slate, amber, emerald, or colors from your page's palette.
|
||
|
||
### CSS Overrides on Mermaid SVG
|
||
|
||
Mermaid renders SVG. Override its classes for pixel-perfect control that `themeVariables` can't reach:
|
||
|
||
```css
|
||
/* Container — see html-css-patterns.md "Mermaid Zoom Controls" for the full zoom pattern */
|
||
.mermaid-wrap {
|
||
position: relative;
|
||
background: var(--surface);
|
||
border: 1px solid var(--border);
|
||
border-radius: 12px;
|
||
padding: 24px;
|
||
overflow: auto;
|
||
}
|
||
|
||
/* CRITICAL: Force node/edge text to follow the page's color scheme.
|
||
Without this, themeVariables.primaryTextColor works for DEFAULT nodes,
|
||
but any classDef that sets color: will hardcode a single value that
|
||
breaks in the opposite color scheme. Fix: never set color: in classDef,
|
||
and always include these CSS overrides. */
|
||
.mermaid .nodeLabel { color: var(--text) !important; }
|
||
.mermaid .edgeLabel { color: var(--text-dim) !important; background-color: var(--bg) !important; }
|
||
.mermaid .edgeLabel rect { fill: var(--bg) !important; }
|
||
|
||
/* Node shapes */
|
||
.mermaid .node rect,
|
||
.mermaid .node circle,
|
||
.mermaid .node polygon {
|
||
stroke-width: 1.5px;
|
||
}
|
||
|
||
/* Edge paths */
|
||
.mermaid .edge-pattern-solid {
|
||
stroke-width: 1.5px;
|
||
}
|
||
|
||
/* Edge labels — smaller than node labels for visual hierarchy */
|
||
.mermaid .edgeLabel {
|
||
font-family: var(--font-mono) !important;
|
||
font-size: 13px !important;
|
||
}
|
||
|
||
/* Node labels — 16px default; drop to 14px for complex diagrams (20+ nodes) */
|
||
.mermaid .nodeLabel {
|
||
font-family: var(--font-body) !important;
|
||
font-size: 16px !important;
|
||
}
|
||
|
||
/* Sequence diagram actors */
|
||
.mermaid .actor {
|
||
stroke-width: 1.5px;
|
||
}
|
||
|
||
/* Sequence diagram messages */
|
||
.mermaid .messageText {
|
||
font-family: var(--font-mono) !important;
|
||
font-size: 12px !important;
|
||
}
|
||
|
||
/* ER diagram entities */
|
||
.mermaid .er.entityBox {
|
||
stroke-width: 1.5px;
|
||
}
|
||
|
||
/* Mind map nodes */
|
||
.mermaid .mindmap-node rect {
|
||
stroke-width: 1.5px;
|
||
}
|
||
```
|
||
|
||
### classDef and style Gotchas
|
||
|
||
`classDef` values and per-node `style` directives are static text inside `<pre>` — they can't use CSS variables or JS ternaries. Two rules:
|
||
|
||
1. **Never set `color:` in classDef or per-node `style` directives.** It hardcodes a text color that breaks in the opposite color scheme. Let the CSS overrides above handle text color via `var(--text)`.
|
||
|
||
2. **Use semi-transparent fills (8-digit hex) for node backgrounds.** They layer over whatever Mermaid's base theme background is, producing a tint that works in both light and dark modes. Use `20`–`44` alpha for subtle, `55`–`77` for prominent:
|
||
|
||
```
|
||
classDef highlight fill:#b5761433,stroke:#b57614,stroke-width:2px
|
||
classDef muted fill:#7c6f6411,stroke:#7c6f6444,stroke-width:1px
|
||
```
|
||
|
||
### Node Label Special Characters
|
||
|
||
Mermaid uses certain characters for shape syntax. Node labels containing these characters cause syntax errors unless quoted.
|
||
|
||
**Shape characters to watch:**
|
||
- `[/text/]` — parallelogram
|
||
- `[(text)]` — cylindrical
|
||
- `[[text]]` — subroutine
|
||
- `((text))` — circle
|
||
- `{{text}}` — hexagon
|
||
|
||
**If your node label starts with `/`, `\`, `(`, or `{`, wrap it in quotes:**
|
||
|
||
```
|
||
%% WRONG — syntax error (/ starts parallelogram shape)
|
||
CMD[/gallery command] --> SRV[server]
|
||
|
||
%% RIGHT — quotes escape the special character
|
||
CMD["/gallery command"] --> SRV[server]
|
||
```
|
||
|
||
**Edge labels with special characters also need quotes:**
|
||
|
||
```
|
||
%% WRONG
|
||
UI -->|"Use as Reference"| RET
|
||
|
||
%% RIGHT — use single quotes or no quotes for simple text
|
||
UI -->|Use as Reference| RET
|
||
```
|
||
|
||
Avoid opaque light fills like `fill:#fefce8` — they render as bright boxes in dark mode.
|
||
|
||
### stateDiagram-v2 Label Limitations
|
||
|
||
State diagram transition labels have a strict parser. Avoid:
|
||
- `<br/>` — only works in flowcharts; causes a parse error in state diagrams
|
||
- Parentheses in labels — `cancel()` can confuse the parser
|
||
- Multiple colons — the first `:` is the label delimiter; extra colons may break parsing
|
||
|
||
If you need multi-line labels or special characters, use a `flowchart` instead of `stateDiagram-v2`. Flowcharts support quoted labels (`|"label with: special chars"|`) and `<br/>` for line breaks.
|
||
|
||
### Writing Valid Mermaid
|
||
|
||
Most Mermaid failures come from a few recurring issues.
|
||
|
||
**For multi-line flowchart node labels, use `<br/>` (not `\n`):**
|
||
|
||
```
|
||
%% WRONG — renders literal "\n" in node text
|
||
A["Copilot Backend\n/api + /api/voicebot"] --> B["Redis"]
|
||
|
||
%% RIGHT — renders on two lines
|
||
A["Copilot Backend<br/>/api + /api/voicebot"] --> B["Redis"]
|
||
```
|
||
|
||
**Quote labels with special characters.** Parentheses, colons, commas, brackets, and ampersands break the parser when unquoted:
|
||
|
||
```
|
||
A["handleRequest(ctx)"] --> B["DB: query users"]
|
||
A[handleRequest] --> B[query users]
|
||
```
|
||
|
||
**Keep IDs simple.** Node IDs should be alphanumeric with no spaces or punctuation:
|
||
|
||
```
|
||
userSvc["User Service"] --> authSvc["Auth Service"]
|
||
```
|
||
|
||
**Max 10-12 nodes per Mermaid diagram.** Beyond that, readability collapses even with zoom controls. For complex architectures (15+ elements), use the **hybrid pattern**: a simple 5-8 node Mermaid overview showing module relationships, followed by CSS Grid cards with detailed function lists.
|
||
|
||
```
|
||
subgraph Auth
|
||
login --> validate --> token
|
||
end
|
||
subgraph API
|
||
gateway --> router --> handler
|
||
end
|
||
Auth --> API
|
||
```
|
||
|
||
**Arrow styles for semantic meaning:**
|
||
|
||
| Arrow | Meaning | Use for |
|
||
|-------|---------|---------|
|
||
| `-->` | Solid | Primary flow |
|
||
| `-.->` | Dotted | Optional, async, or fallback paths |
|
||
| `==>` | Thick | Critical or highlighted path |
|
||
| `--x` | Cross | Rejected or blocked |
|
||
| `-->\|label\|` | Labeled | Decision branches, data descriptions |
|
||
|
||
**Sequence diagram messages must be plain text.** Unlike flowchart labels, sequence diagram messages cannot be quoted or escaped. Curly braces `{}`, square brackets `[]`, angle brackets `<>`, and `&` will silently break the parser:
|
||
|
||
```
|
||
%% WRONG — parser chokes on braces, brackets, ampersand
|
||
A->>B: web_search({ queries: [...] })
|
||
B->>B: User removes query 2, keeps 1 & 3
|
||
|
||
%% RIGHT — plain English, no special characters
|
||
A->>B: Call web_search with queries
|
||
B->>B: User removes query 2, keeps 1 and 3
|
||
```
|
||
|
||
### Layout Direction: TD vs LR
|
||
|
||
`flowchart LR` (left-to-right) spreads horizontally. With many nodes, Mermaid scales everything down to fit the width, making text unreadable. `flowchart TD` (top-down) is almost always better.
|
||
|
||
| Direction | Use when | Avoid when |
|
||
|-----------|----------|------------|
|
||
| `TD` (top-down) | Complex diagrams, 5+ nodes, hierarchies | Simple A→B→C linear flows |
|
||
| `LR` (left-to-right) | Simple linear flows, 3-4 nodes | Complex graphs, many branches |
|
||
|
||
**Rule of thumb:** If the diagram has more than one row of nodes or any branching, use `TD`.
|
||
|
||
### Diagram Type Examples
|
||
|
||
**Flowchart with decisions:**
|
||
```html
|
||
<pre class="mermaid">
|
||
graph TD
|
||
A[Request] --> B{Authenticated?}
|
||
B -->|Yes| C[Load Dashboard]
|
||
B -->|No| D[Login Page]
|
||
D --> E[Submit Credentials]
|
||
E --> B
|
||
C --> F{Role?}
|
||
F -->|Admin| G[Admin Panel]
|
||
F -->|User| H[User Dashboard]
|
||
</pre>
|
||
```
|
||
|
||
**Sequence diagram:**
|
||
```html
|
||
<pre class="mermaid">
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant G as Gateway
|
||
participant S as Service
|
||
participant D as Database
|
||
C->>G: POST /api/data
|
||
G->>G: Validate JWT
|
||
G->>S: Forward request
|
||
S->>D: Query
|
||
D-->>S: Results
|
||
S-->>G: Response
|
||
G-->>C: 200 OK
|
||
</pre>
|
||
```
|
||
|
||
**ER diagram:**
|
||
```html
|
||
<pre class="mermaid">
|
||
erDiagram
|
||
USERS ||--o{ ORDERS : places
|
||
ORDERS ||--|{ LINE_ITEMS : contains
|
||
LINE_ITEMS }o--|| PRODUCTS : references
|
||
USERS { string email PK }
|
||
ORDERS { int id PK }
|
||
LINE_ITEMS { int quantity }
|
||
PRODUCTS { string name }
|
||
</pre>
|
||
```
|
||
|
||
**State diagram:**
|
||
```html
|
||
<pre class="mermaid">
|
||
stateDiagram-v2
|
||
[*] --> Draft
|
||
Draft --> Review : submit
|
||
Review --> Approved : approve
|
||
Review --> Draft : request_changes
|
||
Approved --> Published : publish
|
||
Published --> Archived : archive
|
||
Archived --> [*]
|
||
</pre>
|
||
```
|
||
|
||
**Mind map:**
|
||
```html
|
||
<pre class="mermaid">
|
||
mindmap
|
||
root((Project))
|
||
Frontend
|
||
React
|
||
Next.js
|
||
Tailwind
|
||
Backend
|
||
Node.js
|
||
PostgreSQL
|
||
Redis
|
||
Infrastructure
|
||
AWS
|
||
Docker
|
||
Terraform
|
||
</pre>
|
||
```
|
||
|
||
**Class diagram:**
|
||
```html
|
||
<pre class="mermaid">
|
||
classDiagram
|
||
class User {
|
||
+string email
|
||
+string name
|
||
+login()
|
||
+logout()
|
||
}
|
||
class Order {
|
||
+int id
|
||
+decimal total
|
||
+submit()
|
||
}
|
||
class Product {
|
||
+string name
|
||
+decimal price
|
||
}
|
||
User "1" --> "*" Order : places
|
||
Order "*" --> "*" Product : contains
|
||
</pre>
|
||
```
|
||
|
||
**C4 architecture (flowchart-as-C4):**
|
||
```html
|
||
<pre class="mermaid">
|
||
graph TD
|
||
user("User<br/><small>Browser client</small>")
|
||
subgraph boundary["Web Platform"]
|
||
app["Web App<br/><small>Node.js</small>"]
|
||
db[("Database<br/><small>PostgreSQL</small>")]
|
||
end
|
||
email["Email Service"]:::ext
|
||
payment["Payment Gateway"]:::ext
|
||
user -->|"HTTPS"| app
|
||
app -->|"SQL"| db
|
||
app -->|"SMTP"| email
|
||
app -->|"API"| payment
|
||
classDef ext fill:none,stroke-dasharray:5 5
|
||
</pre>
|
||
```
|
||
|
||
Do NOT use native `C4Context` / `C4Container` syntax — it hardcodes sharp corners, its own font, and inline colors that ignore `themeVariables`. Use `graph TD` + `subgraph` for C4 boundaries instead.
|
||
|
||
### Which Mermaid Diagram Type?
|
||
|
||
| You want to show... | Use | Syntax keyword |
|
||
|---|---|---|
|
||
| Process flow, decisions, pipelines | Flowchart | `graph TD` / `graph LR` |
|
||
| Request/response, API calls, temporal interactions | Sequence diagram | `sequenceDiagram` |
|
||
| Database tables and relationships | ER diagram | `erDiagram` |
|
||
| OOP classes, domain models with methods | Class diagram | `classDiagram` |
|
||
| System architecture at multiple zoom levels | C4 diagram | `graph TD` + `subgraph` |
|
||
| State transitions, lifecycles | State diagram | `stateDiagram-v2` |
|
||
| Hierarchical breakdowns, brainstorms | Mind map | `mindmap` |
|
||
|
||
### Dark Mode Handling
|
||
|
||
Mermaid initializes once — it can't reactively switch themes. Read the preference at load time inside your `<script type="module">`:
|
||
|
||
```javascript
|
||
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
|
||
// Use isDark to pick light or dark values in themeVariables
|
||
```
|
||
|
||
The CSS overrides on the container (`.mermaid-wrap`) and page will still respond to `prefers-color-scheme` normally — only the Mermaid SVG internals are static.
|
||
|
||
---
|
||
|
||
## Chart.js — Data Visualizations
|
||
|
||
Use for bar charts, line charts, pie/doughnut charts, radar charts, and other data-driven visualizations in dashboard-type diagrams. Overkill for static numbers — use pure SVG/CSS for simple progress bars and sparklines.
|
||
|
||
```html
|
||
<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
|
||
|
||
<canvas id="myChart" width="600" height="300"></canvas>
|
||
|
||
<script>
|
||
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
|
||
const textColor = isDark ? '#8b949e' : '#6b7280';
|
||
const gridColor = isDark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.06)';
|
||
const fontFamily = getComputedStyle(document.documentElement)
|
||
.getPropertyValue('--font-body').trim() || 'system-ui, sans-serif';
|
||
|
||
new Chart(document.getElementById('myChart'), {
|
||
type: 'bar',
|
||
data: {
|
||
labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
|
||
datasets: [{
|
||
label: 'Feedback Items',
|
||
data: [45, 62, 78, 91, 120],
|
||
backgroundColor: isDark ? 'rgba(129, 140, 248, 0.6)' : 'rgba(79, 70, 229, 0.6)',
|
||
borderColor: isDark ? '#818cf8' : '#4f46e5',
|
||
borderWidth: 1,
|
||
borderRadius: 4,
|
||
}]
|
||
},
|
||
options: {
|
||
responsive: true,
|
||
plugins: {
|
||
legend: { labels: { color: textColor, font: { family: fontFamily } } },
|
||
},
|
||
scales: {
|
||
x: { ticks: { color: textColor, font: { family: fontFamily } }, grid: { color: gridColor } },
|
||
y: { ticks: { color: textColor, font: { family: fontFamily } }, grid: { color: gridColor } },
|
||
}
|
||
}
|
||
});
|
||
</script>
|
||
```
|
||
|
||
Wrap the canvas in a styled container:
|
||
```css
|
||
.chart-container {
|
||
background: var(--surface);
|
||
border: 1px solid var(--border);
|
||
border-radius: 10px;
|
||
padding: 20px;
|
||
position: relative;
|
||
}
|
||
|
||
.chart-container canvas {
|
||
max-height: 300px;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## anime.js — Orchestrated Animations
|
||
|
||
Use when a diagram has 10+ elements and you want a choreographed entrance sequence (staggered reveals, path drawing, count-up numbers). For simpler diagrams, CSS `animation-delay` staggering is sufficient.
|
||
|
||
```html
|
||
<script src="https://cdn.jsdelivr.net/npm/animejs@3.2.2/lib/anime.min.js"></script>
|
||
|
||
<script>
|
||
const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
|
||
|
||
if (!prefersReduced) {
|
||
anime({
|
||
targets: '.ve-card',
|
||
opacity: [0, 1],
|
||
translateY: [20, 0],
|
||
delay: anime.stagger(80, { start: 200 }),
|
||
easing: 'easeOutCubic',
|
||
duration: 500,
|
||
});
|
||
|
||
anime({
|
||
targets: '.connector path',
|
||
strokeDashoffset: [anime.setDashoffset, 0],
|
||
easing: 'easeInOutCubic',
|
||
duration: 800,
|
||
delay: anime.stagger(150, { start: 600 }),
|
||
});
|
||
|
||
document.querySelectorAll('[data-count]').forEach(el => {
|
||
anime({
|
||
targets: { val: 0 },
|
||
val: parseInt(el.dataset.count),
|
||
round: 1,
|
||
duration: 1200,
|
||
delay: 400,
|
||
easing: 'easeOutExpo',
|
||
update: (anim) => { el.textContent = anim.animations[0].currentValue; }
|
||
});
|
||
});
|
||
}
|
||
</script>
|
||
```
|
||
|
||
When using anime.js, set initial opacity to 0 in CSS so elements don't flash before the animation:
|
||
```css
|
||
.ve-card { opacity: 0; }
|
||
|
||
@media (prefers-reduced-motion: reduce) {
|
||
.ve-card { opacity: 1 !important; }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Google Fonts — Typography
|
||
|
||
Always load with `display=swap` for fast rendering. Pick a distinctive pairing — body + mono at minimum, optionally a display font for the title.
|
||
|
||
**FORBIDDEN as `--font-body` (AI slop signals):**
|
||
- Inter — the single most overused AI default font
|
||
- Roboto — generic Android/Google default
|
||
- Arial, Helvetica — system defaults with no character
|
||
- system-ui alone without a named font — signals zero design intent
|
||
|
||
```html
|
||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||
<link href="https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&family=Outfit:wght@400;500;600;700&display=swap" rel="stylesheet">
|
||
```
|
||
|
||
Define as CSS variables for easy reference:
|
||
```css
|
||
:root {
|
||
--font-body: 'Outfit', system-ui, sans-serif;
|
||
--font-mono: 'Space Mono', 'SF Mono', Consolas, monospace;
|
||
}
|
||
```
|
||
|
||
**Font pairings** (rotate — never use the same pairing twice in a row):
|
||
|
||
| Body / Headings | Mono / Labels | Feel | Use for |
|
||
|---|---|---|---|
|
||
| DM Sans | Fira Code | Friendly, developer | Blueprint, technical docs |
|
||
| Instrument Serif | JetBrains Mono | Editorial, refined | Plan reviews, decision logs |
|
||
| IBM Plex Sans | IBM Plex Mono | Reliable, readable | Architecture diagrams |
|
||
| Bricolage Grotesque | Fragment Mono | Bold, characterful | Data tables, dashboards |
|
||
| Plus Jakarta Sans | Azeret Mono | Rounded, approachable | Status reports, audits |
|
||
| Outfit | Space Mono | Clean geometric, modern | Flowcharts, pipelines |
|
||
| Sora | IBM Plex Mono | Technical, precise | ER diagrams, schemas |
|
||
| Crimson Pro | Noto Sans Mono | Scholarly, serious | RFC reviews, specs |
|
||
| Fraunces | Source Code Pro | Warm, distinctive | Project recaps |
|
||
| Geist | Geist Mono | Vercel-inspired, sharp | Modern API docs |
|
||
| Red Hat Display | Red Hat Mono | Cohesive family | System overviews |
|
||
| Libre Franklin | Inconsolata | Classic, reliable | Data-dense tables |
|
||
| Playfair Display | Roboto Mono | Elegant contrast | Executive summaries |
|
||
|
||
The first 5 pairings are recommended for most use cases. Vary across consecutive diagrams.
|
||
|
||
### Typography by Content Voice
|
||
|
||
For prose-heavy pages (documentation, articles, essays), match typography to the content's voice:
|
||
|
||
| Voice | Fonts | Best For |
|
||
|-------|-------|----------|
|
||
| **Literary / Thoughtful** | Literata, Lora, Newsreader, Merriweather | Essays, personal posts, long-form articles |
|
||
| **Technical / Precise** | IBM Plex Sans + Mono, Geist + Geist Mono, Source family | Documentation, READMEs, API references |
|
||
| **Bold / Contemporary** | Bricolage Grotesque, Space Grotesk, DM Sans | Product pages, feature announcements |
|
||
| **Minimal / Focused** | Source Serif 4 + Source Sans 3, Karla + Inconsolata | Tutorials, how-tos, focused reading |
|
||
|
||
**Literata** deserves special mention — it has optical sizing designed specifically for screen reading. Google's answer to Georgia, but modernized.
|