Skip to content

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

Open
jowcy wants to merge 2 commits into
nicobailon:mainfrom
jowcy:justin/fix-mono-font-weights
Open

fix: load mono font at all weights the CSS renders (avoid faux-bold)#60
jowcy wants to merge 2 commits into
nicobailon:mainfrom
jowcy:justin/fix-mono-font-weights

Conversation

@jowcy

@jowcy jowcy commented Jun 18, 2026

Copy link
Copy Markdown

Problem

The typography guidance tells authors to pick a font pairing and load it via <link>, but never specifies which weights to request. The component patterns throughout the skill use the mono font at 400/500/600/700 (uppercase labels, table headers, status pills, the .opt cell) — yet several canonical examples ship a weight-limited mono:

  • references/libraries.md loaded Space Mono at only 400;700.
  • references/css-patterns.md's copy-paste "Theme Setup" block defaulted --font-mono to Space Mono (400/700 only), while the same file uses var(--font-mono) at font-weight: 600 (e.g. the code-file header label).

When a weight is used in CSS but absent from the <link>, the browser synthesizes it as faux-bold: smeared, lopsided glyphs — worst on monospace.

Real-world symptom: a generated page loaded Fira Code:wght@400;500 but used it at font-weight: 600/700, rendering mangled label text.

Changes

  • SKILL.md — add a "load every weight you use — mono included" rule next to the pairing guidance, with the faux-bold warning.
  • references/libraries.md
    • Make the canonical import example model the rule (symmetric full weights, swapping the weight-limited Space Mono illustration for IBM Plex Sans/Mono, which ship 400;500;600;700).
    • Add the same rule below the example.
    • Flag weight-limited monos (Fragment Mono = 400 only, Space Mono = 400/700) in the pairing table.
  • references/css-patterns.md — switch the starter theme's default --font-mono from Space Mono to JetBrains Mono (full weight range), so the most-copied reference doesn't ship the faux-bold bug out of the box.

Notes

  • Docs/guidance only — no template behavior changes. The bundled templates were already self-consistent (each loads every weight it uses, including mermaid-flowchart.html, which renders Fragment Mono only at 400).
  • Space Mono and Fragment Mono remain valid listed pairings — they're just no longer defaults, and the new caveat steers them toward pages that stay within the weights they offer.
  • Keeps the heavy-mono aesthetic intact by loading the weights the CSS renders, rather than weakening the CSS.

jowcy added 2 commits June 18, 2026 10:22
The typography guidance tells authors to pick a pairing and load it via
<link>, 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.
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant