[docs] Standardize all MUI Core "Installation" pages (mui#34168)

alexfauquette · Oct 14, 2022 · 2d92961 · 2d92961
1 parent 0b87e02
commit 2d92961
Show file tree

Hide file tree

Showing 8 changed files with 156 additions and 72 deletions.
diff --git a/docs/data/base/getting-started/installation/installation.md b/docs/data/base/getting-started/installation/installation.md
@@ -1,23 +1,23 @@
 # Installation
 
-<p class="description">Install MUI Base, a robust library of blank ("unstyled") React UI components and low-level hooks.</p>
+<p class="description">Install MUI Base, a library of headless ("unstyled") React UI components and low-level hooks.</p>
 
-## npm
+Run one of the following commands to add MUI Base to your project:
 
-To install and save in your `package.json` dependencies, run the command below using **npm**:
+## npm
 
 ```sh
 npm install @mui/base
 ```
 
-Or **yarn**:
+## yarn
 
 ```sh
 yarn add @mui/base
 ```
 
+## Peer dependencies
+
 <!-- #react-peer-version -->
 
-:::warning
-**Note:** [react](https://www.npmjs.com/package/react) >= 17.0.0 and [react-dom](https://www.npmjs.com/package/react-dom) >= 17.0.0 are peer dependencies.
-:::
+[`react`](https://www.npmjs.com/package/react) >= 17.0.0 and [`react-dom`](https://www.npmjs.com/package/react-dom) >= 17.0.0 are peer dependencies.
diff --git a/docs/data/joy/getting-started/installation/installation.md b/docs/data/joy/getting-started/installation/installation.md
@@ -2,20 +2,22 @@
 
 <p class="description">Install Joy UI, a library of beautifully designed React UI components.</p>
 
-## npm
+Run one of the following commands to add Joy UI to your project:
 
-Run the command below to add Joy UI using **npm** to your project.
+## npm
 
 ```sh
 npm install @mui/joy @emotion/react @emotion/styled
-npm start
 ```
 
 ## yarn
 
-Run the command below to add Joy UI using **yarn** to your project.
-
 ```sh
 yarn add @mui/joy @emotion/react @emotion/styled
-yarn start
 ```
+
+## Peer dependencies
+
+<!-- #react-peer-version -->
+
+[`react`](https://www.npmjs.com/package/react) >= 17.0.0 and [`react-dom`](https://www.npmjs.com/package/react-dom) >= 17.0.0 are peer dependencies.
diff --git a/docs/data/material/getting-started/design-resources/design-resources.md b/docs/data/material/getting-started/design-resources/design-resources.md
@@ -0,0 +1,28 @@
+# Design resources
+
+<p class="description">Check out these prebuilt UI kits to help you design with Material UI using your favorite tools.</p>
+
+<a href="https://mui.com/store/items/figma-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-figma" style="margin-left: 8px; margin-top: 8px; display: inline-block;"><img src="/static/images/download-figma.svg" alt="figma" /></a>
+<a href="https://mui.com/store/items/adobe-xd-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-adobe-xd" style="margin-left: 32px; margin-top: 8px; display: inline-block;"><img src="/static/images/download-adobe-xd.svg" alt="adobe-xd" /></a>
+<a href="https://mui.com/store/items/sketch-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-sketch" style="margin-left: 32px; margin-top: 8px; display: inline-block;"><img src="/static/images/download-sketch.svg" alt="sketch" /></a>
+
+## MUI resources
+
+### Figma
+
+[Material UI for Figma](https://mui.com/store/items/figma-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-figma): a comprehensive component inventory for Figma, including over 1,500 unique elements that cover the full range of states and variations of each component.
+
+### Adobe XD
+
+[Material UI for Adobe XD](https://mui.com/store/items/adobe-xd-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-adobe-xd): a comprehensive component inventory for Adobe XD, including over 1,500 unique elements that cover the full range of states and variations of each component.
+
+### Sketch
+
+[Material UI for Sketch](https://mui.com/store/items/sketch-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-sketch): a comprehensive component inventory for Sketch, including over 1,500 unique elements that cover the full range of states and variations of each component, as well as 1,000+ icons in five themes.
+
+## Third-party resources
+
+### UXPin
+
+[Material UI for UXPin](https://www.uxpin.com/merge/mui-library): A large UI kit of Material UI components.
+The design tool renders the components in a web runtime. It uses the same React implementation as your production environment.
diff --git a/docs/data/material/getting-started/installation/installation.md b/docs/data/material/getting-started/installation/installation.md
@@ -2,115 +2,141 @@
 
 <p class="description">Install Material UI, the world's most popular React UI framework.</p>
 
-Material UI is available as an [npm package](https://www.npmjs.com/package/@mui/material).
+## Default installation
 
-## npm
+Run one of the following commands to add Material UI to your project:
 
-To install and save in your `package.json` dependencies, run the command below using **npm**:
+### npm
 
 ```sh
 npm install @mui/material @emotion/react @emotion/styled
 ```
 
-Or **yarn**:
+### yarn
 
 ```sh
 yarn add @mui/material @emotion/react @emotion/styled
 ```
 
-<!-- #react-peer-version -->
+## With styled-components
 
-Please note that [react](https://www.npmjs.com/package/react) >= 17.0.0 and [react-dom](https://www.npmjs.com/package/react-dom) >= 17.0.0 are peer dependencies.
+Material UI uses [Emotion](https://emotion.sh/) as its default styling engine.
+If you want to use [styled-components](https://styled-components.com/) instead, run one of the following commands:
 
-Material UI is using [emotion](https://emotion.sh/docs/introduction) as a styling engine by default. If you want to use [`styled-components`](https://styled-components.com/) instead, run:
+### npm
 
 ```sh
 npm install @mui/material @mui/styled-engine-sc styled-components
 ```
 
+### yarn
+
 ```sh
 yarn add @mui/material @mui/styled-engine-sc styled-components
 ```
 
-:::info
-💡 Take a look at the [Styled Engine guide](/material-ui/guides/styled-engine/) for more information about how to configure `styled-components` as the style engine.
+:::warning
+Visit the [Styled engine guide](/material-ui/guides/styled-engine/) for more information about how to configure styled-components.
 :::
 
+## Peer dependencies
+
+<!-- #react-peer-version -->
+
+[`react`](https://www.npmjs.com/package/react) >= 17.0.0 and [`react-dom`](https://www.npmjs.com/package/react-dom) >= 17.0.0 are peer dependencies.
+
 ## Roboto font
 
-Material UI was designed with the [Roboto](https://fonts.google.com/specimen/Roboto)
-font in mind. So be sure to follow [these instructions](/material-ui/react-typography/#general).
-For instance, via Google Web Fonts:
+Material UI is designed to use the [Roboto](https://fonts.google.com/specimen/Roboto)
+font by default.
+You may add it to your project with npm or yarn via [Fontsource](https://fontsource.org/), or with the Google Fonts CDN.
 
-```html
-<link
-  rel="stylesheet"
-  href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap"
-/>
+### npm
+
+```sh
+npm install @fontsource/roboto
 ```
 
-## Font icons
+### yarn
 
-To use the font `Icon` component, you must first add the [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons) font.
-Here are [some instructions](/material-ui/icons/#icon-font-icons)
-on how to do so.
-For instance, via Google Web Fonts:
+```sh
+yarn add @fontsource/roboto
+```
+
+Then you can import it in your entry point like this:
+
+```tsx
+import '@fontsource/roboto/300.css';
+import '@fontsource/roboto/400.css';
+import '@fontsource/roboto/500.css';
+import '@fontsource/roboto/700.css';
+```
+
+:::info
+Fontsource can be configured to load specific subsets, weights and styles. Material UI's default typography configuration relies only on the 300, 400, 500, and 700 font weights.
+:::
+
+### Google Web Fonts
+
+To install the Roboto font in your project using the Google Web Fonts CDN, add the following code snippet inside your project's `<head />` tag:
 
 ```html
 <link
   rel="stylesheet"
-  href="https://fonts.googleapis.com/icon?family=Material+Icons"
+  href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap"
 />
 ```
 
-## SVG icons
+## Icons
 
-In order to use prebuilt SVG Material icons, such as those found in the [icons demos](/material-ui/icons/)
-you must first install the [@mui/icons-material](https://www.npmjs.com/package/@mui/icons-material) package:
+To use the [font Icon component](/material-ui/icons/#icon-font-icons) or the prebuilt SVG Material Icons (such as those found in the [icon demos](/material-ui/icons/)), you must first install the [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons) font.
+You can do so with npm or yarn, or with the Google Web Fonts CDN.
 
-<!-- #default-branch-switch -->
-
-With **npm**:
+### npm
 
 ```sh
 npm install @mui/icons-material
 ```
 
-With **yarn**:
+### yarn
 
 ```sh
 yarn add @mui/icons-material
 ```
 
-## CDN
-
-You can start using Material UI with minimal Front-end infrastructure,
-which is great for prototyping.
+### Google Web Fonts
 
-Two Universal Module Definition (**UMD**) files are provided:
+To install the Material Icons font in your project using the Google Web Fonts CDN, add the following code snippet inside your project's `<head />` tag:
 
-- one for development: https://unpkg.com/@mui/material@latest/umd/material-ui.development.js
-- one for production: https://unpkg.com/@mui/material@latest/umd/material-ui.production.min.js
+To use the font `Icon` component, you must first add the [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons) font.
+Here are [some instructions](/material-ui/icons/#icon-font-icons)
+on how to do so.
+For instance, via Google Web Fonts:
 
-You can follow [this CDN example](https://github.com/mui/material-ui/tree/master/examples/cdn) to quickly get started.
+```html
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/icon?family=Material+Icons"
+/>
+```
 
-⚠️ Using this approach in **production** is **discouraged** though -
-the client has to download the entire library, regardless of which components are actually used,
-affecting performance and bandwidth utilization.
+## CDN
 
-⚠️ The UMD links are using the `latest` tag to point to the latest version of the library.
-This pointer is **unstable**, it shifts as we release new versions.
-You should consider pointing to a specific version, such as [v5.0.0](https://unpkg.com/@mui/material@5.0.0/umd/material-ui.development.js).
+You can start using Material UI right away with minimal front-end infrastructure by installing it via CDN, which is a great option for rapid prototyping.
+Follow [this CDN example](https://github.com/mui/material-ui/tree/master/examples/cdn) to get started.
 
-## Design resources
+:::error
+We do _not_ recommend using this approach in production.
+It requires the client to download the entire library—regardless of which components are actually used—which negatively impacts performance and bandwidth utilization.
+:::
 
-<a href="https://mui.com/store/items/figma-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-figma" style="margin-left: 8px; margin-top: 8px; display: inline-block;"><img src="/static/images/download-figma.svg" alt="figma" /></a>
-<a href="https://mui.com/store/items/adobe-xd-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-adobe-xd" style="margin-left: 32px; margin-top: 8px; display: inline-block;"><img src="/static/images/download-adobe-xd.svg" alt="adobe-xd" /></a>
-<a href="https://mui.com/store/items/sketch-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-sketch" style="margin-left: 32px; margin-top: 8px; display: inline-block;"><img src="/static/images/download-sketch.svg" alt="sketch" /></a>
+Two Universal Module Definition (UMD) files are provided:
 
-A set of reusable components for design tools is available, designed to match the React components and to help you craft great products:
+- one for development: https://unpkg.com/@mui/material@latest/umd/material-ui.development.js
+- one for production: https://unpkg.com/@mui/material@latest/umd/material-ui.production.min.js
 
-- [Figma](https://mui.com/store/items/figma-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-figma): A large UI kit with over 600 handcrafted Material UI components.
-- [Adobe XD](https://mui.com/store/items/adobe-xd-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-adobe-xd): A large UI kit with over 600 handcrafted Material UI components.
-- [Sketch](https://mui.com/store/items/sketch-react/?utm_source=docs&utm_medium=referral&utm_campaign=installation-sketch): A large UI kit with over 600 handcrafted Material UI symbols.
-- [UXPin](https://www.uxpin.com/merge/mui-library): A large UI kit of Material UI components. The design tool renders the components in a web runtime. It uses the same React implementation as your production environment.
+:::warning
+The UMD links use the `latest` tag to point to the latest version of the library.
+This pointer is _unstable_ and subject to change as we release new versions.
+You should consider pointing to a specific version, such as [v5.0.0](https://unpkg.com/@mui/material@5.0.0/umd/material-ui.development.js).
+:::
diff --git a/docs/data/material/pages.ts b/docs/data/material/pages.ts
@@ -11,6 +11,7 @@ const pages = [
       { pathname: '/material-ui/getting-started/example-projects' },
       { pathname: '/material-ui/getting-started/templates' },
       { pathname: '/material-ui/getting-started/learn' },
+      { pathname: '/material-ui/getting-started/design-resources' },
       { pathname: '/material-ui/getting-started/faq', title: 'FAQs' },
       { pathname: '/material-ui/getting-started/supported-components' },
       { pathname: '/material-ui/getting-started/supported-platforms' },

diff --git a/docs/data/system/getting-started/installation/installation.md b/docs/data/system/getting-started/installation/installation.md
@@ -2,30 +2,45 @@
 
 <p class="description">Install MUI System, a collection of CSS utilities for rapidly laying out custom designs.</p>
 
-<!-- #default-branch-switch -->
+## Default installation
 
-To install and save in your `package.json` dependencies, run the command below using **npm**:
+Run one of the following commands to add MUI System to your project:
+
+### npm
 
 ```sh
 npm install @mui/system @emotion/react @emotion/styled
 ```
 
-Or **yarn**:
+### yarn
 
 ```sh
 yarn add @mui/system @emotion/react @emotion/styled
 ```
 
-Or if you want to use `styled-components` as a styling engine:
+## With styled-components
+
+MUI System uses [Emotion](https://emotion.sh/) as its default styling engine.
+If you want to use [styled-components](https://styled-components.com/) instead, run one of the following commands:
 
-<!-- #default-branch-switch -->
+### npm
 
 ```sh
 npm install @mui/system @mui/styled-engine-sc styled-components
 ```
 
+### yarn
+
 ```sh
 yarn add @mui/system @mui/styled-engine-sc styled-components
 ```
 
-Take a look at the [Styled Engine guide](/material-ui/guides/styled-engine/) for more information about how to configure `styled-components` as the style engine.
+:::warning
+Visit the [Styled engine guide](/material-ui/guides/styled-engine/) for more information about how to configure styled-components.
+:::
+
+## Peer dependencies
+
+<!-- #react-peer-version -->
+
+[`react`](https://www.npmjs.com/package/react) >= 17.0.0 is a peer dependency.
diff --git a/docs/pages/material-ui/getting-started/design-resources.js b/docs/pages/material-ui/getting-started/design-resources.js
@@ -0,0 +1,11 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import {
+  demos,
+  docs,
+  demoComponents,
+} from 'docs/data/material/getting-started/design-resources/design-resources.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs demos={demos} docs={docs} demoComponents={demoComponents} />;
+}
diff --git a/docs/translations/translations.json b/docs/translations/translations.json
@@ -224,6 +224,7 @@
     "/material-ui/getting-started/example-projects": "Example projects",
     "/material-ui/getting-started/templates": "Templates",
     "/material-ui/getting-started/learn": "Learn",
+    "/material-ui/getting-started/design-resources": "Design resources",
     "/material-ui/getting-started/faq": "FAQs",
     "/material-ui/getting-started/supported-components": "Supported components",
     "/material-ui/getting-started/supported-platforms": "Supported platforms",