Improve the font clarity of sidebar tab button styles for better accessibility

[hichemfantar]

Removing the inherited font-weight from sidebar button styles improves the visual clarity and overall appearance of the sidebar.

this is an improvement in terms of accessibility as the font can be too thin to read on screens without good contrast levels and pixelating.

research:
https://accessibility.psu.edu/legibility/lightweight/

https://www.digitala11y.com/choosing-accessible-fonts-enhancing-readability-and-inclusivity/#:~:text=Font%20Weight,-Let's%20start%20with&text=But%20be%20cautious%3A%20overly%20bold,fonts%20can%20be%20problematic%20too.

fix applied to tabs

fix applied to everything

tldr: avoid light weight fonts as much as possible

[github-actions]

📦 Docs artifacts are ready: https://github.com/elixir-lang/ex_doc/actions/runs/12895186263/artifacts/2464011708

[hichemfantar]

@josevalim i found the offending code https://github.com/hichemfantar/elixir-ex_doc-fork/blob/68429705e85cd39b579dafc68c1344b2f93f676f/assets/css/sidebar.css#L17-L20

it only looks very thin on macos because of this code.

also removing this https://github.com/hichemfantar/elixir-ex_doc-fork/blob/68429705e85cd39b579dafc68c1344b2f93f676f/assets/css/sidebar.css#L6 makes everything consistent across all OSes

tested on windows, macos, and ubuntu

[DavidOliver]

I think the tabs look fine in the heavier weight you have.

For the second-level of links in the sidebar (Features, Usage, etc.), the text feels just a little too heavy to me in your fixed screenshot. Is there an in-between weight available for this level of links?

[hichemfantar]

There's no in between weight from my testing. I believe we should add some extra vertical spacing and that will fix the issue because there's not enough space between the list items.

also what you're seeing here is actually what it already looks like in windows and linux because of this https://github.com/hichemfantar/elixir-ex_doc-fork/blob/68429705e85cd39b579dafc68c1344b2f93f676f/assets/css/sidebar.css#L17-L20
the note /* Non-Apple OSes render small light type too thinly */ doesn't seem true in my case. in fact, it's the opposite, it's rendered too thinly on macos because of the conditional style. the note could be related to bad user settings.

the cause for the note is https://github.com/hichemfantar/elixir-ex_doc-fork/blob/68429705e85cd39b579dafc68c1344b2f93f676f/assets/css/sidebar.css#L6 i believe

[DavidOliver]

There's no in between weight from my testing.

Ah, that's a shame. Let's see what others think about the weight.

what you're seeing here is actually what it already looks like in windows and linux

Here's what the live ExDoc docs looks like for me in both Firefox and Vivaldi in Linux:

I believe it's usually the case that MacOS renders heavier than others (see, for example, info on font dilation here), especially Windows. We previously attempted to counter this. It sounds like we're seeing different results for some reason.

I haven't looked into it for a while and I have to get back to other things for the next few hours, but I suppose it would be great if we could tell Macs to render like the others and then choose weights for all accordingly, if that didn't negatively affect Mac users.

[hichemfantar]

if macos makes a decision like that then that means macos users are used to it rendering like that.
I'm actually an affected user because of this.

in conclusion, we shouldn't override native font behavior, let each system render their fonts how the system is designed to render them.

[DavidOliver]

Yes, I agree that things don't have to look the same across devices. I think in this case we felt either Mac or non-Mac users were getting a sufficiently poor weight, hence our attempt to close the gap.

Anyway, I should be able to test those browsers in Linux and browsers in Windows as necessary later if it's helpful, once others have confirmed which weight(s) they're happy to aim for.

[hichemfantar]

awesome, i pushed the changes we talked so you could test what it looks like when the font weight is consistent across all OSes.

nothing should change in windows and linux, this change should only affect macos

[josevalim]

I am using macos and the font-weight is definitely too heavy for me. And that's definitely not something I am "used to".

[hichemfantar]

It's the opposite for me, but don't forget that the thin font (which is already uncomfortably thin imo) may become too thin on other apple devices.
this is an accessibility concern that's best left to the os and browser to handle natively

[hichemfantar]

also it may feel a bit heavy for you because there may not be enough vertical spacing between elements

[hichemfantar]

A slightly bold font is better than a light font because of the concerns and research mentioned in the original issue

[hichemfantar]

pasting this here because it's related to this discussion

#2043 (comment)

Notice how vite and the new font weight are pretty much identical (further proof (besides the research i linked) it's the more correct weight to use because vitepress has a large team behind with lots of experience in building great web experiences)

they also use the same weight in the sidebar

[hichemfantar]

even docusaurus uses the same font weight as vitepress which is 500

[josevalim]

Notice how vite and the new font weight are pretty much identical (further proof (besides the research i linked) it's the more correct weight to use because vitepress has a large team behind with lots of experience in building great web experiences)

Right, but we cannot look at things in a vacuum. Both use a lighter font color too, which helps balance things out, but at the same both Vitepress and Docusaurus gets only a AA check on their contrast.

[josevalim]

In other words, maybe we can explore this change alongside some changes to the color, to balance out the heaviness.

[josevalim]

Here is an example from Gmail. The Gmail font is a bit thicker than our current one, but it is definitely thinner than the one proposed here. And the Gmail team has definitely spent enough time and resources on UX. So I don't buy the argument that font-weight 500 is the recommended value, especially because there is variation between fonts and we cannot look at those things in isolation.

Another option is to choose another font, that either has a slightly heavier Light mode or a slightly lighter Normal mode. It seems Lato is neither here nor there.

[hichemfantar]

Funny you should mention gmail because i also find the gmail font weight to be a bit too thin haha. It's also know on multiple instances that google doesn't follow the guidelines they themselves set.

Inter is a really well battle tested font (vitepress uses it) or we can simply rely on native system fonts (that's what docusaurus does)?
native systems font are best because you don't have to wait for the font to load, they're pretty reliable, and the user is used to them.

[josevalim]

I tried a couple founds and Nunito Sans seems to be the least disruptive. It is quite similar but thicker. Here are them side by side:

But that's keeping the current font weight. Increase the weight, once again, make it too heavy for me.

[hichemfantar]

Let me try with system fonts because that may just solve all of our problems

[josevalim]

We moved most of it to system fonts in the past but we couldn't find a reasonable looking one for the sidebar. Let us know if you have better luck.

[hichemfantar]

#2054 my attempt at system fonts which looks pretty consistent imo

[josevalim]

Closing in favor of #2053.