Hi @beatriz! Thanks for you amazing work in the DocC so far! I have a small request regardless the color of the color scheme control. It's almost a 100% blue in light mode.
The dark mode one is a little more subtle.
It would be great if you could tweak it a little!
Hi @mtsrodrigues! Thanks a bunch :)
This blue is a web-safe color which works across all browsers. In dark mode, it needs to be slightly different so it has an accessible contrast ratio.
If you feel strongly about this, you can open a PR with a new color and your rationale behind the change. I’ll be happy to share my feedback.
I recommend you pick colors that are also web safe. Also good to keep in mind this swatch is used for links and buttons across the board in docs, so the new blue should probably work there as well.
Are there any devices supported by Swift (let alone the compiler) which would ordinarily be used with a 256-color display but otherwise could render a DocC page fully featured? Even if there’s the odd exception, I’d optimize for accessibility and aesthetics over that corner case.
You're right @xwu, web safe colors are much less of a concern nowadays. The goal with the initial color choice was to create a brand-agnostic palette that worked for everyone (even on super old computers). Optimizing for accessibility and aesthetics is a solid plan.
I'm excited to announce that the new Swift-DocC content styling changes described here have been enabled by default in Swift-DocC-Render with:
I've updated the ArgumentParser demo with the latest changes: https://ethan-kusters.github.io/swift-argument-parser/documentation/argumentparser/.
I've also added instructions for trying out these changes with your own package to a post on the Swift-DocC sidebar thread so I recommend following those if you'd like to see how things look with your own projects.
If you encounter any issues while trying things out, a bug report on bugs.swift.org (and soon GitHub Issues) would be really appreciated.
- Ethan
So I had a bit of time to try this out.
It's nice, and I quite like navigating using the sidebar. I'll be filing issues for some interaction issues I've encountered, but overall I think it can be an improvement.
One thing that I have noticed, though, is that it can be very distracting. You're reading this clean, calm, neatly-structured article, but the sidebar creates quite a lot of distracting noise in your peripheral vision. It doesn't make for a nice reading environment, so I'd like an ability to manually hide the sidebar, even on desktop browsers.
Within the sidebar, I feel that topic headers could be much more distinct. Topics break complex APIs up in to clear sections, and we should be using them to make the sidebar feel less cluttered. Here's an example of what I mean: imagine I'm reading some content, and then I glance at the sidebar shown below to navigate somewhere else. All I see is a wall of text; it's disorientating.
If we underline the topic headers, things actually get a lot better (the full extent may not come through on the screenshot). Just at a glance, I immediately know roughly where I am, and where the islands of content are. It's just a lot easier to navigate.
-I don't think the underline style specifically is quite "it" (underlining usually implies a link. Ideally, I would like more vertical space, but it appears the vue component needs rows of equal height). But I do think it demonstrates that we can visually reinforce the structure of the content in the sidebar, and in doing so, also make it feel less messy.
The most concerning part of the redesign IMO isn't actually the sidebar, though - it's the topic sections. This is what they look like before (i.e. now/pre-redesign), notice how well they break a complex type up in to clear islands of functionality:
But here's the same page in the redesign:
I'm not sure this is an obvious improvement. Especially on mobile:
The mobile design actually helps highlight some areas of the new content design which do not quite feel balanced:
This is the main "title" element you see everywhere, and previously there was a nice balance between the little "structure" header at the top (called the 'eyebrow'), the title, and the description. But with the redesign, they appear too close together, and the horizontal margins have shrunk, causing what used to be a very professional-looking design to seem somewhat... less refined.
With some adjustments, it is possible to improve the output:
This also affects the regular, non-mobile site. Titles are just not quite as balanced as they used to be, and together with the new topic sections, it still feels like there are rough edges.
Since this is the fist time I've updated my personal fork of DocC-Render, it's worth pointing out again what IMO is the single biggest issue towering over all of these design niggles, which is that font weights and spacing are tuned for Apple's proprietary fonts, not Helvetica, which is what the open-source DocC-Render actually uses. By adjusting the weights to match the same values in Apple's font, and setting all spacing adjustments to 0, you can drastically improve the DocC-Render output. Especially in the sidebar, actually - the current settings squash sidebar items quite severely. It's better to not use any font-spacing adjustments than to use the wrong adjustments. [SR-15567] Improve legibility of typography elements for base Helvetica font · Issue #280 · apple/swift-docc-render · GitHub
Example 1:
Example 2:
Anyway, overall it's really nice. Like I said, I can imagine getting used to navigating with the sidebar very quickly! But the design tweaks will need time to settle and to iron out all the wrinkles.
