RFC: default UI polishing

[Josh-Cena]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

We have several UI polishing requests that I think are very justified. Although they can be easily implemented through swizzling, I do think Docusaurus should offer a better default UI.

1. The language icon doesn't look very good. The React docs uses the mdiTranslate material icon, which looks sturdier.
2. The color mode toggle should be a button rather than a toggle. This can be argued both ways (the toggle looks more explicit), but seems like a button is by far the most prevalent choice: Material UI, VuePress, Ionic (which is still Docusaurus!)
3. The sidebar collapse button should be on the side instead of at the bottom. For example, Dyte. The reason is because there's a significant deviation in the position of the toggle button when the sidebar is expanded vs. collapsed. In addition, the button at the very bottom of the page is admittedly not very visible.

This doesn't mean that everything needs to be implemented, just want to hear about more people's opinions on what UI improvements we should make.

Has this been requested on Canny?

https://docusaurus.canny.io/feature-requests/p/make-the-language-changer-icon-configurable

Self-service

• [X] I'd be willing to contribute this feature to Docusaurus myself.

[slorber]

100% agree with all of this 👍

The theme color toggle is there for a long time. At that time toggles were more popular than single icon buttons

The i18n icon is the one from Docusaurus v1, I took the first icon I found to ship i18n fast but we can definitively use a better icon.

The sidebar collapse works but also agree that we can do better. The Dyte example is nice (a bit small IMHO). And this would probably simplify the sidebar code too. Any opinion @lex111 ?

[lex111]

Honesty, I don't really like Dyte's sidebar collapse button, I had previously considered similar design, but ended up choosing a big button at the bottom of the sidebar.

With the current design of sidebar, similar collapse button wouldn't look very good. I mean, it would require changes to other parts of the UI (since for example it will lead to decrease width of sidebar menu). Note that on the Dyte site, the sidebar items are stretched to the right side plus invisible scroll is used. So overall the revamped button looks good. However in Docusaurus the default styles are different, so that sidebar layout must also be changed, otherwise you get something like this:

And given that navbar can be hidden, such a button looks quite strange.

In addition, the button at the very bottom of the page is admittedly not very visible.

I would say on the opposite: a big full-width button is very visible rather than a small square button, and its position (top or bottom) doesn't make much difference here.

I was inspired by the GitLab docs example when I created this feature, but I can't remember which other docs sites have the feature like that, so maybe there are better ideas on how to place the button, but given our current design, I couldn't think of anything else to do.

[Josh-Cena]

Honestly I haven't even seen any other website (or I forgot) with a collapsible sidebar either, so not much idea to offer 🤷‍♂️ What about a larger (than Dyte), but more consistently positioned collapse button? That would at least help us simplify our code.

Concerning the speculated "looks quite strange", it's hard to say without first seeing a POC...

[lex111]

Maybe it doesn't matter anymore, but I don't really understand the motivation of changing UI of color toggler. In my opinion, it should look exactly like a toggle switch, then its purpose is most understandable for users. Here are just a few major docs sites where the color change looks like a toggle switch, not a button:

• https://developer.mozilla.org/ (new design)
• https://vuejs.org/guide/introduction.html (new design)
• https://docs.docker.com/compose/
• https://squidfunk.github.io/mkdocs-material/getting-started/ (Docusaurus' alternative)
• https://react-hook-form.com/api/
• https://docs.spring.io/
• https://developers.cloudflare.com/
• https://web.dev (not docs site actually, but still)

Also, many highly customized sites probably relied on the previous UI of color switch, so if it looks like a button, it will no longer fit their custom site design, I guess. As correctly stated, the previous design looked more explicit, but now I would not say that color mode can be switched at all, until you press the button -- so it's strange solution.

[Josh-Cena]

I can equally give many sites that use a button as toggle, some of which I'd say look even more modern.

• https://v2.vuepress.vuejs.org/
• https://turborepo.org/docs
• https://mui.com/
• ...

But the actual design is probably not the point here. The point is that:

1. Our previous design looks pretty terrible (which I think you can echo with)
2. The deprecation of the toggle options is going to happen anyways, because the icon/styles options aren't really scalable and we want to encourage people to swizzle.
3. The public API surface (the props of the ColorModeToggle) remains the same, so people who have customized their toggle should find it easy to migrate.
4. Most (99%?) of the sites use the default layout, and currently the color mode toggle is the single most prominent feature that stands out in a negative way (because of that intimidating emoji—I have discussed with other users about this design on Discord and only proposed the alternative after collecting their responses). Using a more subtle design makes the page look more integral.
5. We were able to delete a lot of code when migrating from toggle to button. This is desirable, because it means if the user swizzles the code, she can know what it does at a glance, instead of trying to understand how it works first to figure which parts she needs to touch to make the customizations. It also means people can bring in their own toggle design, which creates a richer design ecosystem in userland rather than being coupled to our react toggle, which as stated in (1) doesn't look good.

So in conclusion, this change is to simplify our code and force users to bring more code of their own, instead of being confined to what we offer.

[lex111]

I disagree, the previous design was very good to me. By the way switchConfig was a very convenient and useful option for quick customization, I have seen people use it. Now when upgrading they will be forced to swizzle the component, although this is not recommended. In general, it that's all strange decisions which alas I can not influence.

[Josh-Cena]

although this is not recommended

Toggle is encouraged to be swizzled—that's what the deprecation error message is pointing to. The entire point of #6243 is to progressively make everything in our codebase safe for swizzle, because we want to encourage users to bring their own UI. So I think the direction is that we will remove more theme config options in the future and recommend swizzling instead.

[Josh-Cena]

that's all strange decisions which alas I can not influence.

Now that you are back, your opinion will of course take an equal importance in our decision-making 😄

[slorber]

I personally prefer the new toggle and never really liked the old emoji/based design. But I understand that it is a matter of personal preferences.

---

I if a lot of people report preferring the old switch design, we might support the ability to have both styles

And we can eventually bring back the switchConfig option if a lot of persons complaining had custom toggle designs.

So I think the direction is that we will remove more theme config options in the future and recommend swizzling instead.

Yes, that's the idea. <ColorModeToggle> has been cleaned up and is meant to be swizzled, we'll be careful to maintain retrocompatibility on it.

Let's ask the users to code a bit instead of providing an exhaustive list of options to support most fancy use-cases.

Now I wouldn't mind if we had a design system presenting 2 distinct toggle designs and a very simple config option like toggleType: "button" | "switch"

---

Which one should be the default? We can poll the community to decide, no ego.

[Josh-Cena]

Community is pretty positive. Discord feedback suggests most are happy with the new design (the old one looked creepy, multiple complained), and those with customizations don't find it too hard to migrate after I pointed out they need to swizzle.

[lex111]

Well, if most of the team thinks a button is better than a toggle switch, alright then, I personally will miss the old design/functionality. However, the a11y and semantics of the new button are broken now, so I have opened the PR to fix it https://github.com/facebook/docusaurus/pull/6930