diff --git a/plugins/visual-explainer/SKILL.md b/plugins/visual-explainer/SKILL.md
index e4a2a3b..1b9ada5 100644
--- a/plugins/visual-explainer/SKILL.md
+++ b/plugins/visual-explainer/SKILL.md
@@ -149,6 +149,8 @@ Apply these principles to every diagram:
Load via `` in ``. 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 `` 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.
diff --git a/plugins/visual-explainer/references/css-patterns.md b/plugins/visual-explainer/references/css-patterns.md
index d20e004..df7b9fe 100644
--- a/plugins/visual-explainer/references/css-patterns.md
+++ b/plugins/visual-explainer/references/css-patterns.md
@@ -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;
diff --git a/plugins/visual-explainer/references/libraries.md b/plugins/visual-explainer/references/libraries.md
index cf45a0c..e21dc95 100644
--- a/plugins/visual-explainer/references/libraries.md
+++ b/plugins/visual-explainer/references/libraries.md
@@ -567,17 +567,19 @@ Always load with `display=swap` for fast rendering. Pick a distinctive pairing
```html
-
+
```
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 `` 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 |
@@ -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: