[docs] Final polish on Base docs - formatting and style consistency by mapache-salvaje · Pull Request #33156 · mui/material-ui

mapache-salvaje · 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 🙌

mapache-salvaje · 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

👍

mapache-salvaje · 2022-07-20T20:59:24Z

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

mapache-salvaje · 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

+## Introduction

-```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

+<p class="description">The ClickAwayListener component detects when a click event happens outside of its child element.</p>

-`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

+To make your badge accessible, you must provide a full description with `aria-label`, as shown in the demo below:

-{{"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>

mapache-salvaje 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

mapache-salvaje added docs Improvements or additions to the documentation. package: @mui/base Specific to @mui/base (legacy). labels Jun 15, 2022

mapache-salvaje requested review from michaldudak, mnajdova and oliviertassinari June 15, 2022 05:18

merge master

387e9e6

mapache-salvaje requested review from danilo-leal, michaldudak, mnajdova, oliviertassinari and siriwatknp and removed request for michaldudak and mnajdova 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

mapache-salvaje 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

mapache-salvaje 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

mapache-salvaje requested a review from mnajdova July 20, 2022 21:07

mapache-salvaje merged commit d207a3b into mui:master Jul 22, 2022

mapache-salvaje mentioned this pull request Jul 22, 2022

[docs] Improve the Base documentation #32072

Closed

20 tasks

oliviertassinari reviewed Jul 22, 2022

View reviewed changes

mapache-salvaje 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>

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

	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).

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

		## Component size

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

Uh oh!

Conversation

mapache-salvaje commented Jun 15, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mui-bot commented Jun 15, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

danilo-leal left a comment

Choose a reason for hiding this comment

Uh oh!

mapache-salvaje commented Jul 13, 2022

Uh oh!

mnajdova left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

michaldudak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

michaldudak left a comment

Choose a reason for hiding this comment

Uh oh!

mapache-salvaje commented Jul 20, 2022

Uh oh!

mapache-salvaje commented Jul 22, 2022

Uh oh!

oliviertassinari left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oliviertassinari Jul 22, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oliviertassinari Jul 22, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oliviertassinari Aug 6, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oliviertassinari commented Nov 23, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

mapache-salvaje commented Jun 15, 2022 •

edited

Loading

mui-bot commented Jun 15, 2022 •

edited

Loading

oliviertassinari Jul 22, 2022 •

edited

Loading

oliviertassinari Jul 22, 2022 •

edited

Loading

oliviertassinari Aug 6, 2022 •

edited

Loading

oliviertassinari commented Nov 23, 2022 •

edited

Loading