Clarity - a new theme for Sphinx

[liborjelinek]

Hi dear fellow Sphinx users,
I recently spent some time designing a new Sphinx theme focused on typography, spacing, and overall readability. The goal was a clean, modern, and distraction-free reading experience for technical docs.

Live demo:
https://readcraft.io/sphinx-clarity-theme/demo

Also, thanks for starring on GitHub:
https://github.com/ReadCraft-io/sphinx-clarity-theme

I’d really appreciate feedback from other Sphinx users — especially what works well and what could be improved.

Libor

[flying-sheep]

Nice, very streamlined!

I also really like the comprehensive narrative and reference docs, including “how to figure out that CSS variable name”. Not many are that explicit!

One thing I always look for and didn’t find immediately is the kitchen sink: most themes show off all Sphinx elements (like headers, admonitions, :guilabel: and so on) as well as all extension elements they support (commonly sphinx-design).

Also a pet peeve: The default for dark mode and light mode should always be “follow system theme”. If you have a toggle button, it should be tri-state (and of course still default to “follow system theme”, with “explicitly dark” and “explicitly light” being the other two options).

[liborjelinek]

One thing I always look for and didn’t find immediately is the kitchen sink: most themes show off all Sphinx elements (like headers, admonitions, :guilabel: and so on) as well as all extension elements they support (commonly sphinx-design).

I use an extensive "kitchen sink" internally during development and testing, but you are 100% correct: it should be public too.

Also a pet peeve: The default for dark mode and light mode should always be “follow system theme”. If you have a toggle button, it should be tri-state (and of course still default to “follow system theme”, with “explicitly dark” and “explicitly light” being the other two options).

This is how currently dark mode selection works (citing https://readcraft.io/sphinx-clarity-theme/docs/en/latest/customize/dark-mode/#how-dark-mode-selection-works)

1. On first visit, the color mode matches the user’s OS preference.
2. Users can switch modes any time using the toggle button.
3. The selected mode is stored in localStorage for future visits.

Unfortunately, there is no way to reset to "OS preference" and to limit the theme to dark or light mode only.

[flying-sheep]

Unfortunately, there is no way to reset to "OS preference" and to limit the theme to dark or light mode only.

Exactly, I hate when sites do that, it’s worse than not having a button and just following the system theme (which is a super valid option, that button is a play thing now that all OSs allow configuring the preferred theme).

I often click the button out of interest how their other theme looks like, and when sites do it the way you do, now the site is broken for me until the cookie gets deleted, as the most useful mode can’t be returned to (i.e.g following the system theme, which for me changes at dusk and dawn)