Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Add "Overview" page to Material UI docs #32643

Merged
merged 20 commits into from
May 30, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
5833a12
material ui overview page first draft
May 5, 2022
78f05ab
prettier, i18n
May 5, 2022
9c1bb99
add material ui overview links to base overview, info callout
May 5, 2022
a2b1c54
Update docs/data/material/getting-started/overview/overview.md
samuelsycamore May 6, 2022
c6bd010
Update docs/data/material/getting-started/overview/overview.md
samuelsycamore May 6, 2022
5a0a8bf
Update docs/data/material/getting-started/overview/overview.md
samuelsycamore May 6, 2022
3947a73
Update docs/data/material/getting-started/overview/overview.md
samuelsycamore May 6, 2022
587d093
fix formatting
oliviertassinari May 8, 2022
227e8a7
official name
oliviertassinari May 8, 2022
c1a71b3
Update docs/data/base/getting-started/overview/overview.md
samuelsycamore May 9, 2022
f361de6
Update docs/data/base/getting-started/overview/overview.md
samuelsycamore May 9, 2022
5f6f456
Update docs/data/material/getting-started/overview/overview.md
samuelsycamore May 9, 2022
a85baf6
Update docs/data/material/getting-started/overview/overview.md
samuelsycamore May 9, 2022
6b11852
Update docs/data/material/getting-started/overview/overview.md
samuelsycamore May 9, 2022
76a4354
Update docs/data/base/getting-started/overview/overview.md
samuelsycamore May 9, 2022
918eb01
Update docs/data/base/getting-started/overview/overview.md
samuelsycamore May 9, 2022
e93175f
Update docs/data/base/getting-started/overview/overview.md
samuelsycamore May 9, 2022
7d73d0d
merge master
samuelsycamore May 25, 2022
baf30f9
reviving, design kits, note about md v3
samuelsycamore May 25, 2022
ba673d2
revise md 3 note
samuelsycamore May 25, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/data/base/getting-started/overview/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,31 +5,31 @@
## Introduction

MUI Base is a library of unstyled React UI components.
It features the same robust engineering as Material UI, but without implementing Material Design.
It features the same robust engineering as [Material UI](/material-ui/getting-started/overview/), but without implementing Material Design.

It includes prebuilt components with production-ready functionality, along with low-level hooks for transferring that functionality to other components.

With MUI Base, you can rapidly build on top of our foundational components using any styling solution you choose—no need to override any default style engines or settings.
With MUI Base, you can rapidly build on top of our foundational components using any styling solution you choose—no need to override any default style engine or theme.

> **Note:** _as of Q2 2022, Base is currently still in alpha._
>
> We're adding new components regularly, and you're welcome to contribute!
>
> Look for the [`package: base` label](https://github.com/mui/material-ui/labels/package%3A%20base) on open [issues](https://github.com/mui/material-ui/issues) and [pull requests](https://github.com/mui/material-ui/pulls) in the `@mui/material-ui` repository on GitHub to see what other community members are working on, and feel free to submit your own.
:::info
**Note:** _as of Q2 2022, Base is currently still in alpha._

We're adding new components regularly, and you're welcome to contribute!

Look for the [`package: base` label](https://github.com/mui/material-ui/labels/package%3A%20base) on open [issues](https://github.com/mui/material-ui/issues) and [pull requests](https://github.com/mui/material-ui/pulls) in the `@mui/material-ui` GitHub repository to see what other community members are working on, and feel free to submit your own.
:::

## Advantages of MUI Base

- **Ship faster:** MUI Base gives you the foundational building blocks you need to assemble a sleek and sophisticated user interface in a fraction of the time that it would take to do it all from scratch.

- **You own the CSS:** unlike Material UI, which uses Emotion as a default style engine, MUI Base has no built-in styling solution.
- **You own the CSS:** unlike Material UI, which uses emotion as a default style engine, MUI Base has no built-in styling solution.
This means you have complete control over your app's CSS.

- **Accessibility:** MUI Base components are built with accessibility in mind.
We do our best to make all components screen reader-friendly, and offer suggestions for optimizing accessibility throughout our documentation.

### MUI Base vs. Material UI
## MUI Base vs. Material UI

MUI Base features many of the same components as Material UI, but _without the Material Design implementation_.
MUI Base features many of the same components as [Material UI](/material-ui/getting-started/overview/), but _without the Material Design implementation_.

Base is not packaged with any default theme or built-in style engine.
This makes it a great choice if you need complete control over how your app's CSS is implemented.
Expand Down
33 changes: 33 additions & 0 deletions docs/data/material/getting-started/overview/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Material UI - Overview

<p class="description">Material UI is library of React UI components that implements Google's Material Design.</p>

## Introduction

Material UI is an open-source React component library that implements Google's [Material Design](https://material.io/).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Material UI is an open-source React component library that implements Google's [Material Design](https://material.io/).
Material UI is an open-source React component library that implements version 2 of Google's [Material Design](https://material.io/).

Copy link
Member

@oliviertassinari oliviertassinari May 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We take the risk to forget to update "version 2" with Material UI v6 which would cover Material Design v3 if everything goes smoothly.

If we really want to mention a version, then I think that we should rephrase it, in the current wording, it could sounds like v2 is our ultimate goal. Instead, we could say something around "currently v2". e.g.

Suggested change
Material UI is an open-source React component library that implements Google's [Material Design](https://material.io/).
Material UI is an open-source React component library that implements Google's [Material Design](https://material.io/).
It currently only supports Material Design v2, see [issue #12134](foo/bar) for the support of Material Design v3.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm confused about what's the intended direction regarding Material's v3, it doesn't seem to exist alignment in this matter — see #32643 (comment)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's what I've added based on my understanding of the situation—please correct me if I'm wrong:

:::info
Material UI currently supports Material Design v2.
Adoption of v3 is tentatively planned for Material UI v6.
You can follow [this GitHub issue](https://github.com/mui/material-ui/issues/29345) for future updates.
:::

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternatively: we could always just leave this out completely if we aren't prepared to say yes or no to v3 adoption. 😅


It includes a comprehensive collection of prebuilt components that are ready for use in production right out of the box.

Material UI is beautiful by design, and features a suite of customization options that make it easy to implement your own custom design system on top of our components.
samuelsycamore marked this conversation as resolved.
Show resolved Hide resolved

:::info
Material UI currently supports Material Design v2.
Adoption of v3 is tentatively planned for Material UI v6.
You can follow [this GitHub issue](https://github.com/mui/material-ui/issues/29345) for future updates.
:::

samuelsycamore marked this conversation as resolved.
Show resolved Hide resolved
## Advantages of Material UI

- **Ship faster:** thousands of open-source contributors have poured countless hours into these components. Focus on your core business logic—we've got your UI covered.
- **Beautiful by default:** we're meticulous about our implementation of Material Design, ensuring that every Material UI component meets the highest standards of form and function.
samuelsycamore marked this conversation as resolved.
Show resolved Hide resolved
- **Cross-team collaboration:** Material UI's intuitive developer experience reduces the barrier to entry for back-end devs and less technical designers, empowering teams to collaborate more effectively.
samuelsycamore marked this conversation as resolved.
Show resolved Hide resolved
- **Reliability:** Material UI is almost as old as React itself—its history stretches back to 2014—and we're in this for the long haul. When you build with Material UI, you can count on our community's support for years to come.
- **Design kits:** streamline your workflow and boost consistency between designers and developers by using our [design kits](https://mui.com/design-kits/) in your favorite design tool.

## Material UI vs. MUI Base

Material UI and [MUI Base](/base/getting-started/overview/) feature many of the same UI components, but MUI Base comes without any default styles or styling solution.

Material UI is _comprehensive_ in that it comes packaged with default styles, and is optimized to work with [Emotion](https://emotion.sh/docs/introduction) (or [styled-components](https://styled-components.com/)).

MUI Base, by contrast, could be considered the "skeletal" or "headless" counterpart to Material UI—in fact, Material UI v6 will use MUI Base components and hooks for its foundational structure.
1 change: 1 addition & 0 deletions docs/data/material/pages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ const pages = [
pathname: '/material-ui/getting-started',
icon: 'DescriptionIcon',
children: [
{ pathname: '/material-ui/getting-started/overview' },
{ pathname: '/material-ui/getting-started/installation' },
{ pathname: '/material-ui/getting-started/usage' },
{ pathname: '/material-ui/getting-started/example-projects' },
Expand Down
11 changes: 11 additions & 0 deletions docs/pages/material-ui/getting-started/overview.js
Original file line number Diff line number Diff line change
@@ -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/overview/overview.md?@mui/markdown';

export default function Page() {
return <MarkdownDocs demos={demos} docs={docs} demoComponents={demoComponents} />;
}
1 change: 1 addition & 0 deletions docs/translations/translations.json
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,7 @@
"/base/react-textarea-autosize": "Textarea autosize",
"/base/react-trap-focus": "Trap focus",
"/material-ui/getting-started": "Getting started",
"/material-ui/getting-started/overview": "Overview",
"/material-ui/getting-started/installation": "Installation",
"/material-ui/getting-started/usage": "Usage",
"/material-ui/getting-started/example-projects": "Example projects",
Expand Down