[docs] Final polish on Base docs - formatting and style consistency #33156

samuelsycamore · 2022-06-15T05:13:13Z

https://deploy-preview-33156--material-ui.netlify.app/base/react-badge/

This is the final (?) follow up to #32072 to polish the existing Base documentation and implement consistent formatting and style.

This PR covers all component pages in the Base docs, as well as one tiny tweak to the Overview page to fix the title. Changes include:

removing HTML from <p> descriptions for SEO
reverting ClickAwayListener's page title for SEO
removing (redundant) bundle size info where present (it's already in the ComponentLinkHeader)
adding lead-in descriptions for demos, explaining what's going on and pointing out important bits to notice
improving and standardizing headers for better TOC navigation
formalizing Introduction and Anatomy sections
implementing universal formatting
adding new callouts
cleaning up random typos and style and grammar errors
expanding and revising content that was still unclear after the last pass

The primary purpose of this final round of polishing is to establish a universal template for component pages that we could use when writing and revising pages going forward. It looks like this:

# Name of component

<p>description</p>

## Introduction

### Features (optional)

- 🥉 only included when there are at least 3 interesting things to point out

{{ComponentLinkHeader}}

## Component(s)

### Usage

### Basics

### Anatomy

### Slot props

## Hook(s) (where applicable)

### Noteworthy features or examples

## Customization

### Props and features that apply to both components and hooks

## Accessibility

## API

Once we're satisfied with this template, we can move on to apply it to all component pages across MUI's products. I believe this will significantly improve the overall experience of our docs.

This final pass turned out to be a much bigger undertaking than I anticipated so I'm sure there are tiny details I've missed! The big-picture formatting is what I'm most concerned with here.

mui-bot · 2022-06-15T05:16:05Z

No bundle size changes

Generated by 🚫 dangerJS against 8f485ec

danilo-leal

Looks amazing to me－scanned it through a couple of times and nothing stood out.
Awesome work 🙌

samuelsycamore · 2022-07-13T16:49:38Z

Thanks @danilo-leal! Maybe @mnajdova and/or @michaldudak could give this one last review to make sure it's all good before merging? It's a big one so I want to make sure we have many sets of eyes on it.

mnajdova

I could just find two issues around missing slots in the slots section. The rest look splendid :)

docs/data/base/components/slider/slider.md

docs/data/base/components/table-pagination/table-pagination.md

michaldudak

Great work, @samuelsycamore, I really like it! I do have just two comments.

michaldudak · 2022-07-15T10:00:40Z

docs/data/base/components/badge/badge.md

+Hooks _do not_ support [slot props](#slot-props), but they do support [customization props](#customization).
+
+:::info
+Hooks give you the most room for customization, but require more work to implement.


I recently realized another use case for hooks - if you're building a component library that can be customized further by developers (e.g. using the componentsProps prop), use hooks. Unstyled components are better suited to build "closed" libraries (that's why we use hooks to build Joy components, for example).

Do you think this is worth mentioning on all pages? Or maybe it would be better suited for the Usage page?

I suppose having it just on the Usage page should be enough.

Sounds good. I'll add it to #33272

docs/data/base/components/badge/badge.md

michaldudak

👍

samuelsycamore · 2022-07-20T20:59:24Z

Just applied the suggestions from @mnajdova's last review. I think this is ready to go finally! 🤞

samuelsycamore · 2022-07-22T17:40:17Z

I think it's time to merge this beast! There will always be more room for improvement, but I think we've established a very strong template here that I'd like to start applying across all product documentation.

oliviertassinari

A great step forward 👍

oliviertassinari · 2022-07-22T22:59:01Z

docs/data/base/components/badge/badge.md

+Hooks give you the most room for customization, but require more work to implement.
+With hooks, you can take full control over how your component is rendered, and define all the custom props and CSS classes you need.
+
+You may not need to use hooks unless you find that you're limited by the customization options of their component counterparts—for instance, if your component requires significantly different [structure](#component-slots).


Would this be better?

Suggested change

You may not need to use hooks unless you find that you're limited by the customization options of their component counterparts—for instance, if your component requires significantly different [structure](#component-slots).

You may not need to use hooks unless you find that you're limited by the customization options of their component counterparts—for instance, if your component requires a significantly different [structure](#component-slots).

oliviertassinari · 2022-07-22T23:25:41Z

docs/data/base/components/button/button.md


-```js
+`ButtonUnstyled` replaces the native HTML `<button>` element.


It could be interesting to explain why (The value proposition for a developer to replace a native button) Or maybe it's better to say "extends" it.

oliviertassinari · 2022-07-22T23:28:25Z

docs/data/base/components/click-away-listener/click-away-listener.md


-`ClickAwayListener` is a utility component that listens for click events outside of its child.
+## Introduction


Is the plan to add this ## Introduction in the rest of the docs? It seems that in Material UI we have systematically skipped it (the introduction content was left to be described under the h1), it's not consistent.

Yes, I think we should apply this format across the Material UI docs as well.

oliviertassinari · 2022-07-22T23:31:12Z

docs/data/base/components/badge/badge.md


-{{"demo": "AccessibleBadges.js", "defaultCodeOpen": false}}
+{{"demo": "AccessibleBadges.js"}}


I think that we could keep the preview disabled. It doesn't explain how the feature works, so I feel noise for developers

Suggested change

{{"demo": "AccessibleBadges.js"}}

{{"demo": "AccessibleBadges.js", "defaultCodeOpen": false}}

oliviertassinari · 2022-07-22T23:31:47Z

docs/data/base/components/trap-focus/trap-focus.md

-## Component size
-
- 📦 [2.0 kB gzipped](https://bundlephobia.com/package/@mui/base@latest)


In the future, we could use Bundlephobia, https://bundlephobia.com/api/exports-sizes?package=@mui/base@5.0.0-alpha.90 and show the value associated with what we export,

pastelsky/bundlephobia#389

oliviertassinari · 2022-07-22T23:40:20Z

docs/data/base/components/badge/badge.md

 ```

-{{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
+### Basics


When landing on https://deploy-preview-33156--material-ui.netlify.app/base/react-badge you need to scroll a lot before you can find an actual demo of the component or one that you can copy and paste into your project. It contrasts with what we had before https://mui.com/base/react-badge/ or https://www.radix-ui.com/docs/primitives/components/tooltip. So I conclude that we miss an introduction demo, maybe under ### Basics?

This is reinforced by this feedback https://mui-org.slack.com/archives/C0170JAM7ML/p1659457895980239?thread_ts=1658732401.469249&cid=C0170JAM7ML

That is a good point. We could definitely use a basic intro demo here, and probably for some other Base components as well.

I will raise this discussion at the next team meeting, seeing

https://reshaped.so/content/docs/components/switch

https://headlessui.com/react/switch

https://www.radix-ui.com/docs/primitives/components/switch

it feels nice to see a full demo first before everything else. It can even then turn into an SEO hack https://www.notion.so/mui-org/Page-image-generator-75bc177fefe64c0b899a42a6f919a907.

oliviertassinari · 2022-11-23T22:09:35Z

Regarding #33156 (comment), Radix seems to do it:

cc @michaldudak, I think it's great to communicate to the developers that bundle size is a key constraint in how components are designed.

…ui#33156) Co-authored-by: Olivier Tassinari <olivier.tassinari@gmail.com>

samuelsycamore added 24 commits June 14, 2022 17:13

fixes seo descriptions

b25aac5

better badge page

60c7b09

better select page, minor tweaks to badge

f78c1f7

better modal doc

faa5479

fix overview title, popper wip

f0e814e

better popper

8907b17

better nossr

3bfbee7

better input doc

1cf8a39

form control wip

1a37b54

prettier

92ab404

better form control doc

0a43be4

better trap focus doc

e3e73f5

better switch

b33f538

better slider

33a8f84

portal update

0962d4b

updated button

b972bfa

tablepag update

3306811

update clickaway

e9f972a

updated tabs

4f65b04

tweak so prettier will play nice

2d9af7b

update textarea

d69cf1b

tabs fix

9b749ed

prettier, markdownlint, i18n

36b20c6

merge master

99ab8dd

samuelsycamore added docs Improvements or additions to the documentation package: base-ui Specific to @mui/base labels Jun 15, 2022

samuelsycamore requested review from mnajdova, michaldudak and oliviertassinari June 15, 2022 05:18

merge master

387e9e6

samuelsycamore requested review from oliviertassinari, michaldudak, mnajdova, siriwatknp and danilo-leal and removed request for mnajdova and michaldudak July 11, 2022 02:22

danilo-leal approved these changes Jul 12, 2022

View reviewed changes

mnajdova reviewed Jul 14, 2022

View reviewed changes

docs/data/base/components/slider/slider.md Show resolved Hide resolved

docs/data/base/components/table-pagination/table-pagination.md Outdated Show resolved Hide resolved

michaldudak reviewed Jul 15, 2022

View reviewed changes

samuelsycamore added 2 commits July 18, 2022 13:46

merge master

bdd7cf7

rearrange usage and anatomy headers

2cd1227

michaldudak approved these changes Jul 20, 2022

View reviewed changes

samuelsycamore added 4 commits July 20, 2022 15:11

merge master

0a71943

slider revisions

c519089

markdownlint

0d4b0d1

table pagination action buttons

38cfeea

three to several

8f485ec

samuelsycamore requested a review from mnajdova July 20, 2022 21:07

samuelsycamore merged commit d207a3b into mui:master Jul 22, 2022

samuelsycamore mentioned this pull request Jul 22, 2022

[docs] Improve the Base documentation #32072

Closed

20 tasks

oliviertassinari reviewed Jul 22, 2022

View reviewed changes

samuelsycamore mentioned this pull request Aug 16, 2022

[docs] Fix interior section links in Base docs that feature hooks #33948

Merged

daniel-rabe pushed a commit to daniel-rabe/material-ui that referenced this pull request Nov 29, 2022

[docs] Final polish on Base docs - formatting and style consistency (m…

410531f

…ui#33156) Co-authored-by: Olivier Tassinari <olivier.tassinari@gmail.com>

samuelsycamore deleted the base-small-fixes branch April 3, 2024 17:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Final polish on Base docs - formatting and style consistency #33156

[docs] Final polish on Base docs - formatting and style consistency #33156

samuelsycamore commented Jun 15, 2022 •

edited

mui-bot commented Jun 15, 2022 •

edited

danilo-leal left a comment

samuelsycamore commented Jul 13, 2022

mnajdova left a comment

michaldudak left a comment

michaldudak Jul 15, 2022

samuelsycamore Jul 15, 2022

michaldudak Jul 18, 2022

samuelsycamore Jul 18, 2022

michaldudak left a comment

samuelsycamore commented Jul 20, 2022

samuelsycamore commented Jul 22, 2022

oliviertassinari left a comment

oliviertassinari Jul 22, 2022

oliviertassinari Jul 22, 2022 •

edited

oliviertassinari Jul 22, 2022

samuelsycamore Aug 2, 2022

oliviertassinari Jul 22, 2022

oliviertassinari Jul 22, 2022 •

edited

oliviertassinari Jul 22, 2022

oliviertassinari Aug 2, 2022

samuelsycamore Aug 2, 2022

oliviertassinari Aug 6, 2022 •

edited

oliviertassinari commented Nov 23, 2022 •

edited

	You may not need to use hooks unless you find that you're limited by the customization options of their component counterparts—for instance, if your component requires significantly different [structure](#component-slots).
	You may not need to use hooks unless you find that you're limited by the customization options of their component counterparts—for instance, if your component requires a significantly different [structure](#component-slots).


		```js
		`ButtonUnstyled` replaces the native HTML `<button>` element.


		`ClickAwayListener` is a utility component that listens for click events outside of its child.
		## Introduction


		{{"demo": "AccessibleBadges.js", "defaultCodeOpen": false}}
		{{"demo": "AccessibleBadges.js"}}

		## Component size

		- 📦 [2.0 kB gzipped](https://bundlephobia.com/package/@mui/base@latest)

[docs] Final polish on Base docs - formatting and style consistency #33156

[docs] Final polish on Base docs - formatting and style consistency #33156

Conversation

samuelsycamore commented Jun 15, 2022 • edited

mui-bot commented Jun 15, 2022 • edited

danilo-leal left a comment

Choose a reason for hiding this comment

samuelsycamore commented Jul 13, 2022

mnajdova left a comment

Choose a reason for hiding this comment

michaldudak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michaldudak left a comment

Choose a reason for hiding this comment

samuelsycamore commented Jul 20, 2022

samuelsycamore commented Jul 22, 2022

oliviertassinari left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oliviertassinari Jul 22, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oliviertassinari Jul 22, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oliviertassinari Aug 6, 2022 • edited

Choose a reason for hiding this comment

oliviertassinari commented Nov 23, 2022 • edited

samuelsycamore commented Jun 15, 2022 •

edited

mui-bot commented Jun 15, 2022 •

edited

oliviertassinari Jul 22, 2022 •

edited

oliviertassinari Jul 22, 2022 •

edited

oliviertassinari Aug 6, 2022 •

edited

oliviertassinari commented Nov 23, 2022 •

edited