[base][docs] Base UI Quickstart Guide #36717

mj12albert · 2023-03-31T11:53:31Z

I have followed (at least) the PR section of the contributing guide.

This PR addresses all 3 points from #32979 by expanding the "Quickstart" to demo how to style a button with a few styling solutions (plain CSS, Tailwind, MUI system) using mostly snippets (not complete code), though complete demos are still provided for each.

Additionally, I made a separate Quickstart page that includes the installation instructions too. Base is one package and the installation instructions will become even shorter after this, it seems a bit much to have a page just for that (despite the fact that our other docs have an Installation page, but they are all more complex).

mui-bot · 2023-03-31T11:56:11Z

Netlify deploy preview

Bundle size report

No bundle size changes

Generated by 🚫 dangerJS against 7c5f0a9

docs/src/modules/components/MarkdownDocs.js

siriwatknp

@mj12albert For the light & dark, I suggest using CSS variables instead of having 2 files with javascript theme.

It could look something like this:

const getStyles = () => ({
  --btn-background: #1f883d,
  '.mode-dark': { // class name `mode-dark` is handled by the docs
    --btn-background: #238636,
  },
  background-color: 'var(--btn-background)',
})

const GithubButtonComponent = styled(ButtonUnstyled)(getStyles);

mj12albert · 2023-04-03T12:11:46Z

Demo: https://deploy-preview-36717--material-ui.netlify.app/base/getting-started/quickstart/

I'm still polishing the demos and snippets, but the content itself is ready for an early review - please have a look and welcome feedback on anything that catches your eye! @michaldudak @mnajdova @samuelsycamore

mj12albert · 2023-04-03T12:14:32Z

@mj12albert For the light & dark, I suggest using CSS variables instead of having 2 files with javascript theme.

Let me try this – I wanted to separate them completely at first because I didn't want the snippets to show anything related to color mode at this point. But since I'm mostly not using the generated one anyway it probably doesn't matter in the end.

danilo-leal · 2023-04-03T23:44:19Z

This is looking excellent, Albert ⎯ excited to see it shaping up! To start off, one high-level thing I thought it'd be better is separating the Tutorial from the Installation page, having it be a standalone page as it is with Joy. What do you think?

mj12albert · 2023-04-04T09:28:51Z

This is looking excellent, Albert ⎯ excited to see it shaping up! To start off, one high-level thing I thought it'd be better is separating the Tutorial from the Installation page, having it be a standalone page as it is with Joy. What do you think?

🤔 Perhaps I should not use Tutorial as a heading here, I do plan to have a standalone tutorial page thats more or less equivalent to Joy, but with something more complex than a simple button ~

samuelsycamore · 2023-04-04T14:13:32Z

This is looking great @mj12albert !! Before I do a line-by-line edit, here are some big-picture notes:

I agree with @danilo-leal that we should give this content its own page, rather than living on the Installation page. Joy UI includes a "Tutorial" page in its Getting Started sequence, and we could follow that pattern here. It could also make sense on the "Usage" page. Otherwise I think this should probably fall under "How-to guides."
Notes on style—see the Writing style guide for more details:
- Avoid using "we" and "let's"—instead, center the reader and the actions they take. "Do this" instead of "We are going to so this." (Frame actions in terms of "you" instead of "us.")
- No code blocks in headers—looks cleaner that way
- Similarly, no back ticks around component names—"Unstyled Button" (or just "Button") instead of ButtonUnstyled

mj12albert · 2023-04-06T13:32:53Z

@danilo-leal @samuelsycamore I changed the heading to not use the word "tutorial" and updated the PR description to be clearer 😅

This is meant to be an expansion of the current quickstart section, and not a step-by-step tutorial like the Joy UI tutorial.

So it totally makes sense to remain on the "Usage" page.

But I wonder if Base really needs a separate installation page (just because the other packages have one). It's only one package and the page will become even shorter after #36766

PS I have done the style guide edits

danilo-leal · 2023-04-06T22:07:44Z

But I wonder if Base really needs a separate installation page (just because the other packages have one). It's only one package and the page will become even shorter after #36766

Yeah, it definitely makes me think that, given the new installation code block, the "Installation" + "Usage" page across all docs could be unified. I'd be down for this approach! It's important we keep consistency, though, regardless of which we end up picking!

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

samuelsycamore

This review is mostly just applying the style guide—the content is looking great!

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

mj12albert · 2023-04-28T09:56:13Z

@mui/core bumping this for a re-review, I think it should be good to go ~ 😬

danilo-leal

Looks great overall! Awesome job 🤙
Left just a tiny comment there.

danilo-leal · 2023-04-28T12:20:01Z

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

+## Implementing a Button
+
+This is a quick tutorial that goes through the basics of using and styling Base UI components by replicating a button from GitHub's UI, using their [Primer design system](https://primer.style) as a reference.
+Base UI components help you abstract away low-level UI implementation details such as accessibility patterns, cross-browser compatibility, event handling, and more, while remaining unopinionated about styling, giving you complete control over your app's CSS.


Suggested change

Base UI components help you abstract away low-level UI implementation details such as accessibility patterns, cross-browser compatibility, event handling, and more, while remaining unopinionated about styling, giving you complete control over your app's CSS.

### Advantages of using Base UI

Base UI components help you abstract away low-level UI implementation details such as accessibility patterns, cross-browser compatibility, event handling, and more, while remaining unopinionated about styling, giving you complete control over your app's CSS.

Was a bit hesitant to suggest this on this page, feeling like it could be out of place, but I think a title here to make this paragraph stand out a bit more would be helpful. Not married to it but what do y'all think? @mj12albert + @samuelsycamore

Not a bad idea. I think I'd go with something like "Why Base UI?" or "Why use a Base UI Button?" But you could also cut the section entirely and the piece would be fine.

I'd be down for placing this paragraph somewhere else, folks might be convinced of using Base UI already if they're diving into the Quickstart doc. But if we were to keep it, also down for your title suggestions there 🤙

Let me take it out for now, and we can add it separately to the Overview page as Sam previously suggested !

michaldudak

It looks good! Just one small remark from me.

michaldudak · 2023-04-28T12:23:26Z

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

+
+### Components and hooks
+
+Base UI provides a Button component and a `useButton` hook.


Suggested change

Base UI provides a Button component and a `useButton` hook.

Base UI provides a Button component and a useButton hook.

or "a Button component and a useButton hook"

@michaldudak according to the Style Guide, the way it's written currently is correct. (Of course it can always be changed as we see fit.)

If you wanted to put both in backticks, the preferred style would be <Button /> and useButton. If you think that neither of them should have backticks, then there are many other instances of useSomeHook throughout the Base and Joy docs that we'll want to update to remove backticks.

Let's go with <Button /> here as it's the first occurrence of the button component, subsequent ones will have no backtick

mj12albert commented Mar 31, 2023

View reviewed changes

docs/src/modules/components/MarkdownDocs.js Outdated Show resolved Hide resolved

mj12albert added docs Improvements or additions to the documentation package: base-ui Specific to @mui/base labels Mar 31, 2023

mj12albert force-pushed the base/quickstart branch 4 times, most recently from 33e6381 to 84fba4a Compare April 2, 2023 14:33

siriwatknp reviewed Apr 3, 2023

View reviewed changes

mj12albert changed the title ~~[WIP][base][docs] Base Quickstart~~ [base][docs] Base Quickstart Apr 3, 2023

mj12albert marked this pull request as ready for review April 3, 2023 12:12

mj12albert force-pushed the base/quickstart branch from 84fba4a to d947426 Compare April 4, 2023 10:59

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

mj12albert force-pushed the base/quickstart branch from 0168b0e to 294da4e Compare April 6, 2023 11:09

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Apr 6, 2023

mj12albert requested a review from samuelsycamore April 6, 2023 13:33

danilo-leal reviewed Apr 6, 2023

View reviewed changes

docs/data/base/getting-started/quickstart/quickstart.md Outdated Show resolved Hide resolved

samuelsycamore reviewed Apr 8, 2023

View reviewed changes

mj12albert requested review from mnajdova and michaldudak April 10, 2023 13:04

michaldudak reviewed Apr 13, 2023

View reviewed changes

docs/data/base/getting-started/quickstart/quickstart.md Outdated Show resolved Hide resolved

docs/data/base/getting-started/quickstart/quickstart.md Outdated Show resolved Hide resolved

This was referenced Apr 14, 2023

[Base][Button] Allow useButton parameters to be completely optional #36879

Closed

[Base][docs] ref is not required for useButton #36880

Closed

mj12albert force-pushed the base/quickstart branch from f4ee49c to fea4f9c Compare April 28, 2023 09:40

mj12albert requested review from mnajdova and michaldudak April 28, 2023 09:54

danilo-leal approved these changes Apr 28, 2023

View reviewed changes

michaldudak approved these changes Apr 28, 2023

View reviewed changes

mj12albert added 19 commits May 1, 2023 15:42

Enable MarkdownDocs to exclude demos based on current color mode

5b5a41e

Quickstart tutorial

76f91ec

Add Tailwind section

cbbca5e

Revise MUI System section

3457789

Fix links

ab61ef2

A round of edits

89f8dea

Add MUI system theming snippet

12552f7

Remove unused code

8d85de0

Update plain css demo

8c77c34

Update Tailwind demo

9d99109

Revert changes to MarkdownDocs

dae7e19

More content edits

bb5114f

Fixes and content revision from code review

05f51bf

No need to involve a ref in these demos

f98a033

More fixes

9719713

Add sentence explaining benefits of Base components

e6fe29e

More copy edits

8467f79

Remove Unstyled suffix

ad2f57e

Final edits

7c5f0a9

mj12albert force-pushed the base/quickstart branch from fea4f9c to 7c5f0a9 Compare May 1, 2023 07:47

mj12albert changed the title ~~[base][docs] Base UI Quickstart~~ [base][docs] Base UI Quickstart Guide May 1, 2023

mj12albert merged commit 5b6e6c5 into mui:master May 1, 2023
18 checks passed

binh1298 pushed a commit to binh1298/material-ui that referenced this pull request May 17, 2023

[base][docs] Add Base UI Quickstart Guide (mui#36717)

bb332aa

mj12albert deleted the base/quickstart branch August 28, 2023 07:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[base][docs] Base UI Quickstart Guide #36717

[base][docs] Base UI Quickstart Guide #36717

mj12albert commented Mar 31, 2023 •

edited

mui-bot commented Mar 31, 2023 •

edited

siriwatknp left a comment •

edited

mj12albert commented Apr 3, 2023

mj12albert commented Apr 3, 2023

danilo-leal commented Apr 3, 2023

mj12albert commented Apr 4, 2023

samuelsycamore commented Apr 4, 2023

mj12albert commented Apr 6, 2023

danilo-leal commented Apr 6, 2023

samuelsycamore left a comment

mj12albert commented Apr 28, 2023

danilo-leal left a comment

danilo-leal Apr 28, 2023 •

edited

samuelsycamore Apr 28, 2023

danilo-leal Apr 28, 2023

mj12albert May 1, 2023

michaldudak left a comment

michaldudak Apr 28, 2023

samuelsycamore Apr 28, 2023

mj12albert Apr 28, 2023


		### Components and hooks

		Base UI provides a Button component and a `useButton` hook.

[base][docs] Base UI Quickstart Guide #36717

[base][docs] Base UI Quickstart Guide #36717

Conversation

mj12albert commented Mar 31, 2023 • edited

mui-bot commented Mar 31, 2023 • edited

Netlify deploy preview

Bundle size report

siriwatknp left a comment • edited

Choose a reason for hiding this comment

mj12albert commented Apr 3, 2023

mj12albert commented Apr 3, 2023

danilo-leal commented Apr 3, 2023

mj12albert commented Apr 4, 2023

samuelsycamore commented Apr 4, 2023

mj12albert commented Apr 6, 2023

danilo-leal commented Apr 6, 2023

samuelsycamore left a comment

Choose a reason for hiding this comment

mj12albert commented Apr 28, 2023

danilo-leal left a comment

Choose a reason for hiding this comment

danilo-leal Apr 28, 2023 • edited

Choose a reason for hiding this comment

samuelsycamore Apr 28, 2023

Choose a reason for hiding this comment

danilo-leal Apr 28, 2023

Choose a reason for hiding this comment

mj12albert May 1, 2023

Choose a reason for hiding this comment

michaldudak left a comment

Choose a reason for hiding this comment

michaldudak Apr 28, 2023

Choose a reason for hiding this comment

samuelsycamore Apr 28, 2023

Choose a reason for hiding this comment

mj12albert Apr 28, 2023

Choose a reason for hiding this comment

mj12albert commented Mar 31, 2023 •

edited

mui-bot commented Mar 31, 2023 •

edited

siriwatknp left a comment •

edited

danilo-leal Apr 28, 2023 •

edited