[docs] Improvement ideas for Base UI docs

[mapache-salvaje]

This is an umbrella issue to gather together the documentation projects and tasks we'd like to complete before the stable release of Base UI (or very soon thereafter).

As decided in the Core documentation forum, we will prioritize improvements to the Base UI docs. These improvements include:

• [base-ui][docs] Create more examples for Base UI material-ui#36193
• revamping the Getting Started section of the docs
  • making the Overview page more visually appealing; sharpening the value proposition - creating a Why Base UI? page to follow the Overview
• one final round of editorial polishing: fixing broken header links, minor grammar and style inconsistencies
  • [docs][base-ui] Revise the structure of the Component docs material-ui#38529
  • [docs][base-ui] Structure and style revisions for Component docs material-ui#38826
• adding Introduction demos where they're missing, and removing Basics demos when they're duplicates of Intro demos

One key improvement we still need to deliberate on is how to present demos/examples of Base UI components implemented in real(istic) use cases (rather than isolated in feature demos), like we do with Templates for Material UI and Joy UI. Templates as such don't necessarily make sense for Base UI, because it doesn't really "look" or "feel" like anything special out of the box with no styles, and it doesn't come packaged with any layout components. Plus, it kind of misses the purpose of Base UI, which is about maximizing freedom and flexibility—meaning we probably don't want to impose any style opinions on the developer.

Ideas floated include:

1. component gallery - showing off (any and all) design system implementations - akin to a project showcase
2. recipe kits - possibly implementing Joy Design (or else a very minimal but still production-ready system) via an "own your code" pattern à la shadcn/ui - but then what styling solution do we choose and why? (this may not be feasible to accomplish before the stable but is worth considering)
3. design system scaffold - optimized for implementing a custom design system with Storybook and other relevant tooling already installed, with very minimal style decisions made
4. all of the above? none of the above? something else entirely? 🙃

I'll create separate issues and PRs for the improvements we've already settled on.

I'd love to hear people's thoughts about the latter half. Assuming we'll never have time to do them all—what would be most useful to the community when they show up on day one of the stable release? That's what we want to do!

Note that the scope here is limited to documentation content rather than infrastructure.

[oliviertassinari]

Ideas floated include:

1. Yes, big 👍. But maybe to rename to "design system gallery" or equivalent. I doubt we will see real one off components. Today, we can list Joy UI, tomorrow hopefully Material UI. In the future, a showcase like https://storybook.js.org/showcase/ would be such a powerful marketing tool.
2. This might be a lot of receipt kits, maybe instructions would be enough. But yes, I think that we need to reduce the friction to create a new project with the Joy Design theme of Base UI (assuming we build this).
3. This could be very close to 2. To consider if there will be people needing this (it could be kept for internal use cases). For example, maybe advanced users will prefer to do it their way.

[mapache-salvaje]

With mui/material-ui#38826 merged, I feel comfortable saying that the Base UI Component docs content is officially "good enough" for the stable release. 🎉🫡🚀🤝😁

The last few tasks I'd still like to tackle before the stable release include:

• adding a few more basic boilerplate examples, and an Examples page for linking to them
• adding missing Introduction demos, and removing redundant Basic demos, cc @mnajdova
• revising the Overview / Why Base UI content

[mapache-salvaje]

I think #43 should resolve the discussion around how to showcase demo projects/examples/use cases, at least for now.

[michaldudak]

@colmtuite, @vladmoroz, FYI, we discussed this a long time ago (regarding the old Base UI docs). Perhaps something to consider in the new docs as well?