From 05353d0bd9b438f3e876dfc6df864c66c9882562 Mon Sep 17 00:00:00 2001 From: Justin Stander Date: Thu, 18 Jun 2026 10:22:31 -0400 Subject: [PATCH 1/2] fix: load mono font at all weights the CSS renders MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The typography guidance tells authors to pick a pairing and load it via , but never says which weights to request. The component patterns use the mono font at 400/500/600/700 (uppercase labels, table headers, status pills, the .opt cell), so a mono import that only covers a subset (the default example loaded Space Mono at 400;700) leaves the browser to synthesize the missing weights as faux-bold — smeared, mangled glyphs, worst on monospace. - SKILL.md: add a 'load every weight you use, mono included' rule. - libraries.md: make the canonical import example model the rule with symmetric full weights (IBM Plex Sans/Mono), add the same rule, and flag weight-limited monos (Fragment Mono, Space Mono) in the table. --- plugins/visual-explainer/SKILL.md | 2 ++ plugins/visual-explainer/references/libraries.md | 10 +++++++--- 2 files changed, 9 insertions(+), 3 deletions(-) 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/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: From f26fbbe220640e68f6c6b4b405e0e7818ebe44e3 Mon Sep 17 00:00:00 2001 From: Justin Stander Date: Thu, 18 Jun 2026 11:31:31 -0400 Subject: [PATCH 2/2] fix: default css-patterns.md theme mono to a full-weight font The starter Theme Setup block defaulted --font-mono to Space Mono (400/700 only), yet the same reference uses var(--font-mono) at font-weight 600 (e.g. the code-file header label). Copying it verbatim reproduced the faux-bold bug. Switch the default to JetBrains Mono, which ships 400-800. Space Mono remains a valid listed pairing for pages whose mono text stays at 400/700. --- plugins/visual-explainer/references/css-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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;