[docs][docs-infra] Early feedback v2

[oliviertassinari]

Summary

This is a refresh of #588 with the up-to-date problems/opportunities with the documentation, since we made a lot of changes since.

The goal is to cover more table stack expectations that users can have, looking at what could be seen a missing coming as a user from Material UI docs.

Motivation

Try to provide great DX.

List

In no specific order, some should probably be moved to their own issue:

• 1. Headers text are harder to select than in Material UI. When it comes to the header, I believe that I use them 50% of the time to share a link with someone else, and 50% of the time to search on the page all the hits about that specific topic in the header (since I'm lazy, I copy part of the header)

Screen.Recording.2025-09-15.at.23.59.07.mov

• 2. There are no "reset focus" feature. It seems harder to test without. Shouldn't there be one (under a triple dot menu)?

• 3. There are no links to the source. It feels impactful to help the community contribute fixes. Shouldn't there be one (under a triple dot menu)?

• 4. There is no light/dark mode toggle. It's not obvious that everyone uses the same mode for their OS and code. For example, I'm personally mostly in light mode. I moved to dark mode for some code-related tasks.

• 5. Demos are not editable. Waiting 5-10 seconds to open a demo in CodeSandbox or StackBlitz is not the best experience. Better would be to be able to test prop combinations instantly.

• 6. Element that handles onClick don't have cursor: pointer. Current behavior seems great for people who are building Electron apps, where on desktop, the expectation is that the UI is so normalized, everything looks the same, that, as a user, you can predict what's clickable, and hence, you don't need to be distracted with cursor changes.
  However, for the rest of the people, building for the web, every website is different; it feels a lot more frustrating to not know if an element can be interacted with or not than to have a cursor change distraction, blurring the lines of what is a link and what is a button.

  To be clear, this point is not me saying that we should make this change; it's me not confused, trying to understand the logic. Related to [bug]: Cursor pointer not working when hovering on button in Tailwind v4 shadcn-ui/ui#6843.

  Edit: tradeoff discussed more ⬇️ in the comments.

• 7. Having a terminal toggle would be nice for lazy people. I'm using pnpm, I would rather have a direct copy & paste that is saved in a cookie.

https://base-ui.com/react/overview/quick-start

e.g. https://ui.shadcn.com/docs/installation/next

• 8. Docs search [docs] Add search #2144
• 9. The TOCs headers seem strange. Is it expected?

https://base-ui.com/react/components/checkbox

I would have thought it would be clearer with "On this page"?

• 10. The scroll in the TOCs is broken; to move, you need to scroll the page. You lose your current reading context:

Screen.Recording.2025-09-16.at.00.30.28.mov

• 11. Social cards per component https://www.opengraph.xyz/url/https%3A%2F%2Fmui.com%2Fmaterial-ui%2Freact-tabs%2F vs. https://base-ui.com/react/components/tabs. The og title is also wrong.

• 12. Restore SEO / EAO from before [docs] SEO issues on https://base-ui.com/ #1615.

• 13. StackBlitz and CodeSandbox are almost equally used by the React community. GA usage in Material UI also show this pattern. So it seems that people tend to pick one and stick to it. Offering only one option can be frustrating (if it's not the one you prefer). I imagine there must be a way to allow people to toggle and change the default open action.

• 14. The TOCs don't show the current position on the page. I felt a bit lost on https://deploy-preview-2719--base-ui.netlify.app/react/handbook/customization#controlling-components-with-state. I would expect an indicator to know my scroll position, for example:

Screen.Recording.2025-09-24.at.12.46.07.mov

https://clerk.com/docs/upgrade-guides/upgrading-from-v2-to-v3

• 15. The list items feel a bit too close to read comfortably; 1, 2, 3 more pixels in the gap could help. https://master--base-ui.netlify.app/react/handbook/animation#elements-removed-from-the-dom-when-closed

But where it gets broken for me is: paragraph lists. For example, I fail to read this: https://master--base-ui.netlify.app/react/handbook/typescript#other-accessible-types

The notion of a loose list for large paragraphs in lists could fix this if we want to have tight lists. Quick benchmark in: #2824 (comment).

• 16. The number list are not correctly aligned: https://master--base-ui.netlify.app/react/utils/use-render#merging-props

• 17. There can be mistakes on the docs; without an edit source button, we are less likely to see contributors open PRs.

[mj12albert]

Just sharing my thoughts on some of these:

Demos are not editable

I thought this would be good when it was added in the Material UI docs but in the end I never used it, testing it in CSB/stackblitz feels more neutral

There are no "reset focus" feature. It seems harder to test without.

Usually just clicking the empty space in the demo is enough to reset it? People may instinctively do that first before exploring all the buttons there

[atomiks]

Some thoughts on these:

1. Headers text are harder to select than in Material UI

I feel like 90% of the time if you want to click the header text, it's because you want to link to it, not select the text? It's easier to do this when the entire thing can be linked than a small icon next to it. I'm curious why someone would want to copy the text and not the link. If they're discussing the page and link the text ("for example under the Virtualization header..."), they'll prefer to link to it

4. There is no light/dark mode toggle. It's not obvious that everyone uses the same mode for their OS and code. For example, I'm personally mostly in light mode. I moved to dark mode for some code-related tasks.

Do you mean code blocks should be seen as dark/light, or the demo itself, when the system is the opposite?

6. Element that handles onClick don't have cursor: pointer. Current behavior seems correct for people who are building Electron apps, where on desktop, the expectation is that the UI is so normalized, everything looks the same, that, as a user, you can predict what's clickable, and hence, you don't need to be distracted with cursor changes. But for anyone else building for the web, every website is different; it feels a lot more frustrating to not know if an element can be interacted with or not than to have a cursor change distraction.

On the web, the cursor: pointer style is fairly universal but it's not used for non-links in the native OS. People are so used to it in web dev that they just change it without a second thought. To me, making only links (things that can be opened in a new tab) have the style is a useful affordance in web apps.

I think with good hover styles, it's not necessary to use and makes the UI feel less premium/native and cheapens it. JUI looks & feels incredible without using it; adding it would make it feel cheap. https://x.com/colmtuite/status/1933543454996365477

10. The scroll in the TOCs is broken; to move, you need to scroll the page. You lose your current reading context:

I wouldn't say it's "broken"; it's just a different style to avoid duplicate scrollbars. GitHub for instance uses it right on the issue sidebar:

Screen.Recording.2025-09-16.at.4.13.37.pm.mov

I don't think reading context matters here since you're trying to go somewhere else on the page anyway

[oliviertassinari]

5. I thought this would be good when it was added in the Material UI docs but in the end I never used it, testing it in CSB/stackblitz feels more neutral

@mj12albert I feel like I had a different experience on this, but I'm using it as a maintainer, not as a user, so I don't think I count so much beyond helping with reasoning with it. It could be great to add GA Events on Material UI to know the current usage pattern.

Actually, this makes me think that we should revert mui/material-ui#43618. We don't get any of the issues the PR fixes in Base UI (I believe), but with this PR, it's now frustrating to use CodeSandbox in Material UI (to share / save edits).

2. Usually just clicking the empty space in the demo is enough to reset it? People may instinctively do that first before exploring all the buttons there

Yeah, ok, maybe it's enough. To be clear, I don't think this proposal has much value for users; it's mostly for contributors.

1. I'm curious why someone would want to copy the text and not the link.

@atomiks Maybe it's just me, my use case is 50% click to share the link with someone else, and 50% select part of the header, to search on the page with the keyword it has to find all references (I don't want to read, I want to skim read).

4. Do you mean code blocks should be seen as dark/light, or the demo itself, when the system is the opposite?

I'm thinking about those use cases: 1. their system is in light mode, but they code in dark mode. They need a button to toggle the docs' light/dark mode. 2. They want to test how light/dark mode is handled by the component. They need to toggle the mode.

6. To me, making only links (things that can be opened in a new tab) have the style is a useful affordance in web apps.

Ok, interesting, so with this, what I understand of the updated pros vs. cons of no cursor: pointer:

Pros:

• No distractions of a cursor change (thought this feels limited)
• Clarity of what a link is (though most people don't open links in new tabs, a link opens in the same tab vs. a button is almost the same thing nowadays. People can infer from the context what a link is and what a button is. The previous navigation function might be more annoying for people to know when they can use it, but also, it's common for non link, like dialog button to trigger history change, so it's already hard to know what you can undo).

Cons:

• End-user expectations
• Clarity of what can be interacted with, and what can't (using the hover effect can help with this, but it feels like it can be hard to spot as a diff, and it's not easy to apply everywhere, hence it gets often missed by developers).

Cons weight feels >> Pros on my end 😄

6. https://x.com/colmtuite/status/1933543454996365477

Yeah, ok, I think this is aligned with the pros & cons above ⬆️.

6. I think with good hover styles, it's not necessary to use and makes the UI feel less premium/native and cheapens it. JUI looks & feels incredible without using it; adding it would make it feel cheap.

If we can guarantee those four, then, definitely, I agree:

1. The user has a great screen
2. The user has great eyesight
3. The developer is carefully adding a distinguishable hover style to all the elements
4. End-users don't complain too much about the lack of a cursor.

The problem is that I'm thinking of, e.g. my mother. case 1 and 2. fails, having seen her laptop screen and how she uses it, I expect her to fail to use this:

Screen.Recording.2025-09-19.at.01.57.16.mov

I'm thinking of how average developer team that will use Joy UI, case 3 feels like it will fail.
I'm thinking of how the average end-user will expect the UI to behave; case 4 will fail. So it's why it feels that it doesn't work in most cases. But if you are a product like Linear, then ok, sure 1, 2, 3, 4 are there (thought in 4 I used their setting to set cursor: pointer back, I was annoyed to not have it, it feel too brittle, I like to know, for sure 😆).

But anyway, Base UI users are more likely to satisfy those four points, so maybe it's for the best here 🤷‍♂️.

10. I wouldn't say it's "broken"; it's just a different style to avoid duplicate scrollbars. GitHub for instance uses it right on the issue sidebar:

I would also categorize GitHub as annoying 😄. This feels correct IMHO: https://www.radix-ui.com/primitives/docs/components/slider, I can explore the TOC for what could be a better section to read, without losing the scroll position of what I currently plan to read next

Screen.Recording.2025-09-19.at.02.04.16.mov

[atomiks]

It's annoying when I encounter a web app that has links that look like buttons, but only some of them open in new tabs, and you can't tell which. I use it all the time actually.

Also, hover styles probably aren't even necessary in many cases. The OS often doesn't use hover styles. I don't think this means users can't use their own OS 😄 This applies to checkboxes as well

Screen.Recording.2025-09-19.at.10.18.14.am.mov

I can explore the TOC for what could be a better section to read, without losing the scroll position of what I currently plan to read next

Yes, I suppose it's ok if it's a custom scrollbar; the default one (or default overlay ones) look terrible. My Floating UI does that and it's much worse than Base UI's docs:

Screen.Recording.2025-09-19.at.10.24.21.am.mov

[oliviertassinari]

6. It's annoying when I encounter a web app that has links that look like buttons, but only some of them open in new tabs, and you can't tell which. I use it all the time actually.

Going off topic: this, omg, it's one of the biggest pain I have on the web, I don't understand how people keep implementing links that don't support opening in new tabs. I see the URL changing, so I know it's a link, but it navigates in the same tab, horrible 🙈.

6. hover styles probably aren't even necessary in many cases. The OS often doesn't use hover styles

I touched on this in the initial comment. While not great, I think it only works for the OS because everything follows the same pattern, and users learn it once. It's not 296 different patterns to learn, one for each website you go to (I have 296 domain names with passwords saved for them).

10. My Floating UI does that and it's much worse than Base UI's docs:

So it feels worse visually on Floating UI, but the behavior feels better. Radix Primitives gets the best of the two.