Infra: improve text readability and webpage performance

[hugovk]

Space is important for the readability of any kind of text.

Right now the PEP webpages use a Google font with a lot of custom CSS to pull the text in tighter and with less whitespace.

I find the font, small size and tight spacing hard to read (and my eyes aren't getting any younger!). Using default fonts and spacing feels more readable and loads faster. The Google font causes an annoying initial layout shift after it's loaded and the page is re-rendered.

Readability was brought up when we overhauled the PEPs infra as part of PEP 676. But as the other improvements and benefits of migration were so big, it made sense to press ahead without delaying to discuss this further.

One year on, the overhauled infra has been working really well. Let's now improve the readability :)

Original comments

Some of the comments from the original discussion:

This looks really good to me (I like the higher contrast too), although I had to boost the text to 125%. [Barry]

Its certainly something worth considering bumping up the size a notch or two further; while the text size is one tick bigger (16 px vs 15 px on the old PEPs), preferred text sizes on the web have gotten larger over the years as the viewing habits have changed. Also, I’ve noticed that source code renders much larger than the text, which looks kinda awkward, is much larger than the legacy build system and means that a PEP 8 79-character line will not fit on one line. [CAM]

There’s a strong argument to be made for using the so-called system font stack: no extra network requests, no “jump” in rendering as the font loads, more familiar, broad support, up-to-date. [Hugo]

The whitespace (line height + margin) for paragraphs and heading seems… somewhat tight which makes it a bit difficult to read. [Pradyun]

This PR

This PR uses a default "system font stack", and removes a lot of the custom CSS to use default CSS spacing. Let's compare:

• Original: https://peps.python.org/pep-0703/
• PR: https://pep-previews--3132.org.readthedocs.build/pep-0703/

Original

PR

Benefits according to https://systemfontstack.com:

• Fast: No network request, no time to parse a font, no flash of an incorrect font.
• Styles & unicode: System fonts have lots of styles and broad language coverage, unlike many webfonts.
• Familiarity: Web apps feel more native when they use system font faces.

Many sites use a system font stack: GitHub, Stack Overflow, Booking.com, and Weather.com, Bootstrap, Medium, Ghost, PubMed, and the WordPress dashboard. As do the Furo (used on the devguide) and pydata-sphinx-theme themes. See more on the history and rationale.

I looked at sites such as Mozilla's MDN Web Docs (for example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) to compare CSS. Their site is technical writing which I find clearly laid out, with space to breathe. They use a lot of default CSS values.

I've been using this preview build to read recent PEPs and found it much clearer.

In numbers

Running some numbers on Google's Lighthouse tool (ignore the SEO drop on the PR, that's because RtD rightly hides preview builds via robots.txt) shows better performance with the PR:

Original	PR

Note:

• First Contentful Paint ("time at which the first text or image is painted"): 2.8s -> 1.1s
• Largest Contentful Paint ("time at which the largest text or image is painted"): 2.8s -> 1.1s
• Cumulative Layout Shift ("the movement of visible elements within the viewport. Learn more about the cumulative layout shift metric"): 0.012 -> 0
• Speed Index ("how quickly the contents of a page are visibly populated"): 2.8s -> 1.5s

And:

• the 1.8s render-blocking resource (i.e. the Google font) has been eliminated
• the large layout shifts have been removed
• the chained critical requests have dropped from 10 chains to 6
• the request counts have dropped from 13 to 8, and transfer size from 101 KiB to 47 KiB
• long main-thread tasks have dropped from 2 to 1

[AA-Turner]

Initial points on some CSS changes

[pradyunsg]

LGTM!

[EpicWink]

My main issue is with the high contrast of dark mode (look at this site, GitHub.com, as an example of the contrast between background and text that I prefer), but I don't think that's within scope for this PR.

[hugovk]

We changed it from the original greenish #001111 to a greyish #111111 in #2977, but yes, it's out of scope for this PR.

[merwok]

To my eyes both your colours look black! 😄

[AA-Turner]

From the rationale in the PR:

I find the font, small size and tight spacing hard to read (and my eyes aren't getting any younger!). Using default fonts and spacing feels more readable and loads faster.

I agree with this especially on the fonts point. I do have a slight hesitation on whitespace though, perhaps as evidenced by the side-by-side below. I think there is value in some level of information density, and e.g. the new change means that the PEPs table is 'below the fold' as there is significantly more space above and below headings, paragraphs, and lists.

Perhaps there's a compromise to increase our margins and padding somewhat, but not to the level on the right hand side of the screenshot below?

A

[merwok]

Had the same feedback about content density!

[pradyunsg]

Keeping the whitespace reduction around the headers is likely OK. We get most of the benefits from the font change and line height tweaks, and leaving the headings tighter to increase content density seems reasonable to me!

[ambv]

We can circle back about the vertical spacing once there's more eyes on the new style and more feedback. Personally, I like the change in the PR. I think it's big enough to make it easier to follow reading line by line, but small enough to retain sensible information density.