docs: propose modernizing user guide typography

[paulbalandan]

Description

Note on scope: This is a discussion/RFC-style PR, not a drop-in merge. The user guide's font is tied to CodeIgniter's brand typography — Raleway is also in active use on codeigniter.com — so landing this in isolation would create a visible divergence between the marketing site and the docs. The purpose here is to make the case, propose a coordinated change, and open the conversation. A sibling PR will be drafted against codeigniter4projects/website so both surfaces can move together. If the project prefers to keep Raleway for brand reasons, there is a scoped-down Plan B near the bottom that can ship independently.

Background

The user guide currently bundles Raleway locally (6 @font-face blocks in user_guide_src/source/_static/css/citheme.css, and 30 font files totaling ~1.1 MB under user_guide_src/source/_static/fonts/Raleway/). That setup dates to February 2020, commit a57d141 ("Change font to 'Raleway' (CI's 'official' font)"), followed by a short stabilization series ending with 80ec0c0. It has not been revisited in ~6 years.

Verified that codeigniter4projects/website currently ships the identical Raleway bundle in public/assets/css/ci-theme.css — same 6 variants (200/400/700 × normal/italic), same legacy formats. So brand alignment between the docs and the marketing site today is real and deliberate. Any serious proposal to change the user guide font therefore needs to either (a) keep it aligned with the website, or (b) change both together.

Why re-open the question

Three reasons to revisit the 2020 choice, independent of which font ends up winning:

1. Raleway is a display typeface — not optimized for long-form reading. Designed by Matt McInerney in 2010 as a single ExtraLight weight for headlines, later expanded into a family. The bundled 200 weight in particular renders thin and low-contrast on modern high-DPI displays at body sizes. Readers going through long API reference pages aren't getting the best legibility we could offer.
2. The local bundle ships formats for browsers that no longer exist. The 30 files include .eot (IE 6–9 — Microsoft retired IE in June 2022) and .svg fonts (pre-iOS 4.2 Safari). Modern browsers all use .woff2. The legacy formats are dead weight in every clone, CI job, and release.
3. Code blocks have no intentional font. The RTD theme falls back to SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", ..., so readers on macOS, Windows, and Linux each see a different monospace — no consistency, no programming ligatures, no deliberate choice. This is independent of the brand-font question and is probably the single biggest readability win available.

Proposal (full)

Body + headings: Inter — a neutral sans-serif designed specifically for UI and on-screen reading by Rasmus Andersson (ex-Figma, ex-Spotify), SIL OFL-licensed. It's become the de facto choice for modern technical documentation (Tailwind, Vercel, Laravel, GitHub's design system). Much better legibility at body sizes than a display sans like Raleway. Reasonable alternatives worth discussing: Source Sans 3, IBM Plex Sans, Work Sans. The point isn't "Inter is the only right answer," it's "a purpose-built reading sans fits the docs better than a display sans."

Code: JetBrains Mono — with OpenType calt ligatures enabled (renders =>, !=, ->, <=, >=, ===, !== as single glyphs in PHP samples). SIL OFL. Alternatives: Fira Code, Cascadia Code, Source Code Pro.

Delivery: self-hosted .woff2 (updated per @neznaika0's review feedback — previously proposed via Google Fonts, then Bunny Fonts CDN). 10 latin-subset .woff2 files totaling ~252 KB, under user_guide_src/source/_static/fonts/Inter/ (6 variants) and user_guide_src/source/_static/fonts/JetBrainsMono/ (4 variants). Each @font-face declares unicode-range for the latin subset so glyphs outside the range fall back cleanly to system fonts, and uses font-display: swap so text paints immediately with the fallback stack rather than blocking. Still a significant reduction from the original Raleway bundle (~1.1 MB across 30 legacy-format files) despite gaining a monospace family.

Coordinated change

For consistency with the marketing site, a matching PR would be opened at codeigniter4projects/website touching public/assets/css/ci-theme.css and public/assets/fonts/. I'll open that once there's signal here — no point in a two-repo change if the answer on this one is "no."

Plan B (if a full brand change isn't on the table)

If the CodeIgniter Foundation wants to preserve Raleway for brand consistency, I'd narrow this PR to the code-block-only improvements:

• Keep Raleway for body and headings exactly as today.
• Add JetBrains Mono (or Fira Code) for <pre> and <code> self-hosted as .woff2 — no brand conflict, high dev-facing value.
• Add high-specificity monospace selectors (.rst-content div[class^=highlight] pre, .rst-content pre.literal-block, .rst-content .linenodiv pre) so the chosen font wins the cascade over the RTD theme's fallbacks.
• Optionally remove the legacy .eot and .svg files from the Raleway bundle (~400 KB cleanup for dead-browser formats, no visible change on any supported browser).

Plan B is mergeable on its own merits and doesn't depend on brand-level decisions. Happy to split it out as a separate, smaller PR if preferred.

What this PR currently changes (full-proposal version)

• user_guide_src/source/_static/css/citheme.css
  • Replaced 6 local Raleway @font-face blocks with 10 local @font-face blocks for Inter (6 variants) + JetBrains Mono (4 variants), sourcing .woff2 only (no legacy .eot/.svg/.ttf/.woff). Each block declares unicode-range for the latin subset and font-display: swap.
  • Updated body / p / legend / h1–h6 font-family from "Raleway", ... to "Inter", ....
  • Added a monospace rule targeting RTD's high-specificity selectors so JetBrains Mono wins the cascade on syntax-highlighted blocks.
  • Added font-feature-settings: "calt" 1; to make ligature intent explicit.
• user_guide_src/source/_static/fonts/Raleway/ — deleted (30 files, ~1.1 MB).
• user_guide_src/source/_static/fonts/Inter/ — added (6 .woff2 files, ~148 KB).
• user_guide_src/source/_static/fonts/JetBrainsMono/ — added (4 .woff2 files, ~88 KB).

Questions for maintainers

1. Is Raleway still considered the project's brand typeface? If yes, is the Foundation open to revisiting that? (Decisive question — everything downstream hangs on it.)
2. Is there a preference for self-hosted fonts over a Google Fonts CDN dependency? Addressed — self-hosted after @neznaika0 raised CDN-reachability concerns in review. Files ship as latin-subset .woff2 under user_guide_src/source/_static/fonts/.
3. Would a coordinated PR at codeigniter4projects/website be welcome, or is that repo's typography considered separate?
4. If the full change isn't on the table, is Plan B (code font only) acceptable as a standalone PR?

---

_{Drafted with assistance from Claude (Anthropic). All factual claims verified against primary sources.}

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[paulbalandan]

How this change would look like:

Sidebar:

Content:

Code:

[michalsn]

I think the proposal is reasonable, and I'm not against the changes. The readability arguments make sense, and using a deliberate monospace font for code blocks is a clear improvement.

It also raises the bigger docs question. We already started the move from Sphinx to MkDocs in codeigniter4/docs-update, and maybe that is the more worthwhile direction to pursue. It would require more time, work, and some compromises, since Markdown does not provide PHP class descriptions in the same way. We would need to either drop that, transform it somehow, or handle API-style docs separately. I would be interested to hear your take on that as well.

The same goes for the website. If we are revisiting typography and presentation anyway, a broader refresh might make more sense than just a font change. With current AI tools, that kind of work feels much more within reach than it used to be.

We are also a bit blocked on website updates right now. A new site deploy expects PHP 8.2+, while the forum is still on an older version, so there are some infrastructure issues to sort out before taking on anything bigger. Maybe this is also a good moment to consider a static site generator instead of using the framework for the website. That could make deployment much easier, including via GitHub Pages or something similar.

Overall, I'm not against this PR. If we make the change, I would lean toward the full version over Plan B. But the larger proposal probably fits better into a wider conversation about the docs direction and the website.

Answers:

1. I'm not sure whether Raleway should be treated as fixed brand typography at this point.
2. I don't have a strong preference myself, CDN sounds fine, although I would consider https://fonts.bunny.net instead.
3. I think a coordinated PR would make sense if we want to keep both surfaces aligned.
4. Yes.

[paulbalandan]

Thanks @michalsn, really helpful feedback. I've updated the PR body and pushed a commit switching the @import URL to Bunny Fonts.

On codeigniter4/docs-update I wasn't even aware that the repo existed, so I went and looked. The work is real (.rst → MD tooling, toctree/code-block/link handling) but last activity was October 2025, about 7 months ago. The PHP class description problem you flagged is the genuine blocker. One observation: the tooling there is currently procedural-style (top-level scripts, require_once, no classes) — happy to look at converting it to OOP in a framework-native style once time permits, if that's useful for picking the work back up. My take otherwise: treat the migration as a separate track and don't gate font work on it — the monospace/ligature win is immediate, and font-family ports over in one line if/when MkDocs lands.

On the API-docs question specifically: two-tier docs — MkDocs-Material for handwritten guides, with an auto-generated API reference using phpDocumentor linked from the sidebar as a separate section. Sidesteps the Markdown-can't-replicate-phpdomain problem by not trying to. Happy to open an issue on docs-update to explore it properly; doesn't belong here.

On the website & static SSG — agree. The website ↔ framework ↔ forum PHP-version coupling is tax with no upside, and static (Hugo/11ty/Astro) fits a marketing site better. Separate conversation though, so I'll open the coordinated codeigniter4projects/website font PR against current deployment; the font pieces port cleanly into any later refresh.

On Raleway as brand typography — appreciate the response; that's what I needed to propose the full version over Plan B.

Next from my side:

1. Bunny Fonts adopted (CSS commit pushed; PR body updated) - done.
2. Will open the sibling codeigniter4projects/website PR once there's directional consensus here.

[michalsn]

About codeigniter4/docs-update, I don't think we have to ditch the procedural code - this is mostly a one-time conversion, so refactoring sounds a bit like a waste of time. The actual challenge is to actually take a look at everything and see if there are still any gaps and what needs to be improved to sustain the readability of the user guide. Overall, if the result looks good enough.