[docs] Tweaks on getting started page #329

colmtuite · 2024-04-19T06:32:56Z

A quick clean-up of the getting started pages to focus things a bit more.

Shortened some heading
Removed some links to redacted components.
Removed “headless” in a few places.
Removed some technical support nonsense and Material UI targeted stuff from the support page.
Added a tiny install and import tutorial.
Explained a bit about our main goal/vision.

Preview: https://deploy-preview-329--base-ui.netlify.app/base-ui/getting-started/

github-actions · 2024-04-19T06:33:19Z

docs/data/base/getting-started/overview/overview.md

-Base UI is a library of unstyled React UI components and hooks.
-These components were extracted from [Material UI](https://mui.com/material-ui/), and are now available as a standalone package.
-They feature the same robust engineering but without implementing Material Design.
+Our goal with Base UI is to provide a complete set of accessible UI components but with maximum flexibility. We want to facilitate creative user interfaces and help teams ship high-quality products.


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.We] Try to avoid using first-person plural like 'Our'.

github-actions · 2024-04-19T06:33:20Z

docs/data/base/getting-started/overview/overview.md

-Base UI is a library of unstyled React UI components and hooks.
-These components were extracted from [Material UI](https://mui.com/material-ui/), and are now available as a standalone package.
-They feature the same robust engineering but without implementing Material Design.
+Our goal with Base UI is to provide a complete set of accessible UI components but with maximum flexibility. We want to facilitate creative user interfaces and help teams ship high-quality products.


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.We] Try to avoid using first-person plural like 'We'.

github-actions · 2024-04-19T06:33:20Z

docs/data/base/getting-started/overview/overview.md


-Base UI includes prebuilt components with production-ready functionality, along with low-level hooks for transferring that functionality to other components.
+Base UI components are React-based, are built by the same team that created [Material UI](https://mui.com/material-ui/), and feature the same robust engineering but without any styling.


🚫 [vale] _{reported by reviewdog 🐶}
[MUI.MuiBrandName] Use a non-breaking space (option+space on Mac, Alt+0160 on Windows or AltGr+Space on Linux, instead of space) for brand name ('Base UI' instead of 'Base UI')

github-actions · 2024-04-19T06:33:20Z

docs/data/base/getting-started/overview/overview.md


-With Base UI, you can rapidly build on top of our foundational components using any styling solution you choose—no need to override any default style engine or theme.
+With Base UI, you can rapidly build on top of our foundational components using any styling or animation solution you choose.


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.We] Try to avoid using first-person plural like 'our'.

github-actions · 2024-04-19T06:33:20Z

docs/data/base/getting-started/overview/overview.md

-Base UI features many of the same components as [Material UI](https://mui.com/material-ui/getting-started/), but without the Material Design implementation.
-
-Base UI is not packaged with any default theme or built-in style engine.
+Unlike Material UI, Base UI does not include any default theme or built-in style engine.


🚫 [vale] _{reported by reviewdog 🐶}
[MUI.MuiBrandName] Use a non-breaking space (option+space on Mac, Alt+0160 on Windows or AltGr+Space on Linux, instead of space) for brand name ('Material UI' instead of 'Material UI')

github-actions · 2024-04-19T06:33:20Z

docs/data/base/getting-started/overview/overview.md

 This makes it a great choice if you need complete control over how your app's CSS is implemented.

-You could think of Base UI as the "skeletal" or "headless" version of Material UI—in fact, future versions of Material UI will gradually adopt these components and hooks for their foundational structure.
+Future versions of Material UI will gradually adopt Base UI as its foundation.


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.Will] Avoid using 'will'.

github-actions · 2024-04-19T06:33:20Z

docs/data/base/getting-started/overview/overview.md

 This makes it a great choice if you need complete control over how your app's CSS is implemented.

-You could think of Base UI as the "skeletal" or "headless" version of Material UI—in fact, future versions of Material UI will gradually adopt these components and hooks for their foundational structure.
+Future versions of Material UI will gradually adopt Base UI as its foundation.


🚫 [vale] _{reported by reviewdog 🐶}
[MUI.MuiBrandName] Use a non-breaking space (option+space on Mac, Alt+0160 on Windows or AltGr+Space on Linux, instead of space) for brand name ('Base UI' instead of 'Base UI')

github-actions · 2024-04-19T06:33:20Z

docs/data/base/getting-started/quickstart/quickstart.md

+
+## Style your component
+
+Base UI makes no assumptions about style at all. You're free to style your components


🚫 [vale] _{reported by reviewdog 🐶}
[MUI.MuiBrandName] Use a non-breaking space (option+space on Mac, Alt+0160 on Windows or AltGr+Space on Linux, instead of space) for brand name ('Base UI' instead of 'Base UI')

github-actions · 2024-04-19T06:36:38Z

docs/data/base/getting-started/overview/overview.md

 This makes it a great choice if you need complete control over how your app's CSS is implemented.

-You could think of Base UI as the "skeletal" or "headless" version of Material UI—in fact, future versions of Material UI will gradually adopt these components and hooks for their foundational structure.
+Future versions of Material UI will gradually adopt Base UI as its foundation.


⚠️ [vale] _{reported by reviewdog 🐶}
[Google.Will] Avoid using 'will'.

oliviertassinari · 2024-04-21T12:22:14Z

docs/data/base/getting-started/support/support.md

@@ -52,12 +52,6 @@ You can search through existing questions and answers to see if someone has aske



On the support page conent, I think that all open-source projects should have the same structure, unless there is a strong reason not to:

Tidelift: I don't see a reason for this to be different, so either to delete it everywhere or keep it everywhere. Since Tidelift pays us, it would make sense to me to have it, but maybe to reshape.

Custom work: same incentive as 1. The soft objective was to offer people the open to shuffle the roadmap if some folks are willing to spend enough for it, but the main idea was for organizations to feel like they could spend $ to get unstuck, vs. staying stuck. I don't see strong arguments either way (remove it everywhere or add it everywhere).

Social media. Ok, I guess maybe only MUI X would make sense to post on LinkedIn? cc @joserodolfofreitas. We would then update all the other products cc @samuelsycamore

Technical support. same incentive as 1. The problem is that MUI X paid clients ask about paid support on Base UI which isn't included in their plan today, we needed this to make it clear.

I reverted 1, 2, 4.

On 3, I don't think there's a benefit to posting on LinkedIn about Base UI, or a benefit to linking to it. So I left that out.

oliviertassinari

Having a quick look

oliviertassinari · 2024-04-21T14:45:07Z

docs/data/base/getting-started/overview/overview.md

-# Base UI - Overview
+# Overview


I think we added Base UI as a cheap workaround waiting to fix the header to make it clear it's not some other library:

If we make this change, we do no longer need a custom SEO <title>, we should remove:

--- title: Overview ---

oliviertassinari · 2024-04-21T14:46:30Z

docs/data/base/getting-started/quickstart/quickstart.md

+
+```jsx
+import * as React from 'react';
+import * as NumberField from '@base_ui/react/NumberField';


We used

Suggested change

import * as NumberField from '@base_ui/react/NumberField';

import * as BaseNumberField from '@base_ui/react/NumberField';

in the demos of the docs, maybe it's not relevant here.

Which docs? The current demos use import * as NumberField from '@base_ui/react/NumberField'; as far as I can see.

oliviertassinari · 2024-04-21T14:47:54Z

docs/data/base/getting-started/quickstart/quickstart.md

+const NumberFieldDemo = () => (
+  <NumberField.Root>
+    <NumberField.Group>
+      <NumberField.Decrement />
+      <NumberField.Input />
+      <NumberField.Increment />
+    </NumberField.Group>
+  </NumberField.Root>
+);
+
+export default NumberFieldDemo;


If we follow the convention in the docs, we would use:

Suggested change

const NumberFieldDemo = () => (

<NumberField.Root>

<NumberField.Group>

<NumberField.Decrement />

<NumberField.Input />

<NumberField.Increment />

</NumberField.Group>

</NumberField.Root>

);

export default NumberFieldDemo;

export default function NumberFieldDemo() {

return (

<NumberField.Root>

<NumberField.Group>

<NumberField.Decrement />

<NumberField.Input />

<NumberField.Increment />

</NumberField.Group>

</NumberField.Root>

);

}

the main upside is to make it easier to add hooks, not having to refactor. But since it's not a demo, same point as a above, maybe it's a case where we want to make an exception.

Yep make an exception imo. Hooks are hugely deprioritised in new Base UI, so we should focus on simplicity in this example.

colmtuite added 5 commits April 19, 2024 06:55

Tweaked overview copy

68a1947

Add demo to quickstart

152f104

Remove redundant a11y content

831f41b

Clean up support page

172a3f7

Remove meta tag nonsense

2f99980

colmtuite added the website Related to the marketing pages label Apr 19, 2024

github-actions bot reviewed Apr 19, 2024

View reviewed changes

colmtuite requested review from michaldudak and atomiks April 19, 2024 06:33

Try to make bot happy

22cbaa3

github-actions bot reviewed Apr 19, 2024

View reviewed changes

oliviertassinari added docs Improvements or additions to the documentation and removed website Related to the marketing pages labels Apr 21, 2024

oliviertassinari changed the title ~~[website] Docs getting started tweaks~~ [docs] Tweaks on getting started page Apr 21, 2024

oliviertassinari reviewed Apr 21, 2024

View reviewed changes

colmtuite added 3 commits May 2, 2024 02:46

Merge branch 'master' into colm/rewrite-getting-started

ca09137

Revert support page

2b14d2e

Removed redundant page title

499d0ca

colmtuite requested a review from oliviertassinari May 2, 2024 02:06

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label May 2, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Tweaks on getting started page #329

[docs] Tweaks on getting started page #329

colmtuite commented Apr 19, 2024 •

edited by oliviertassinari

github-actions bot Apr 19, 2024

github-actions bot Apr 19, 2024

github-actions bot Apr 19, 2024

github-actions bot Apr 19, 2024

github-actions bot Apr 19, 2024

github-actions bot Apr 19, 2024

github-actions bot Apr 19, 2024

github-actions bot Apr 19, 2024

github-actions bot Apr 19, 2024

oliviertassinari Apr 21, 2024 •

edited

colmtuite May 2, 2024

oliviertassinari left a comment •

edited

oliviertassinari Apr 21, 2024 •

edited

oliviertassinari Apr 21, 2024

colmtuite May 2, 2024

oliviertassinari Apr 21, 2024

colmtuite May 2, 2024


		Base UI includes prebuilt components with production-ready functionality, along with low-level hooks for transferring that functionality to other components.
		Base UI components are React-based, are built by the same team that created [Material UI](https://mui.com/material-ui/), and feature the same robust engineering but without any styling.


		With Base UI, you can rapidly build on top of our foundational components using any styling solution you choose—no need to override any default style engine or theme.
		With Base UI, you can rapidly build on top of our foundational components using any styling or animation solution you choose.


		## Style your component

		Base UI makes no assumptions about style at all. You're free to style your components

		@@ -52,12 +52,6 @@ You can search through existing questions and answers to see if someone has aske

	import * as NumberField from '@base_ui/react/NumberField';
	import * as BaseNumberField from '@base_ui/react/NumberField';

[docs] Tweaks on getting started page #329

Are you sure you want to change the base?

[docs] Tweaks on getting started page #329

Conversation

colmtuite commented Apr 19, 2024 • edited by oliviertassinari

github-actions bot Apr 19, 2024

Choose a reason for hiding this comment

github-actions bot Apr 19, 2024

Choose a reason for hiding this comment

github-actions bot Apr 19, 2024

Choose a reason for hiding this comment

github-actions bot Apr 19, 2024

Choose a reason for hiding this comment

github-actions bot Apr 19, 2024

Choose a reason for hiding this comment

github-actions bot Apr 19, 2024

Choose a reason for hiding this comment

github-actions bot Apr 19, 2024

Choose a reason for hiding this comment

github-actions bot Apr 19, 2024

Choose a reason for hiding this comment

github-actions bot Apr 19, 2024

Choose a reason for hiding this comment

oliviertassinari Apr 21, 2024 • edited

Choose a reason for hiding this comment

colmtuite May 2, 2024

Choose a reason for hiding this comment

oliviertassinari left a comment • edited

Choose a reason for hiding this comment

oliviertassinari Apr 21, 2024 • edited

Choose a reason for hiding this comment

oliviertassinari Apr 21, 2024

Choose a reason for hiding this comment

colmtuite May 2, 2024

Choose a reason for hiding this comment

oliviertassinari Apr 21, 2024

Choose a reason for hiding this comment

colmtuite May 2, 2024

Choose a reason for hiding this comment

colmtuite commented Apr 19, 2024 •

edited by oliviertassinari

oliviertassinari Apr 21, 2024 •

edited

oliviertassinari left a comment •

edited

oliviertassinari Apr 21, 2024 •

edited