[Joy] Add an overview page (#32836)

* create pages * create markdown file * add the page * add callout * move the Principles content to here * bonus: turn the Quick Start page into Usage * change page title * add Base link * detail: making strong tag on dark mode lighter * edit next steps * remove next step section from tutorials * Jun's review Co-authored-by: Siriwat K <[email protected]> * add line break Co-authored-by: Siriwat K <[email protected]>
mui · May 20, 2022 · c349358 · c349358
1 parent f859ef9
commit c349358
Show file tree

Hide file tree

Showing 8 changed files with 62 additions and 40 deletions.
diff --git a/docs/data/joy/getting-started/overview/overview.md b/docs/data/joy/getting-started/overview/overview.md
@@ -0,0 +1,44 @@
+# Joy UI - Overview
+
+<p class="description">Joy UI is a library of beautifully designed React UI components.</p>
+
+Joy UI is a library of React UI components. It features foundational components such as the ones you'd find in Material UI.
+It comes with a beautifully designed default theme so you can rapidly start your own design system.
+
+You should see Joy UI as your starting point.
+It includes a lot of customization features and the capability for you to match it to your desired look and feel.
+
+:::warning
+**Note:** as of Q2 2022, Joy UI is currently in active development, with an alpha version soon to be released.
+We're adding new components and features regularly, and you're welcome to contribute! Look for the [`joy` label](https://github.com/mui/material-ui/pulls?q=is%3Aopen+is%3Apr+label%3Ajoy) 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.
+:::
+
+## Advantages of Joy UI
+
+- **Ship faster:** Joy UI gives you a significant amount of prebuilt components you need to develop web apps, with a sleek and carefully designed look and feel, allowing it to achieve a good-looking result without a dedicated designer.
+- **Extensive customization:** you're encouraged to customize each and every tiny piece of the Joy UI components so they match your desired design.
+- **Accessibility in mind:** Joy UI components are built on top of [MUI Base unstyled components and low-level hooks](/base/getting-started/overview/), giving you support for several accessibility features out of the box. We do our best to make all components screen reader-friendly, and offer suggestions for optimizing accessibility throughout our documentation.
+
+## Principles
+
+### Keep it essential
+
+Joy should work with the least amount of effort possible. We're striving for the essential only, both in the component API and design (look & feel). Components should have only what they need to do the job. What is considered essential will be drawn from MUI's experience over the years developing component libraries like this one, as well as from benchmarks of modern API and design guidelines—especially when it comes to developing web apps.
+
+### Looks great out-of-the-box
+
+Joy needs to be simple yet characteristic. Visual attributes such as scale, size, and density should be consistent across all of the components so they live together nicely. We aim to spark delight with simplicity and attention to detail. You should feel like your UI looks great from the start.
+
+### Encourage creativity
+
+We're aiming for Joy to be entirely customizable, and seen as a great starting point. This is meant to encourage you to extend, change, and revamp how Joy looks. Be creative by making it your own.
+
+### Focus on developer experience
+
+A great developer experience is not only the quality of the code we ship but also how clear the documentation is, and what learning resources are available for developers. We hope that bundling it all together brings joy.
+
+## Joy UI vs. Material UI
+
+Joy UI is meant to feature the same list of components you'd find in Material UI, with similar philosophy around component API and customization extensibility, but without the Material Design implementation.
+
+If you ever wanted to use Material UI for the breadth of supported components, carefully written component API, and reliability of a tried and tested library but hesitated because of Material Design, Joy UI is here to solve that for you and act as the best alternative for that.
diff --git a/docs/data/joy/getting-started/principles/principles.md b/docs/data/joy/getting-started/principles/principles.md
diff --git a/docs/data/joy/getting-started/tutorial/tutorial.md b/docs/data/joy/getting-started/tutorial/tutorial.md
@@ -221,9 +221,3 @@ export default function App() {
 > 💡 By using the `useColorScheme` hook, Joy ensures that the user selected mode (stored in localStorage by default) is in-sync across browser tabs.
 
 Congratulations 🎉! You have seamlessly built a simple yet good looking UI!
-
-## Where to go from here?
-
-- 💎 Learn about Joy's main features
-- 💅 Learn about how to customize Joy components
-- 📖 Learn about Joy's guiding principles and core concepts.
diff --git a/...etting-started/quick-start/quick-start.md → docs/data/joy/getting-started/usage/usage.md b/...etting-started/quick-start/quick-start.md → docs/data/joy/getting-started/usage/usage.md
@@ -1,12 +1,12 @@
-# Quick start
+# Joy UI - Usage
 
-<p class="description">Get started with Joy, a simple and beautiful starting point for your design system, in 3 quick steps.</p>
+<p class="description">Learn the basics of working with Joy UI components in three quick steps.</p>
 
-## 1. Installation
+## Installation
 
 Install Joy via either npm or yarn using the commands below in your directory of choice.
 
-### npm
+**npm**
 
 ```sh
 npm init react-app spark-joy
@@ -15,7 +15,7 @@ npm install @mui/joy @emotion/react @emotion/styled
 npm start
 ```
 
-### yarn
+**yarn**
 
 ```sh
 yarn create react-app spark-joy
@@ -24,7 +24,7 @@ yarn add @mui/joy @emotion/react @emotion/styled
 yarn start
 ```
 
-## 2. Set up the `CssVarsProvider` component
+## Set up the `CssVarsProvider` component
 
 Go to your `App.js` file and replace it with the code snippet below. You should see the text `Hello from Joy` being rendered on your browser.
 
@@ -38,7 +38,7 @@ function App() {
 export default App;
 ```
 
-## 3. Render your first component
+## Render your first component
 
 To render any Joy component, make sure you place them inside the `CssVarProvider` element. Let's start off with a button.
 
@@ -57,11 +57,11 @@ function App() {
 export default App;
 ```
 
-Make sure that your development server is running, save your file and that's it! It's that fast.
+Make sure that your development server is running, save your file, and that's it!
+It's that fast.
 You're now ready to go on exploring Joy and build amazing UIs.
 
-## Where to go from here?
+## Next steps
 
-- 👨‍💻👩‍💻 [See more tutorials](/joy-ui/getting-started/tutorial/) to learn how to use other Joy components
+- 👩‍💻 [Build your first UI](/joy-ui/getting-started/tutorial/) with Joy.
 - 💎 Learn about Joy's main features.
-- 📖 Learn about Joy's guiding principles and core concepts.
diff --git a/docs/data/joy/pages.ts b/docs/data/joy/pages.ts
@@ -3,9 +3,9 @@ const pages = [
     pathname: '/joy-ui/getting-started',
     icon: 'DescriptionIcon',
     children: [
-      { pathname: '/joy-ui/getting-started/quick-start' },
+      { pathname: '/joy-ui/getting-started/overview' },
+      { pathname: '/joy-ui/getting-started/usage' },
       { pathname: '/joy-ui/getting-started/tutorial' },
-      { pathname: '/joy-ui/getting-started/principles' },
     ],
   },
   {

diff --git a/...ages/joy-ui/getting-started/principles.js → .../pages/joy-ui/getting-started/overview.js b/...ages/joy-ui/getting-started/principles.js → .../pages/joy-ui/getting-started/overview.js
@@ -4,7 +4,7 @@ import {
   demos,
   docs,
   demoComponents,
-} from 'docs/data/joy/getting-started/principles/principles.md?@mui/markdown';
+} from 'docs/data/joy/getting-started/overview/overview.md?@mui/markdown';
 
 export default function Page() {
   return <MarkdownDocs demos={demos} docs={docs} demoComponents={demoComponents} />;

diff --git a/...ges/joy-ui/getting-started/quick-start.js → docs/pages/joy-ui/getting-started/usage.js b/...ges/joy-ui/getting-started/quick-start.js → docs/pages/joy-ui/getting-started/usage.js
@@ -4,7 +4,7 @@ import {
   demos,
   docs,
   demoComponents,
-} from 'docs/data/joy/getting-started/quick-start/quick-start.md?@mui/markdown';
+} from 'docs/data/joy/getting-started/usage/usage.md?@mui/markdown';
 
 export default function Page() {
   return <MarkdownDocs demos={demos} docs={docs} demoComponents={demoComponents} />;

diff --git a/docs/src/modules/components/MarkdownElement.js b/docs/src/modules/components/MarkdownElement.js
@@ -7,6 +7,9 @@ import { blue, blueDark } from 'docs/src/modules/brandingTheme';
 const Root = styled('div')(({ theme }) => ({
   ...theme.typography.body1,
   color: theme.palette.text.primary,
+  '& strong': {
+    color: theme.palette.mode === 'dark' ? theme.palette.grey[200] : theme.palette.text.primary,
+  },
   wordBreak: 'break-word',
   '& .anchor-link': {
     marginTop: -96,