Please bring back the paintbrush icon, or an equivalent!

[steffahn]

It seems as if #92629 has removed the theme picker from rustdoc. Both the way to change themes as well as any indication of the fact that changing themes is possible in the first place is hidden behind a setting page that many users will probably not even use at all.

My initial experience with rustdoc and mdbook, back over 1 year ago, was quite positive because of the easy option to customize the looks / themes. I hadn't set up my browser for any dark theme yet at the point; the easy accessibility and good visibility of the paintbrush icon largely introduced me to the appeal of dark-themed documentation pages.

I have switched themes in rustdoc countless times. For every new browser, for every new device, for every new incognito window on a non-dark-theme-configured browser / device. And that number multiplied by the amount of websites that contain rustdoc, which is docs.rs, doc.rust-lang.org, and a whole lot of self-hosted pages for certain crates, like docs.serde.rs.

The change in #92629 makes changing themes about 20x more effort. Instead of 2 clicks (click paint brush, then the theme) in the same area of the page, you need to:

• click the (less conveniently and less visibly located) setting button
• this takes you to a different page!
• traverse the whole screen with the mouse
• click to toggle "use system theme"
• traverse the whole screen with the mouse again
• click to open the drop down menu
• click to select theme (this changes the theme)
• move mouse to browser's "back" button to get to previous page
• click back button
• this takes you back to the previous page, and the new theme is no longer visible (admitted, this issue only happened sometimes)
• click refresh
• this changes the theme back back into the newly selected one

So over all

• the page changed 5 times (2 navigation, 3 theme changes)
• the mouse traversed width of the the screen twice
• I had to click 6 times

Previously it was

• 1 page change (theme change)
• two clicks
• no significant forced extra mouse movement

Additionally, discoverability is terrible (I estimate that – optimistically – less than half as many users will be able to find out on there own that there are themes in the first place), the settings page with its initial layout showing "preferred dark / light theme" is confusing, the need to go back to the previous page using browser navigation is confusing, and the need to refresh the page is absolutely confusing.

Finally, if I don’t know my favorite theme yet and want to compare the looks:

• I can’t get a direct visual comparison at all because it displays a different page in-between,
  • unless I open multiple tabs to be able to switch themes for direct visual comparison
• The issue of having to click more and do more stuff multiplies, because I want to take a look at all the themes. With just 3 themes right now, this is somewhat manageable, because you “only” need to play the game twice to be able to see all the themes, and a third time to select your favorite; but assuming that more themes might be added in the future, it will get worse.

---

The change on nightly rustdoc unfortunately affects crate documentations on docs.rs immediately. In my personal opinion this change is a terrible user experience and should be reverted as fast as possible. Future attempts to remove the paintbrush icon should, in my opinion

• make sure that changing the theme is less effort, including at least that you don't have to leave the page at all
  • maybe a pop-up version of (a subset of) the settings could be implemented
• make sure that themes stay discoverable
  • maybe, if rustdoc is able to save theme selection, it’s also possible to show a visual hint to “first-time” users, that there’s an option for theme selection in the settings

But I don’t actually see any problem with just keeping a paintbrush symbol. Mdbook does this, too. Rustdoc pages are usually huge and full of information, I don’t see why there wouldn’t be room to keep the paintbrush symbol. I also don’t understand why a redundant way to change the same setting has to be a problem; after all, themes are a great feature, (who expects API docs to have themes? wow, Rust is so great...) and discoverability of this feature is only improved if there’s multiple ways to change them.

If you want to address the main point of #84539, well, I don’t understand how that’s a significant issue in the first place, and there are probably better solutions than removing the paintbrush symbol. For example I personally wasn’t even aware that there was a different way of choosing themes than using the paintbrush symbol. My first reaction to browsing nightly std docs was “oh no, have they now joined those websites that don’t give you any configuration option besides automagically syncing with system settings?” (These websites are terrible if you’re on a device where it’s hard to bring your browser into an actual working dark mode; this took me multiple days to achieve on my current PC (linux), and actually it’s still kind-of broken). The main question

It's not clear how these are related. Does one override the other? Also, what is the "system theme"?

describes a minor problem; it doesn’t really matter whether a user understands the precise logic of these settings as long as they find some option easily that makes the website look the way they want it to look. And Github is a bad comparison because it’s a central (single host) website that basically assumes you’re logged in, which immediately makes (the equivalent of) the problem of having to reconfigure for

• new devices and browsers
• new rustdoc-hosting pages

go away. Good luck trying to change your Github theme when you’re not logged in (I’m not even sure if that’s possible at all!) Well, but for rustdoc paged, you’re never logged in! Hence, adapting Github’s approach is probably a terrible idea, isn’t it?

@rustbot label T-rustdoc

cc @jsha

[jsha]

Hi @steffahn! Thanks for the detailed feedback. For additional context, these changes are also largely motivated by:

• Rustdoc formatting presents accessibility issues #59829
• rustdoc styling improvements for readability #59845
• Controls and search in Rustdoc header are visually distracting #59840

The overall theme is that a lot of visual clutter harms readability - particularly for readers with dyslexia, and also particularly for new users. The paintbrush icon is one of the things I have heard the most complaints about - it occupied an enormously prominent position on every single documentation page, for what is -- in most cases -- a one-time operation.

this takes you back to the previous page, and the new theme is no longer visible (admitted, this issue only happened sometimes)

This is definitely an issue, and will be fixed by #93097. That PR will also add the "Escape" button as a hotkey to leave the settings menu, going back to the page you were on.

Another really nice improvement we could make here - instead of a drop-down, theme selection should really be a radio button interface, so the themes are all visible when you first open the page, and it takes only a single click to set one.

By the way, you may be interested in the "Rustdoc settings sync" add-on by @notriddle:

https://chrome.google.com/webstore/detail/rustdoc-settings-sync/bjlannnpljhejnbhnjghmamhidbcbhgm
https://microsoftedge.microsoft.com/addons/detail/rustdoc-settings-sync/hkgcnanboeeppamlahljjbhilelbnehf
https://addons.mozilla.org/en-US/firefox/addon/rustdoc-settings-sync/

This will automatically sync your settings across doc.rust-lang.org, docs.rs, and localhost, hopefully saving some more clicks. @notriddle, what do you think of adding some of the more popular third-party rustdoc sites, like doc.serde.rs?

[steffahn]

No, I am not installing a browser extension just because rustdoc decides to make its theme setting unworkable without an extension that would fix it! And extensions aren't even a solution for all mobile browsers, or help when switching devices.

Browser extensions can be great for websites of stubborn companies that regularly decide to kill user experience for whatever reason nobody asked for, nobody understands, and where user feedback isn't taken into account. (If you couldn't tell, I'm not happy with what kind of BS YouTube is pulling off at the moment, just that their BS can't even be fixed with browser extensions.) Before I recently installed "dark reader" extension, rustdoc and mdbook were the only websites I've been using that had a comfortable to use approach to dark themes. Now, only mdbook is left.

If high contrast of the paintbrush or its location are a problem, move the symbol or lower its contrast. I seriously cannot imagine any solution to theme selection that I wouldn't consider worse in user experience, other than a dedicated, visible by default theme picker drop down menu (labeled with an icon or text that suggests this is about themes/appearance). The degree of "how much worse" of course varies, the current solution is about as bad as it gets. Also, anything that requires more than 2 clicks or has the intermediate effect of (visually) taking you to an entirely different page, seems particularly annoying. #93097 doesn't fix any of this. Take a look at https://meta.discourse.org for a website that has an acceptable, but not great approach to themes. Pros: you can change themes in the hamburger menu without being logged in, with 2 clicks, and without taking you to a different page. Cons: still hard to discover, especially if you're not searching for it.

(Note that I don't share the opinion that it's too high contrast or in a bad location. Moving it will force existing users to search for it again, and a different contrast might not fit in visually.)

[steffahn]

For the record, I like the changes to the setting menu a lot. Also all the other recent appearance related changes are pretty decent. #93097 is a great change, too, and your addition to make the theme setting more understandable (im the same PR that removed the paint brush, I think) when not in "use system theme node" is highly logical and just makes sense. Just, I don't see any reason against also keeping the paintbrush. Properly dark themed websites are rare, properly changing browser settings can be a pain or impossible, even for experienced technical users, and even if they weren't relying on "system settings" never helps users that like theme changes on a case-by-case basis, or depending on lighting conditions or the theme of other applications they have open, nor users that share the same device and account, yet have different preferences.

[notriddle]

No, I am not installing a browser extension just because rustdoc decides to make its theme setting unworkable without an extension that would fix it!

To be clear, I made that addon because I already considered themes on file:// URL unusable, paintbrush button or not, because Firefox treats every single HTML file as its own origin with its own theme. The addon is the only way to really fix this problem in local documentation, because it’s caused by the browser sandbox.

93097 doesn't fix any of this

It fixes the need to reload the page at the end. I guess this isn’t a big deal, but it’s one less step.

[steffahn]

@notriddle FYI, I was not intending to discredit the add-on. I understand its use for file URLs in Firefox. I don’t currently need an add-on; I’m not experiencing any problems – even on file URLs – in Google Chrome. Also, on second thought, a settings sync add-on is fairly orthogonal to this issue anyways. If I can install an add-on, I can probably also set an appropriate system theme. My main point is about new devices or other people’s devices that I might be using, or Google Chrome on Android, where I haven’t figured out a dark theme yet (and it doesn’t support extensions AFAIK), or – and that’s my main point – new or casual users of rustdoc documentation who might not know about the option to select themes in the first place.

I used to be a new user myself not too long ago, on a device not configured for choosing dark themes by default, and I can say that it was easy to learn about the existence of themes in rustdoc, and easy select a different theme on a not perfectly configured device, because of the theme picker / paintbrush symbol. I’m saying that the theme picker was an important aspect of my positive experience with rustdoc when learning Rust, so I’d be quite disappointed when future learners of the language cannot make the same positive experience anymore. As I hinted at above (I think, somewhere...), the fact that Rust’s documentation had such a user-friendly approach to themes had the effect that mdbook and rustdoc really introduced me to trying out (and ultimately liking) dark-themed websites in the first place; most other websites don’t have themes, and many of the few ones that have dark themes make them insanely hard to choose manually, in particular if you haven’t re-configured your system to prefer dark themes by default.

The issue I’ve opened here won’t significantly affect me personally very much. I know about themes, I can work around this, if I come across a situation where I need to change the rustdoc theme in the future, I’ll be annoyed for a second, and then dig through the settings page.

---

I just recently watched a streamer on YouTube learning Rust for the first time, with the book. Book was in a light theme on the first stream, and a dark theme on the second. They probably discovered mdbook’s paintbrush symbol / theme picker in the meantime. I’m convinced that once they will start using standard library docs, they will easily find out about the fact that it has themes if and only if the standard library still has a theme-picker that looks (mostly) the same as the one from mdbook.

I suppose the fact that many people learn Rust with the book (which is an mdbook page) is quite important here, because it means there’s great value in keeping the rustdoc theme picker similar to the mdbook theme picker. It’s even in the same position on the top, to the left of search, to the right of the side-bar there, so quite a lot of similarity. The menu elements are lower contrast though, so that seems an appropriate change that rustdoc could make here: Particularly on rustdoc’s theme “dark”, the buttons are currently white buttons on dark background. I wouldn’t mind if that changed. The mdbook buttons don’t even have an outline, I wouldn’t mind if that changed for rustdoc either for the theme-picker, help, and settings button.

[GuillaumeGomez]

I also think that the painbrush being less accessible is an issue. mdbook allows to change the theme easily. I'm just not sure how to make the UI less cluttered...

[tinaun]

I think the paintbrush should be brought back on the right, next to the settings icon - currently I find all these recent css changes incredibly off-putting but I think I could get used to them, but I really did like the paintbrush and the lack of it makes documentation much less usable for me

[GuillaumeGomez]

Well, let's ask our UX/UI expert about this.

cc @jsha

My previous comment might have not been very clear about my position so just in case: I don't like not having the paintbrush as easily accessible as before but @jsha's arguments convinced me that it was too cluttered and a small cleanup was necessary.

[tinaun]

this is purely anecdotal evidence but i've noticed a lot more people in beginners channels asking how to change the documentation theme since this change was implemented - I wouldn't mind having just the settings icon instead of two, but removing the instant feedback is a major setback

[jsha]

We've made some changes in response to the feedback here:

• Fixed theme updating on forward/back navigations. Now if you change theme on the settings page then go back, the page you go back to will have the correct theme.
• Changed theme selector from dropdown to radio buttons. This means there's a larger click target, and it takes only a single click to select one, rather than a click to open the dropdown and a click to select.
• Added a Back link on the settings page, aligned nearby the settings button and the theme buttons, so you don't have to move your mouse very far.

The process now takes just 3 clicks, all of them close to each other. Here's what it looks like now:

[steffahn]

I'm aware of these changes.

Now you're defining ayu as a light theme in that demo!?

I'm not convinced anything can be as user friendly as a paintbrush icon. I'm not convinced a paintbrush symbol is a clutter or distracting or bad in any way. I am convinced that there's clear disadvantages w. r. t. discoverability and usability when NOT having it. Accessibility (which apparently is a main movation to remove the icon!?) is also greatly reduced if a user can't find the dark mode (of never learns of its existence in the first place) even though they would benefit from it.

As the rust book is the main way of starting to learn the language, I still think that consistency with mdbook is a important factor. Unless mdbook removes their paintbrush, I think rustdoc should have one.

I think I've had that Back functionality fail once on mobile, I don't remember the details and can't reproduce it right now.

Switching between system theme enabled or disabled can leave the radio buttons in an incorrect state.

Given the (unfortunate) situation that docs.rs uses nightly rustdoc and we're getting new documentation generated every day that can potentially stay being the latest version for quite a while, I'm somewhat disappointed how long the documentation keeps staying in a somewhat broken state (broken, as far as my personal perception/interpretation of the current status goes). Especially if bringing back the paintbrush icon is any realistic option (which, judging by reactions / feedback from others in this thread, I think it might be) then having it disappear and then reappear significantly later is a somewhat weird move. (If we do bring it back, by now, there'd even be the need for a beta backport potentially.)

I would open a PR for this myself, just to get some more feedback whether it really should be gone and stay gone, but I'm unfortunately very unfamiliar with HTML / Javascript and such things.

[notriddle]

this is purely anecdotal evidence but i've noticed a lot more people in beginners channels asking how to change the documentation theme since this change was implemented

I'm not convinced anything can be as user friendly as a paintbrush icon. I'm not convinced a paintbrush symbol is a clutter or distracting or bad in any way. I am convinced that there's clear disadvantages w. r. t. discoverability and usability when NOT having it.

The reason these anecdotes seem unconvincing, at least to me, is that they're trying to tell me something I never disagreed with in the first place. I know that the theme switcher is harder to find than before; you don't have to convince me of that. Given that people focus more on the left-hand side of English-language web pages, and that the theme button was the leftmost option in the global toolbar, it couldn't have possibly been any easier to find before.

I just don't think the theme switcher deserved to be the single most prominent button in the entire application.

Accessibility (which apparently is a main movation to remove the icon!?) is also greatly reduced if a user can't find the dark mode (of never learns of its existence in the first place) even though they would benefit from it.

Pocket actually does a better job of this than rustdoc or mdbook do, in my opinion:

It's still not as easy-to-find as rustdoc's theme switcher used to be, but the theme switcher does not deserve to be the single most prominent button in the entire application. It is still better than the dedicated Settings page, since it offers the instant feedback you want.

And, most importantly, if Accessibility is your reason for offering color schemes, you really should also offer font size changes.

[steffahn]

Pocket actually does a better job of this than rustdoc or mdbook do, in my opinion

Obviously with a solution of that style, I would be mostly okay. As I noted in my original post:

Future attempts to remove the paintbrush icon should, in my opinion

• make sure that changing the theme is less effort, including at least that you don't have to leave the page at all

  • maybe a pop-up version of (a subset of) the settings could be implemented

Comparing to status quo of the Rustdoc settings, apart from the fact that it takes you to a different page, there’s additional significant differences to the Pocket screenshot: The fact that by default there’s going to be 2 sets of selection, labelled “Preferred light theme” and “Preferred dark theme” makes this option immediately highly non-straightforward to use, and even harder to use properly (who’d guess that deselecting “Use system theme” changes the menu) (I’m considering changing the “Preferred light theme” to a dark theme to be a case of “improperly” using the settings). And there’s a label for the theme selection, but that label is very, very, very, very far removed from the selection itself. E.g. with “Use system theme” disabled, it’s ridiculous, look at the word “Theme” and what it’s supposed to be referring to:

[steffahn]

The process now takes just 3 clicks, all of them close to each other.

So on mobile, and properly changing the option, the thing takes 4 clicks (the 4th click is deselecting “Use system theme”), and the things aren’t quite as close together and smooth:

• the “Back” button is on the left side
• toggling “Use system theme” makes the radio buttons jump across the screen
• in it’s location, the “Back” button is easy to miss, my intuition was then to click the cog wheel a second time, which has a weird page reloading effect and otherwise does nothing. I’d suggest that clicking the cog wheel button when you’re already on the settings page should take you back, too.

---

---

Thinking about how to solve the problem that those “preferred … theme” options are confusing, here’s an idea

Have a straightforward theme selection on top, then a toggle for system theme, and then an expandable section to customize the system theme.

◯ light◉ dark◯ ayu
□▣ Use system theme

Customize system theme

Preferred light theme ◉ light◯ dark◯ ayu
Preferred dark theme ◯ light◉ dark◯ ayu

Maybe different wording from “system theme”, e.g. “Choose theme automatically”

◯ light◉ dark◯ ayu
□▣ Choose theme automatically

Advanced automatic theme settings

Preferred light theme ◉ light◯ dark◯ ayu
Preferred dark theme ◯ light◉ dark◯ ayu

Then, in terms of interaction, if you deselect “Choose theme automatically”, the “Advanced automatic theme settings” settings disappear completely:

◯ light◉ dark◯ ayu
▣□ Choose theme automatically

Similarly, if you change the theme directly at the top, then the “Choose theme automatically” setting is disabled, e.g. clicking on “◯ ayu” in the original state above, brings you directly into a state of

◯ light◯ dark◉ ayu
▣□ Choose theme automatically

---

Finally, while

□▣ Choose theme automatically

is enabled, then changing “Preferred light theme” or “Preferred dark theme” should automatically affect the current theme. I.e. the original state above

◯ light◉ dark◯ ayu
□▣ Choose theme automatically

Advanced automatic theme settings

Preferred light theme ◉ light◯ dark◯ ayu
Preferred dark theme ◯ light◉ dark◯ ayu

is only possible when the “system” is in dark mode (otherwise, “◉ light”, the preferred light theme, would have to be active in the first line), and clicking on “◯ ayu” under “Preferred dark theme” gets you into this state

◯ light◯ dark◉ ayu
□▣ Choose theme automatically

Advanced automatic theme settings

Preferred light theme ◉ light◯ dark◯ ayu
Preferred dark theme ◯ light◯ dark◉ ayu

Reenabling “Choose theme automatically” should immediately change the selected theme in the top line, too, according to the currently active preferred themes. The expandable “Customize system theme” option should, whenever it’s hidden by deselecting “Choose theme automatically”, probably remember its expansion state, so when it was expanded while it was hidden, it should re-appear expanded when you toggle “Choose theme automatically” twice.