pydata-sphinx-theme
pydata-sphinx-theme copied to clipboard
Grow our font size and set the content width to have ~80 characters
In the sphinx book theme I was doing a bit of research on good practices for design around web content for readability and accessibility. One thing that I consistently ran into was that you should shoot for 45-75 characters per line, with a max of 80 characters. (though note that Wikipedia seemed to think that a longer width was OK for material that needs to be information dense and "scannable"). They also consistently recommended 16px as the font base size.
Currently, our base font size is 15px, and the max width allows for about 108 characters per line on my screen.
What do people think about these two changes to this theme:
- Set the font base size to 16px to be a bit larger. Here's one ref that recommends this.
- Set the main content max-width such that, at a 16px font size, we have ~90 characters per line. (this is more than the recommended line width, but IMO this is OK since documentation content may have the same "scannability" needs that wikipedia does...I am happy to hear countering opinions on this one!).
What do folks think about this? (cc also @bollwyvl whose perspective on accessibility I have appreciated!)
Some refs:
- Best practices for line width and accessibility and this criterion page from W3C as well
- Visual design guide from accessibility.digital.gov
- wikipedia page discussing their intent to cap the line width
-
the Tufte CSS page
- a max-width of 1400px for all content, and then sets 55% for the main text and 45% for the sidebar text.
- Main content: 55% of full width. Roughly 85 characters per line. Font size 1.4rem
- Margin content: 50% of width of the main content. Roughly 60 characters per line. Font size 1.1rem
- webtypography recommends about 66 characters per line
tagging @hoechenberger who may be interested in this discussion too
Thanks for the research! I am +1 in general. Do you have any idea what max-width this would approximately result in? (the ~90 chars at 16px)
Here's one attempt at doing this w/ minimal changes to the CSS: https://github.com/pydata/pydata-sphinx-theme/pull/428
What do folks think? (feel free to comment there if you like)
Set the font base size to 16px to be a bit larger.
ACTUALLY, we really shouldn't be setting a base font size at all.
From https://css-tricks.com/accessible-font-sizing-explained/#avoid-setting-a-base-font-size (the entire page is a really good read, if you're interested):
My recommendation is to avoid setting font-size on the :root, or
elements in favor of letting the browser’s default size serve as a baseline from where we can cascade our own styles. Since this default is accessible, the content will also be accessible. The WACAG 2.2 working draft states that:When using text without specifying the font size, the smallest font size used on major browsers for unspecified text would be a reasonable size to assume for the font.
Of course, there is an exception to the rule. When using an intricate, thin, or super short x-height font, for example, you might consider bumping up the font size base to get the correct contrast. Remember that the spec defines contrast, not size:
Fonts with extraordinarily thin strokes or unusual features and characteristics that reduce the familiarity of their letter forms are harder to read, especially at lower contrast levels.
In the same manner, a user might change the base font size to fit their needs. A person with low vision would want to choose a larger size, while someone with an excellent vision can go smaller to gain real estate on their screens.
If you skipped the quote above, this is basically for the behaviour when the user changes their default font size in the browser -- accessible pages are supposed to properly accomodate for this user preference (which is also why a bunch of folks recommend using rem as a layout unit).
Beyond that, I am nodding in agreement. :)
@pradyunsg interesting point! That sounds like a good argument to me as well. One thought thought: do we know if the Sphinx "basic" theme sets a base font size? If so then we might need to accommodate for that.
And to be clear, if we set the width based off of em
, then this will roughly scale with the font size so the number of characters per line is the same. Is that right?
One thought thought: do we know if the Sphinx "basic" theme sets a base font size? If so then we might need to accommodate for that.
Nope: https://github.com/sphinx-doc/sphinx/search?l=CSS&q=font-size
Some of the other themes do, but, honestly, I think those are firmly a lost cause at this point.
One thing to consider is that code examples may also want 79 characters or so. But code blocks have extra margin so that in the case of your example the text is 80 chars but the code block clips at 75 chars.
@timhoffm that's a great point. I think we could widen the content window so that we have ~85 characters, and thus code blocks are at ~80 characters.
:+1: And that's assuming people don't use line numbers. But most don't so 80 without line numbers should be good enough.
Made a few tweaks in https://github.com/pydata/pydata-sphinx-theme/pull/428 - would love some feedback there.
It seems to me that this limitation is pretty much set here: https://github.com/pydata/pydata-sphinx-theme/blob/d2c51a65e79642babd1a845cf4fadcfbbcc589ca/src/pydata_sphinx_theme/assets/styles/sections/_article.scss#L18
should we adapt this value or keep it as it is and close this issue ?
I'm happy with either approach - I think our width is fine right now. Do others have opinions?
it seems everyone is happy with the current width (v0.11) I'll close this one for now