[docs] Improve npm experience (#38906)

Signed-off-by: Olivier Tassinari <[email protected]>
Co-authored-by: Sam Sycamore <[email protected]>

README.md

@@ -1,6 +1,6 @@
 <!-- markdownlint-disable-next-line -->
 <p align="center">
-  <a href="https://mui.com/core/" rel="noopener" target="_blank"><img width="150" height="133" src="/docs/public/static/logo.svg" alt="MUI Core logo"></a>
+  <a href="https://mui.com/core/" rel="noopener" target="_blank"><img width="150" height="133" src="https://mui.com/static/logo.svg" alt="MUI Core logo"></a>
 </p>
 
 <h1 align="center">MUI Core</h1>
@@ -31,15 +31,11 @@
 
 </div>
 
-## Installation
+## Documentation
 
 ### Material UI
 
-Material UI is available as an [npm package](https://www.npmjs.com/package/@mui/material).
-
-```bash
-npm install @mui/material @emotion/react @emotion/styled
-```
+Visit [https://mui.com/material-ui/](https://mui.com/material-ui/) to view the full documentation.
 
 <details>
   <summary>Older versions</summary>
@@ -53,32 +49,23 @@ npm install @mui/material @emotion/react @emotion/styled
 **Note:** `@next` only points to pre-releases.
 Use `@latest` for the latest stable release.
 
-### Base UI
-
-Base UI is available as an [npm package](https://www.npmjs.com/package/@mui/base).
+### Joy UI
 
-```bash
-npm install @mui/base
-```
+Visit [https://mui.com/joy-ui/getting-started/](https://mui.com/joy-ui/getting-started/) to view the full documentation.
 
-**Note**: Base UI is still in beta.
+**Note**: Joy UI is still in beta.
 We are adding new components regularly and you're welcome to contribute!
 
-### MUI System
-
-MUI System is available as an [npm package](https://www.npmjs.com/package/@mui/system).
+### Base UI
 
-```bash
-npm install @mui/system @emotion/react @emotion/styled
-```
+Visit [https://mui.com/base-ui/](https://mui.com/base-ui/) to view the full documentation.
 
-Or if you want to use styled-components as the styling engine:
+**Note**: Base UI is still in beta.
+We are adding new components regularly and you're welcome to contribute!
 
-```bash
-npm install @mui/material @mui/styled-engine-sc styled-components
-```
+### MUI System
 
-Visit our [styled-components guide](https://mui.com/material-ui/guides/styled-components/) for more information on configuration.
+Visit [https://mui.com/system/](https://mui.com/system/) to view the full documentation.
 
 ## Sponsors
 
@@ -112,42 +99,15 @@ Gold Sponsors are those who have pledged \$500/month or more to MUI.
 
 See the full list of [our backers](https://mui.com/material-ui/discover-more/backers/).
 
-## Getting started with Material UI
-
-Here is an example of a basic app using Material UI's `Button` component:
-
-```jsx
-import * as React from 'react';
-import Button from '@mui/material/Button';
-
-function App() {
-  return <Button variant="contained">Hello World</Button>;
-}
-```
-
-In the interactive demo below, try changing the code and see how it affects the output.
-(Hint: change `variant` to `"outlined"` and `color` to `"secondary"`.
-For more options, see the [`Button` component page](https://mui.com/material-ui/react-button/) in our docs.)
-
-[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/material-ui-u9sy1h)
-
 ## Questions
 
-For how-to questions that don't involve making changes to the code base, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/material-ui) instead of GitHub issues.
-Use the "mui" tag on Stack Overflow to make it easier for the community to find your question.
+For how-to questions that don't involve making changes to the code base, please use [Stack Overflow](https://stackoverflow.com/questions/) instead of GitHub issues.
 
 ## Examples
 
-Our documentation features [a collection of example projects using Material UI](https://mui.com/material-ui/getting-started/example-projects/).
+Our documentation features [a collection of example projects](https://github.com/mui/material-ui/tree/master/examples).
 
-## Documentation
-
-- [Material UI](https://mui.com/material-ui)
-- [Joy UI](https://mui.com/joy-ui/getting-started/)
-- [Base UI](https://mui.com/base-ui/)
-- [MUI System](https://mui.com/system/getting-started/)
-
-## Premium themes
+## Premium templates
 
 You can find complete templates and themes in the [MUI Store](https://mui.com/store/?utm_source=docs&utm_medium=referral&utm_campaign=readme-store).
 
@@ -179,30 +139,42 @@ For details of supported versions and contact details for reporting security iss
 
 These great services sponsor MUI's core infrastructure:
 
+<div>
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="/docs/public/static/readme/github-darkmode.svg">
-  <source media="(prefers-color-scheme: light)" srcset="/docs/public/static/readme/github-lightmode.svg">
-  <img alt="GitHub logo" src="/docs/public/static/readme/github-lightmode.svg" width="80" height="43">
+  <source media="(prefers-color-scheme: dark)" srcset="https://mui.com/static/readme/github-darkmode.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://mui.com/static/readme/github-lightmode.svg">
+  <img alt="GitHub logo" src="https://mui.com/static/readme/github-lightmode.svg" width="80" height="43">
 </picture>
 
 [GitHub](https://github.com/) lets us host the Git repository and coordinate contributions.
 
+</div>
+
+<div>
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="/docs/public/static/readme/netlify-darkmode.svg">
-  <source media="(prefers-color-scheme: light)" srcset="/docs/public/static/readme/netlify-lightmode.svg">
-  <img alt="Netlify logo" src="/docs/public/static/readme/netlify-lightmode.svg" width="100" height="27" style="margin-top: 1rem;">
+  <source media="(prefers-color-scheme: dark)" srcset="https://mui.com/static/readme/netlify-darkmode.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://mui.com/static/readme/netlify-lightmode.svg">
+  <img alt="Netlify logo" src="https://mui.com/static/readme/netlify-lightmode.svg" width="100" height="27">
 </picture>
 
 [Netlify](https://www.netlify.com/) lets us distribute the documentation.
 
+</div>
+
+<div>
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="/docs/public/static/readme/browserstack-darkmode.svg">
-  <source media="(prefers-color-scheme: light)" srcset="/docs/public/static/readme/browserstack-lightmode.svg">
-  <img alt="BrowserStack logo" src="/docs/public/static/readme/browserstack-lightmode.svg" width="140" height="25" style="margin-top: 1rem;">
+  <source media="(prefers-color-scheme: dark)" srcset="https://mui.com/static/readme/browserstack-darkmode.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://mui.com/static/readme/browserstack-lightmode.svg">
+  <img alt="BrowserStack logo" src="https://mui.com/static/readme/browserstack-lightmode.svg" width="140" height="25">
 </picture>
 
 [BrowserStack](https://www.browserstack.com/) lets us test in real browsers.
 
-<img loading="lazy" alt="CodeCov logo" src="https://avatars.githubusercontent.com/u/8226205?s=70" width="35" height="35" style="margin-top: 1rem;">
+</div>
+
+<div>
+<img loading="lazy" alt="CodeCov logo" src="https://avatars.githubusercontent.com/u/8226205?s=70" width="35" height="35">
 
 [CodeCov](https://about.codecov.io/) lets us monitor test coverage.
+
+</div>

packages/mui-base/README.md

@@ -1,4 +1,9 @@
-# Base UI
+<!-- markdownlint-disable-next-line -->
+<p align="center">
+  <a href="https://mui.com/base-ui/" rel="noopener" target="_blank"><img width="150" height="133" src="https://mui.com/static/logo.svg" alt="Base UI logo"></a>
+</p>
+
+<h1 align="center">Base UI</h1>
 
 Base UI is a library of unstyled React UI components and hooks. With Base UI, you gain complete control over your app's CSS and accessibility features.
 
@@ -14,8 +19,37 @@ npm install @mui/base
 
 <!-- #default-branch-switch -->
 
-[The documentation](https://mui.com/base-ui/)
+Visit [https://mui.com/base-ui/](https://mui.com/base-ui/) to view the full documentation.
+
+## Questions
+
+For how-to questions that don't involve making changes to the code base, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/base-ui) instead of GitHub issues.
+Use the "base-ui" tag on Stack Overflow to make it easier for the community to find your question.
+
+## Examples
+
+Our documentation features [a collection of example projects using Base UI](https://github.com/mui/material-ui/tree/master/examples).
 
 ## Contributing
 
-See [the contributing guide](./CONTRIBUTING.md) if you wish to implement Base UI components or hooks.
+Read the [contributing guide](/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.
+
+Contributing to Base UI is about more than just issues and pull requests!
+There are many other ways to [support MUI](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) beyond contributing to the code base.
+
+## Changelog
+
+The [changelog](https://github.com/mui/material-ui/releases) is regularly updated to reflect what's changed in each new release.
+
+## Roadmap
+
+Future plans and high-priority features and enhancements can be found in our [roadmap](https://mui.com/material-ui/discover-more/roadmap/).
+
+## License
+
+This project is licensed under the terms of the
+[MIT license](/LICENSE).
+
+## Security
+
+For details of supported versions and contact details for reporting security issues, please refer to the [security policy](https://github.com/mui/material-ui/security/policy).

packages/mui-icons-material/README.md

@@ -26,8 +26,8 @@ npm install @mui/material
 
 <!-- #default-branch-switch -->
 
-- [The documentation](https://mui.com/material-ui/icons/#svgicon)
-- [The icons search](https://mui.com/material-ui/material-icons/)
+- [The SvgIcon documentation](https://mui.com/material-ui/icons/#svgicon)
+- [The Material Design icons search](https://mui.com/material-ui/material-icons/)
 
 ## Contributing
 
@@ -39,4 +39,4 @@ To synchronize with Material Icons, do the following:
 1. Inside this workspace run `yarn src:download`
 2. Inside this workspace run `yarn src:icons`
 3. Inside the root run `yarn docs:mdicons:synonyms`
-4. If the number of icons changed significantly, edit the icons/icons.md and material-icons/material-icons.md under docs/data/material/components and update the numbers.
+4. If the number of icons changes significantly, edit the icons/icons.md and material-icons/material-icons.md under docs/data/material/components and update the numbers.

packages/mui-joy/README.md

@@ -1,4 +1,9 @@
-# Joy UI
+<!-- markdownlint-disable-next-line -->
+<p align="center">
+  <a href="https://mui.com/joy-ui/getting-started/" rel="noopener" target="_blank"><img width="150" height="133" src="https://mui.com/static/logo.svg" alt="Joy UI logo"></a>
+</p>
+
+<h1 align="center">Joy UI</h1>
 
 Joy UI is a library of beautifully designed React UI components built to spark joy.
 
@@ -12,4 +17,37 @@ npm install @mui/joy @emotion/react @emotion/styled
 
 ## Documentation
 
-[The documentation](https://mui.com/joy-ui/getting-started/)
+Visit [https://mui.com/joy-ui/getting-started/](https://mui.com/joy-ui/getting-started/) to view the full documentation.
+
+## Questions
+
+For how-to questions that don't involve making changes to the code base, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/joy-ui) instead of GitHub issues.
+Use the "joy-ui" tag on Stack Overflow to make it easier for the community to find your question.
+
+## Examples
+
+Our documentation features [a collection of example projects using Joy UI](https://github.com/mui/material-ui/tree/master/examples).
+
+## Contributing
+
+Read the [contributing guide](/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.
+
+Contributing to Joy UI is about more than just issues and pull requests!
+There are many other ways to [support MUI](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) beyond contributing to the code base.
+
+## Changelog
+
+The [changelog](https://github.com/mui/material-ui/releases) is regularly updated to reflect what's changed in each new release.
+
+## Roadmap
+
+Future plans and high-priority features and enhancements can be found in our [roadmap](https://mui.com/material-ui/discover-more/roadmap/).
+
+## License
+
+This project is licensed under the terms of the
+[MIT license](/LICENSE).
+
+## Security
+
+For details of supported versions and contact details for reporting security issues, please refer to the [security policy](https://github.com/mui/material-ui/security/policy).

packages/mui-lab/README.md

@@ -25,4 +25,4 @@ npm install @mui/material @emotion/react @emotion/styled
 
 <!-- #default-branch-switch -->
 
-[The documentation](https://mui.com/material-ui/about-the-lab/)
+Visit [https://mui.com/material-ui/about-the-lab/](https://mui.com/material-ui/about-the-lab/) to view the full documentation.

packages/mui-material/README.md

@@ -1,4 +1,9 @@
-# Material UI
+<!-- markdownlint-disable-next-line -->
+<p align="center">
+  <a href="https://mui.com/material-ui/" rel="noopener" target="_blank"><img width="150" height="133" src="https://mui.com/static/logo.svg" alt="Material UI logo"></a>
+</p>
+
+<h1 align="center">Material UI</h1>
 
 Material UI is a comprehensive library of components that features our implementation of Google's [Material Design](https://m2.material.io/design/introduction/) system.
 
@@ -7,9 +12,42 @@ Material UI is a comprehensive library of components that features our implement
 Install the package in your project directory with:
 
 ```bash
-npm install @mui/material
+npm install @mui/material @emotion/react @emotion/styled
 ```
 
 ## Documentation
 
-[The documentation](https://mui.com/material-ui/)
+Visit [https://mui.com/material-ui/](https://mui.com/material-ui/) to view the full documentation.
+
+## Questions
+
+For how-to questions that don't involve making changes to the code base, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/material-ui) instead of GitHub issues.
+Use the "material-ui" tag on Stack Overflow to make it easier for the community to find your question.
+
+## Examples
+
+Our documentation features [a collection of example projects using Material UI](https://mui.com/material-ui/getting-started/example-projects/).
+
+## Contributing
+
+Read the [contributing guide](/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.
+
+Contributing to Material UI is about more than just issues and pull requests!
+There are many other ways to [support MUI](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) beyond contributing to the code base.
+
+## Changelog
+
+The [changelog](https://github.com/mui/material-ui/releases) is regularly updated to reflect what's changed in each new release.
+
+## Roadmap
+
+Future plans and high-priority features and enhancements can be found in our [roadmap](https://mui.com/material-ui/discover-more/roadmap/).
+
+## License
+
+This project is licensed under the terms of the
+[MIT license](/LICENSE).
+
+## Security
+
+For details of supported versions and contact details for reporting security issues, please refer to the [security policy](https://github.com/mui/material-ui/security/policy).

packages/mui-styled-engine-sc/README.md

@@ -7,4 +7,4 @@ It's designed for developers who would like to use `styled-components` as the ma
 
 <!-- #default-branch-switch -->
 
-[The documentation](https://mui.com/material-ui/guides/styled-components/)
+Visit [https://mui.com/material-ui/guides/styled-components/](https://mui.com/material-ui/guides/styled-components/) to view the full documentation.

packages/mui-styled-engine/README.md

@@ -8,4 +8,4 @@ It is used internally in the `@mui/system` package.
 
 <!-- #default-branch-switch -->
 
-[The documentation](https://mui.com/material-ui/guides/styled-components/)
+Visit [https://mui.com/material-ui/guides/styled-components/](https://mui.com/material-ui/guides/styled-components/) to view the full documentation.

packages/mui-styles/README.md

@@ -12,4 +12,4 @@ npm install @mui/styles
 
 ## Documentation
 
-[The documentation](https://mui.com/system/styles/basics/)
+Visit [https://mui.com/system/styles/basics/](https://mui.com/system/styles/basics/) to view the full documentation.

packages/mui-system/README.md

@@ -1,6 +1,6 @@
 # MUI System
 
-CSS utilities for rapidly laying out custom designs.
+MUI System is a collection of CSS utilities to help you rapidly lay out custom designs.
 
 ## Installation
 
@@ -16,4 +16,4 @@ npm install @mui/system @emotion/react @emotion/styled
 
 <!-- #default-branch-switch -->
 
-[The documentation](https://mui.com/system/getting-started/)
+Visit [https://mui.com/system/getting-started/](https://mui.com/system/getting-started/) to view the full documentation.

scripts/copyFiles.mjs

@@ -162,13 +162,9 @@ async function run() {
     const packageData = await createPackageFile();
 
     await Promise.all(
-      [
-        // use enhanced readme from workspace root for `@mui/material`
-        packageData.name === '@mui/material' ? '../../README.md' : './README.md',
-        '../../CHANGELOG.md',
-        '../../LICENSE',
-        ...extraFiles,
-      ].map((file) => includeFileInBuild(file)),
+      ['./README.md', '../../CHANGELOG.md', '../../LICENSE', ...extraFiles].map((file) =>
+        includeFileInBuild(file),
+      ),
     );
 
     await addLicense(packageData);