Improved Website Styles

[EmNudge]

I really enjoyed reading the blog posts, but found it difficult to do so. These are changes that I think positively affect the readability, but it is of course subjective to some extent.

[brainkim]

I’ll try to take a look at this and provide feedback by tomorrow, sorry for the wait.

[brainkim]

Okay. Sorry for the delay and thanks for doing this work! You’re definitely not the first to say that the docs website is less readable than it could be, and I’m definitely interested in improving readability.

Changes I like:

1. The inline code styling is great! For some reason I wanted to avoid using border-radius on the site entirely, but it just makes sense to soften the corner of inline code blocks.
2. Use of semantic elements like aside and article.

Changes I dislike:

1. Usage of a serif, non-system font. On my machine (macOS), I’m seeing everything as Georgia, and I’d rather just use the system sans-serif consistently to reduce page weight.
2. The code snippet color scheme. I think you’re definitely onto something with using a dark code box for the darker theme, but I dislike the khaki coloring for default text in the box. I would prefer the default color in those boxes be a white or off-white, and only use the orangey colors for specific syntax elements, otherwise it looks a little too uhhh Halloween-y.
3. I spent a lot of time getting the features to each render on three lines. I know it’s crazy but I like the look of it. Some part of the styling changed the number of lines to four.
   
4. I may want to stand my ground on the background/highlight colors, insofar as it might be used in branding and I like it. Unless it can be proven that the contrast is impacting readability I’d like to keep that dark blue in the background. I do want to do with light/dark mode splits though.
5. Link colors are inconsistently applied?
   

All in all, thanks for the effort, and I’m sorry about the current difficulty of building docs and running the server (most of it is undocumented). If you want to continue tweaking the designs in response to feedback, I am happy to have your help, especially because it would be great for another person to provide feedback in terms of site readability, but no pressure. I may merge things like the code pill design anyways. I’m very particular and annoying with design stuff sorry.

[EmNudge]

Thanks for the feedback!

Usage of a serif, non-system font. On my machine (macOS), I’m seeing everything as Georgia, and I’d rather just use the system sans-serif consistently to reduce page weight.

This will likely be a pain point for me. Sans serif fonts demonstrably make for worse reading experiences over longer pieces. For small articles, it's completely fine, but anything longer will seriously hurt readability.

The code snippet color scheme. I think you’re definitely onto something with using a dark code box for the darker theme, but I dislike the khaki coloring for default text in the box. I would prefer the default color in those boxes be a white or off-white, and only use the orangey colors for specific syntax elements, otherwise it looks a little too uhhh Halloween-y.

I threw together random colors, so I'm not deadset on anything specifically for the color scheme, but having light mode code on a dark mode website seems like an extraordinarily odd choice. My eyes are accustomed to reading text one way then immediately need to shift to adjust to the difference.
If the website was in light mode in general (not necessarily a bad idea), then I'd be fine with the color scheme, but not presently.

I may want to stand my ground on the background/highlight colors, insofar as it might be used in branding and I like it. Unless it can be proven that the contrast is impacting readability I’d like to keep that dark blue in the background. I do want to do with light/dark mode splits though.

The changes I made in these departments also contribute to better legibility, but it's not enough to justify a change if you prefer the previous ones for branding. It's fine to keep the previous ones.

Link colors are inconsistently applied?

Are they? I'm not sure what you mean by that or how the screenshot demonstrates this. Previously, the link colors were the same color as the text. It looked like underlines for emphasis rather than a clickable link. Medium can get away with this because they make a deal of being black&white in the style of newspapers. The underlines are also thicker there than normal, which help.

All in all, thanks for the effort

Thanks!
Unfortunately, if only the inline code blocks and semantic elements are merged, it will do very little bit for anything here. Both were just things I did as an aside while I changed the CSS for the rest. The major obstacles in regards to readability were the font choice, font size, line height, and code color scheme. It seems we don't see eye to eye on the changes I wanted to push there.

I do appreciate you taking time to respond! I'll likely see if I can create a chrome snippet to introduce the changes, so you can close PR. I was hoping to introduce the changes via the PR since others I've spoken to said along the same lines of my first comment, but I'll see if I can find another way.

Again, thanks for taking the time!