Skip to content

fix: load mono font at all weights the CSS renders (avoid faux-bold) #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jowcy wants to merge 2 commits into
base: main
Choose a base branch
from
Open

fix: load mono font at all weights the CSS renders (avoid faux-bold) #60

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
05353d0
fix: load mono font at all weights the CSS renders
jowcy Jun 18, 2026
f26fbbe
fix: default css-patterns.md theme mono to a full-weight font
jowcy Jun 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions plugins/visual-explainer/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,8 @@ Apply these principles to every diagram:

Load via `<link>` in `<head>`. Include a system font fallback in the `font-family` stack for offline resilience.

**Load every weight you use — mono included.** These patterns set the mono font at `400`/`500`/`600`/`700` (uppercase labels, table headers, status pills, the `.opt` cell), so request `wght@400;500;600;700` for the mono family too, not just the body. A weight the CSS uses but the `<link>` omits gets faux-bolded by the browser — smeared, mangled glyphs, ugliest on monospace. (Fragment Mono and Space Mono ship limited weights; pair them only with CSS that stays within what they offer.)

**Color tells a story.** Use CSS custom properties for the full palette. Define at minimum: `--bg`, `--surface`, `--border`, `--text`, `--text-dim`, and 3-5 accent colors. Each accent should have a full and a dim variant (for backgrounds). Name variables semantically when possible (`--pipeline-step` not `--blue-3`). Support both themes.

**Forbidden accent colors:** `#8b5cf6` `#7c3aed` `#a78bfa` (indigo/violet), `#d946ef` (fuchsia), the cyan-magenta-pink combination. These are Tailwind defaults that signal zero design intent.
Expand Down
2 changes: 1 addition & 1 deletion plugins/visual-explainer/references/css-patterns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Always define both light and dark palettes via custom properties. Start with whi
```css
:root {
--font-body: 'Outfit', system-ui, sans-serif;
--font-mono: 'Space Mono', 'SF Mono', Consolas, monospace;
--font-mono: 'JetBrains Mono', 'SF Mono', Consolas, monospace;

--bg: #f8f9fa;
--surface: #ffffff;
Expand Down
10 changes: 7 additions & 3 deletions plugins/visual-explainer/references/libraries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -567,17 +567,19 @@ Always load with `display=swap` for fast rendering. Pick a distinctive pairing
```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">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600;700&family=IBM+Plex+Sans: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-body: 'IBM Plex Sans', system-ui, sans-serif;
--font-mono: 'IBM Plex Mono', 'SF Mono', Consolas, monospace;
}
```

**Load every weight you render — for the mono font too.** The component CSS uses mono at `400`/`500`/`600`/`700` (labels, table headers, status pills, the `.opt` cell), so both families above carry `wght@400;500;600;700`. A weight used in CSS but missing from the `<link>` is synthesized as faux-bold by the browser — mangled, smeared glyphs, worst on monospace. Never load the mono with fewer weights than the body.

**Font pairings** (rotate — never use the same pairing twice in a row):

| Body / Headings | Mono / Labels | Feel | Use for |
Expand All @@ -598,6 +600,8 @@ Define as CSS variables for easy reference:

The first 5 pairings are recommended for most use cases. Vary across consecutive diagrams.

**Weight-limited monos:** Fragment Mono ships `400` only; Space Mono only `400`/`700`. They have no `500`/`600`, so the browser fakes those weights — pick them only for pages whose mono text stays at the weights they offer, otherwise prefer a full-range mono (Fira Code, JetBrains Mono, IBM Plex Mono, Azeret Mono, Geist Mono, Roboto Mono).

### Typography by Content Voice

For prose-heavy pages (documentation, articles, essays), match typography to the content's voice:
Expand Down