Very low contrast in sidebar

[cdegroot]

This is a screenshot from Linux/KDE/Firefox. It might be the font rendering, but that contrast is low to the point of it being unreadable to me (some details here).

I've experimented with a styling browser plugin and making things just white-on- with making the currently highlighted entries bolder works very nicely - a much better contrast than the marginal current one (I think it doesn't hit AA) and still looks pleasant.

Ideally, light mode would be "actually light mode" with a dark-on-light sidebar, but that would be a large change. I'm willing to come up with a color scheme if this would be an acceptable solution although I'm not a designer and, frankly, given that this is code documentation and not a marketing/PR site, I'd end up with lots of shades of grey suitably spaced apart and call it a day :)

(I usually like to submit PRs over Issues but this probably warrants some discussion before making changes).

[josevalim]

There is definitely a font issue, so I would try to address that first. Any ideas why the font rendering is so faint on Linux?

[cdegroot]

Well... yes and no for the font issue, of course. If you design with a low-ish contrast and a very thin font, you're walking near the edge and you shouldn't be surprised if you stumble and fall over it :-). I'm suggesting to move well away from the ledge instead of doing a deep dive into font rendering issues.

I'm not sure whether it's the font, the copy of the webfont in particular, the Linux/X11 rendering engine, or the settings on my machines (I'm seeing this both on my laptop, a FHD 15" panel, and my desktop, a 4K 32" panel). I do know that I can work with pretty much everything else and that a true light mode would fix this cross-platform and increase ex_doc's accessibility score. I did try changing to a locally installed font on my main box (Lucida Sans, I think), and that got indeed rendered a bit better.

Anyway, back to what I think is the better solution; not suggesting this is any good, but I did some tinkering using a styling browser plugin, and something like

has a minimum contrast of 16.25:1 but still a decent separation between the various elements (contrast to the 5.07 of the purple-on-black in the current scheme that does just barely make the mark). It also is a "true light" scheme - I think that these "mixed" themes are not nice on the eyes regardless of your light-or-dark preferences.

[josevalim]

The problem is that we would effectively be maintaining three themes per ExDoc language, which adds a burden and at the moment gives 6 combinations, and none of us are designers. So I would prefer first to exhaust all other options: such as increasing the natural contrast, fix the font, and everything else before adding a new theme.

there is also an argument to make it better by default within the current design/theme rather than behind an option many may not find.

[cdegroot]

I'd indeed argue for just two themes: a true dark and a true light theme. Currently, ex_doc has a true dark and a "someone wanted a light theme but we didn't have the time to do the sidebar as well so this mix of light and dark is what it is" theme :)

[josevalim]

That’s inaccurate. The page and sidebar were actually designed with proper time and focus by a UI specialist with accessibility concerns in mind.

The screenshot that you posted means the sidebar is barely usable to you. It is clearly not meant to work like that. So I would consider fixing it. Let’s please focus on that (this is the third comment asking as much).

[cdegroot]

(On mobile, last reply for today - EST - fully yours tomorrow)

Well, that would mean changing the font then? I’ve gone through most combinations of antialiasing, hinting, and subpixel rendering but these hardly make a difference. So if you’re asking me to do something I’m clearly missing a point here :). I can be daft at times so do feel free to spell it out. I think that all I can do on my system is said font rendering tweaks and they don’t help. Just to be sure though I’ll do a more systematic round through these settings and get you another screenshot, with what I feel is the best result. Don’t hold your breath though ;)

(Side note: I would love to pick this designer’s brain because I don’t think that the current light/dark mix is optimal. If it were, dark mode would have a light sidebar. But I want to stay focused on solutions not on critiquing designs - overall, everything around elixir looks pretty, well-designed, and that is a step above a lot of other ecosystems)

Sent from Proton Mail for iOS

On Wed, Mar 1, 2023 at 23:58, José Valim @.***> wrote:

That’s inaccurate. The page and sidebar were actually designed with proper time and focus by a UI specialist with accessibility concerns in mind.

The screenshot that you posted means the sidebar is barely usable to you. It is clearly not meant to work like that. So I would consider fixing it. Let’s please focus on that (this is the third comment asking as much).

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[josevalim]

At a minimum, we should reach out to other Linux users and see if they reproduce the issue. I would imagine we would have heard about it before if it was a common issue. The new sidebar redesign is more than 1y old and it has better contrast than the old one (you can check the old one, maybe it looks better for you for some reason). You can also explore the font rendering on Google Fonts itself (16px 300).

Meanwhile we can also increase the contrast on the sidebar (--gray-200 => --gray-100).

[josevalim]

FWIW, Firefox reports the contrast to be 11.98 for me, I further bumped it to 13.23. The purple one was bumped from 5.13 to 7.97 (on main branch). The purple one was indeed too low.

[DavidOliver]

It sounds like you've already improved the readability via colour, but I use Linux (Ubuntu and OpenSUSE/KDE) and can take a look later today. Mac OS has tended to render type thicker than Linux and Windows. It might be worth seeing what the next available weight of the font is.

[josevalim]

Thanks @DavidOliver! I gave a try at the next weight but the jump from 300 and 400 is quite big: https://fonts.google.com/specimen/Lato

[josevalim]

In any case, a new version is out, someone can see the new colors here: https://hexdocs.pm/ex_doc/ And here is a screenshot:

[josevalim]

We can also change the font. Here is Open Sans (15px) on the left vs current:

Open Sans has thicker lines which may make a difference.

Doing this change would also affect the titles, so here is the full screenshot:

[DavidOliver]

Thanks for the release. :)

I can see why the designer went for the light variant based on the Mac OS rendering. In Ubuntu, here's light on the left (as at present) versus regular on the right:

Even in Ubuntu, the regular weight feels just a smidge on the heavy side for the subsection titles, but it is more readable than the light and feels closer to the optimum to me. I expect that regular (400) feels too fat in Mac OS? The regular weight isn't currently loaded, so I dumped this in the HTML head via the HTML inspector just to test:

<link href="https://fonts.googleapis.com/css2?family=Lato:wght@300;400&display=swap" rel="stylesheet">

Though OpenSans is very slightly heavier relative to Lato, it doesn't feel as refined overall and additionally lacks some of the character that I've come to associate with the Elixir documentation, especially in characters such as the '9', so I would recommend keeping Lato.

[josevalim]

Yeah, unfortunately 400 is too heavy on macOS (400 vs 300 below):

I also heard on Linux you will find differences between Chrome and Firefox. Is that correct?

[cdegroot]

@DavidOliver thanks for that comparison shot - at least at that size, it makes all the difference to me. I wish I could share how the achromatic abberation that my lenses apparently introduce mess up the lighter font. And it messes it up to the point that I'm 'well, people always have told me that accessibility should win over 'it looks nicer'" and now that I'm getting on the receiving end, I concur :-) (I was on MacOS when my eyesight started deteriorating and that was the point where I finally left the world of dark mode behind me; but the regular Lato version is at least readable even though I still don't think that the inverted contrast sidebar is a very optimal design. But yeah, platform differences don't help, but are a fact of life).

Is there a way to make the font weight platform-dependent? Given that "light mode sidebar" is apparently an avenue only I want to explore?

[DavidOliver]

I also heard on Linux you will find differences between Chrome and Firefox. Is that correct?

Not to anything like that extent as far as I'm aware. Chrome and Firefox show the 300 text consistently for me.

Could you try 400 in Webkit (and Firefox if possible) with the following CSS added, please?

body {
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
}

This should use grayscale antialiasing rather than subpixel antialiasing, which, I believe, removes the heavier-text effect in Mac OS.

If I understand correctly, this may result in other text rendering less heavily on Mac OS. My thinking is that we can then adjust all weights to compensate and have a more consistent rendering across OSes.

Is there a way to make the font weight platform-dependent? Given that "light mode sidebar" is apparently an avenue only I want to explore?

I'm hoping the above will improve the consistency across OSes.

@josevalim, I tend to agree with @cdegroot that a light mode light sidebar would be good, as the bright white of the content area does negatively affect my perception of the dark sidebar to a degree, and as far as I'm aware I have normal eyesight.

[josevalim]

@DavidOliver unfortunately those options did not make any difference whatsoever. I am afraid the best option forward is finding another font altogether, because I agree the current version is not acceptable on Linux.

[DavidOliver]

Thanks for trying. Could I do some more research/experimenting and get back to you? I have a LambdaTest account and so can load up browsers in Mac OS to test.

[josevalim]

Yes please! I am trying with some fonts too, most are a tricky fit, I will post some suggestions here.

Quicksand (weight 400, size 15px):

[josevalim]

Raleway (weight 400, size 15px):

[josevalim]

Quicksand resembles the Elixir logo but a bit too playful. Raleway looks and feels great to me.

[josevalim]

I sent a PR here for Raleway in case folks want to try it out: https://github.com/elixir-lang/ex_doc/pull/1669

[cdegroot]

Still quite a bit thinner on Linux, I think.

[josevalim]

That's unfortunate. :( Maybe the best option is to keep things as is and change the weight based on user agent or something.

[cdegroot]

FWIW, I just tweaked my light mode option a bit to use shades of the "proper purple".

It's on https://userstyles.world/style/8789/elixir-hexdocs-pm-light-sidebar for those using styling plugins. Basically putting that option out there in this thread so people hunting for it can find it :-)

But yeah, short of fixing it, tweaking weight based on user agent seems to be the best thing. Mine is:

Mozilla/5.0 (X11; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/110.0

Now I see the X11 and realize "shoot, we should verify how Wayland does things" ;-). @DavidOliver are you on Wayland or X11?

[DavidOliver]

Though Raleway is a not-insignificant improvement in terms of weight for me. Lato left, Raleway right:

I'm currently in X11.

Regardless of which font is used, I'll see if I can find a way to improve consistency across OSes and browsers when I next get a chance to spend a little time on it if that's okay.

[josevalim]

I found an article about detecting font smoothing: https://www.useragentman.com/blog/2009/11/29/how-to-detect-font-smoothing-using-javascript/

And here is a proof of concept: https://www.useragentman.com/tests/fontSmoothing/cssExample.html . @cdegroot and @DavidOliver, when you visit the page above, does it say font smoothing is enabled or disabled?

[DavidOliver]

Enabled. I'm pretty sure we've all got font smoothing these days, and that it's (likely partially) a question of the type of font smoothing.

[cdegroot]

Yes, my machines use font smoothing. It really is the rendering engine that seems to make a different decision here.

By the way, I've been tweaking the userstyle linked above a bit while using it today, it's quite nice now. As an Nx noob I had a lot of opportunity to look at hexdocs.pm today using the light style and I still think it's the better solution: simpler to implement, and much better a11y, independent of font rendering issues. I'm more than happy to submit a PR.

[cdegroot]

(by the way, I'm not trying to ram things through with the PR; I just think that it's much easier to discuss merits when you have something working to talk about)

[cdegroot]

Just realized that there's this little OS out of the Pacific Northwest, called "Windows". This is Firefox on Windows:

Seems thinner than Apple as well. I know font rendering quality is not decided by popular vote, and I'm sort of bummed that only one platform seems to get it right, but I guess it is what it is.

[josevalim]

The Apple one looks better than Windows but the Windows looks considerably better than the Linux one for me.

[cdegroot]

Yup. I think that regardless of my light mode PR, a font change should be considered to make the dark mode sidebar better cross-platform and we should not leave out Windows in testing which I'm hereby sorta volunteering for (it'd be better if a dark mode adept would do that but something is better than nothing).

[josevalim]

I used Raleway for a while and I disliked it at the end. I will submit Open Sans in a PR.

[cdegroot]

Given the unceremonial way that the door got slammed in my face with #1672, I'll see myself out now. I'll focus my energy on the Stylus overrides instead, it will still leave ex_doc with the "meh" accessiblity in light mode for the community but apparently it has been decreed that the current colors are inviolate.

[josevalim]

Given the unceremonial way that the door got slammed in my face

You have been told 3 times, in this very issue, that a PR with such changes will not be accepted unless under specific conditions.

Then please don't say you got the door slammed in your face when you submit changes that have been said, 3 times, that they won't be accepted without said conditions.

Maintaining libraries is time consuming as well as contributing patches. Working and reviewing something that was declared to not be acceptable is not productive to anyone.

I will lock this, feel free to submit a PR still @DavidOliver.