[material-ui][docs] Add Connect-related content (#40848)

Co-authored-by: David Cnoops <davidcnoops@outlook.com>
mui · Apr 16, 2024 · abed32d · abed32d
1 parent 6bcb471
commit abed32d
Show file tree

Hide file tree

Showing 23 changed files with 454 additions and 4 deletions.
diff --git a/docs/data/material/design-resources/connect/connect.md b/docs/data/material/design-resources/connect/connect.md
@@ -0,0 +1,301 @@
+# Connect plugin
+
+<p class="description">Connect is a Figma plugin that generates Material UI themes directly from design to code.</p>
+
+## Introduction
+
+[Connect](https://www.figma.com/community/plugin/1336346114713490235/) is a Figma plugin that lets you generate a theme from the [Material UI for Figma Design Kit](https://www.figma.com/community/file/912837788133317724/material-ui-for-figma-and-mui-x/).
+
+:::warning
+Connect works in combination with the [Material UI for Figma Design Kit v5.16.0](https://github.com/mui/mui-design-kits/releases) and later.
+Other kits, such as the Joy UI Design Kit, are not supported yet.
+:::
+
+<img src="/static/material-ui/design-resources/connect.png" style="width: 814px;" alt="Customizing the Material UI Switch component in Figma with the Connect plugin running." width="1628" height="400" />
+
+## Running the plugin
+
+If you don't have the [complete and latest version](/store/items/figma-react/) of the Material UI for Figma Design Kit installed, you can test the plugin by using the [Community version](https://www.figma.com/community/file/912837788133317724/material-ui-for-figma-and-mui-x/) instead.
+
+After installing and opening it in Figma, head over to the [Connect plugin page](https://www.figma.com/community/plugin/1336346114713490235/) on the Community tab and click on **Open in...** and select the Material UI for Figma Design Kit.
+
+<img src="/static/material-ui/design-resources/connect-access.png" style="width: 814px;" alt="Accessing Connect via the Resources menu in Figma." width="1628" height="400" />
+
+## Customizing design tokens
+
+Design tokens are defined in the Design Kit's [local variable collections](https://help.figma.com/hc/en-us/articles/15145852043927-Create-and-manage-variables) and include color palettes, breakpoints, shapes, and spacing tokens.
+Typography and shadow-related tokens are found in the [local styles collection](https://help.figma.com/hc/en-us/articles/360039820134-Manage-and-share-styles#:~:text=Local%20styles%20are%20styles%20that,or%20from%20the%20style%20picker.).
+
+### Altering existing tokens
+
+The Material UI for Figma Design Kit comes fully loaded with design tokens that map out to the [default theme of the Material UI React library](/material-ui/customization/default-theme/).
+
+To customize existing tokens, open the [local variable modal](https://help.figma.com/hc/en-us/articles/15145852043927-Create-and-manage-variables) by clicking on the filter icon as shown below.
+Tweak any of the variables available in the collections (such as palettes, breakpoints, shapes, and spacing) as you see fit.
+
+<img src="/static/material-ui/design-resources/connect-variables.png" style="width: 814px; margin-bottom: 8px;" alt="The Local variables menu in Figma, where all design tokens are stored and new ones can be added." width="1628" height="400" />
+
+Then open the Connect plugin and click on **Generate theme**.
+
+<img src="/static/material-ui/design-resources/connect-generate.png" style="width: 814px; margin-bottom: 8px;" alt="The Generate theme button in the Connect plugin UI." width="1628" height="400" />
+
+A theme containing the altered tokens is generated and displayed in the plugin's Theme tab.
+
+<img src="/static/material-ui/design-resources/connect-code-editor.png" style="width: 814px; margin-bottom: 8px;" alt="The generated theme displayed in the Connect plugin UI." width="1628" height="400" />
+
+You can also preview the generated theme and the customized tokens by navigating to the Storybook preview tab.
+
+<img src="/static/material-ui/design-resources/connect-storybook.png" style="width: 814px" alt="The generated theme previewed in Storybook in the Connect plugin UI." width="1628" height="400" />
+
+### Adding new tokens
+
+You can extend the existing tokens set with your own either by adding new variables to the existing local variable collections, or by adding new elevation and typography styles to the local style collections.
+After you've added your custom tokens, click on **Regenerate theme** to include these tokens in your theme.
+
+<img src="/static/material-ui/design-resources/connect-regenerate.png" style="width: 814px" alt="The Regenerate button in the Connect plugin UI." width="1628" height="400" />
+
+## Customizing components
+
+Connect can also generate theme styles for customized components, enabling you to completely change their look and feel and create your custom design system from within Figma.
+
+:::info
+This feature is currently limited to the Button and Switch components.
+Support for more components is coming soon.
+:::
+
+As an example, here's how to customize the checked state, medium size, and primary color of a Switch component to replicate the iOS design system:
+
+:::warning
+The Design Kit's component layer hierarchy and layer names must remain unaltered for Connect to correctly extract custom component styles and generate the theme.
+:::
+
+<img src="/static/material-ui/design-resources/connect-component-variant.png" style="width: 814px; margin-bottom: 8px;" alt="A specific variant of the Switch component selected in the Design Kit." width="1628" height="400" />
+
+Connect generates the following theme code for the customized Switch:
+
+```js
+{
+  components: {
+    MuiSwitch: {
+      styleOverrides: {
+        root: {
+          '&.MuiSwitch-sizeMedium:has(.MuiSwitch-colorPrimary)': {
+            '&:has(.Mui-checked):not(:has(.Mui-disabled)):not(:has(.Mui-focusVisible))':
+              {
+                width: '40px',
+                height: '21px',
+                padding: '0',
+                '& .MuiSwitch-switchBase': {
+                  transform: 'translateX(19px) translateY(2px)',
+                  padding: '0',
+                  '& .MuiSwitch-thumb': {
+                    width: '17px',
+                    height: '17px',
+                    background: '#FAFAFA',
+                  },
+                  '& + .MuiSwitch-track': {
+                    width: '38px',
+                    height: '21px',
+                    background: 'var(--mui-palette-success-light)',
+                    opacity: '1',
+                  },
+                },
+              },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+The generated theme targets classes that correspond to the specific Switch configuration defined above, so styles are only applied when the props and state of the Material UI component match those of the customized Figma component.
+
+To customize other states, you need to apply the desired design changes to each variant in Figma by following these steps:
+
+1. Customize a single "base" variant—for example, a Switch component in the checked state, of medium size, and primary color.
+2. Clone this variant and rename it to target the next variant you'd like to customize—for example, rename the cloned version of `Checked=True, Size=Medium, Color=Primary, State=Enabled` to `Checked=False, Size=Medium, Color=Primary, State=Enabled`.
+3. Delete the old versions of the same variant.
+4. Move the new version to the correct square in the variant grid.
+5. Make the necessary style adjustments to the variant's child layers.
+
+Repeat this process for each variant you want to customize.
+Here's an example of what this might look like:
+
+<img src="/static/material-ui/design-resources/connect-switch-component-customized.png" style="width: 814px; margin-bottom: 8px;" alt="A fully customized Switch component in the Material UI Design Kit." width="1628" height="400" />
+
+You can run Connect to generate a new theme.
+From here you can run Connect to generate a new theme—here's what would be generated from the example above:
+
+```js
+{
+  components: {
+    MuiSwitch: {
+      styleOverrides: {
+        root: {
+          "&.MuiSwitch-sizeMedium:has(.MuiSwitch-colorPrimary)": {
+            width: "40px",
+            height: "21px",
+            padding: "0",
+            "& .MuiSwitch-switchBase": {
+              padding: "0",
+              "& .MuiSwitch-thumb": {
+                width: "17px",
+                height: "17px",
+                background: "#FAFAFA",
+              },
+              "& + .MuiSwitch-track": {
+                width: "38px",
+                height: "21px",
+                borderRadius: "100px",
+                opacity: "1",
+              },
+            },
+            "&:not(:has(.Mui-checked)):not(:has(.Mui-disabled)):not(:has(.Mui-focusVisible))": {
+              "& .MuiSwitch-switchBase": {
+                transform: "translateX(3px) translateY(2px)",
+                "& + .MuiSwitch-track": {
+                  background: "#BDBDBD",
+                },
+              },
+            },
+            "&:not(:has(.Mui-checked)):has(.Mui-disabled):not(:has(.Mui-focusVisible))": {
+              "& .MuiSwitch-switchBase": {
+                transform: "translateX(3px) translateY(2px)",
+                "& + .MuiSwitch-track": {
+                  background: "rgba(229, 229, 229, 0.99)",
+                },
+              },
+            },
+            "&:not(:has(.Mui-checked)):not(:has(.Mui-disabled)):has(.Mui-focusVisible)": {
+              "& .MuiSwitch-switchBase": {
+                transform: "translateX(3px) translateY(2px)",
+                "& + .MuiSwitch-track": {
+                  border: "1px solid #000",
+                  background: "#BDBDBD",
+                },
+              },
+            },
+            "&:has(.Mui-checked):has(.Mui-disabled):not(:has(.Mui-focusVisible))": {
+              "& .MuiSwitch-switchBase": {
+                transform: "translateX(19px) translateY(2px)",
+                "& + .MuiSwitch-track": {
+                  background: "rgba(187, 231, 188, 0.99)",
+                },
+              },
+            },
+            "&:not(:has(.Mui-checked)):not(:has(.Mui-disabled)):not(:has(.Mui-focusVisible)):hover": {
+              "& .MuiSwitch-switchBase": {
+                transform: "translateX(3px) translateY(2px)",
+                "& + .MuiSwitch-track": {
+                  background: "#616161",
+                },
+              },
+            },
+            "&:has(.Mui-checked):not(:has(.Mui-disabled)):not(:has(.Mui-focusVisible))": {
+              "& .MuiSwitch-switchBase": {
+                transform: "translateX(19px) translateY(2px)",
+                "& + .MuiSwitch-track": {
+                  background: "var(--mui-palette-success-light)",
+                },
+              },
+            },
+            "&:has(.Mui-checked):not(:has(.Mui-disabled)):not(:has(.Mui-focusVisible)):hover": {
+              "& .MuiSwitch-switchBase": {
+                transform: "translateX(19px) translateY(2px)",
+                "& + .MuiSwitch-track": {
+                  background: "var(--mui-palette-success-dark)",
+                },
+              },
+            },
+            "&:has(.Mui-checked):not(:has(.Mui-disabled)):has(.Mui-focusVisible)": {
+              "& .MuiSwitch-switchBase": {
+                transform: "translateX(19px) translateY(2px)",
+                "& + .MuiSwitch-track": {
+                  border: "1px solid #000",
+                  background: "var(--mui-palette-success-light)",
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+:::info
+The generated theme may contain the CSS `has()` selector, which is used to target specific child classes.
+This selector is not used by other theme-related examples in the docs because it used to have limited browser support.
+It is now [supported by all modern browsers](https://caniuse.com/css-has).
+:::
+
+You can also check out the Storybook preview to test the Material UI version of your component.
+
+<img src="/static/material-ui/design-resources/connect-switch-component-customized-storybook.png" style="width: 814px" alt="A fully customized Switch component in Storybook." width="1628" height="400" />
+
+## Using the generated theme
+
+:::warning
+Themes generated by Connect must be used with Material UI's [`CssVarsProvider`](/material-ui/experimental-api/css-theme-variables/migration/)—the default [`ThemeProvider`](/material-ui/customization/theming/#theme-provider) is not supported.
+:::
+
+Here's an example of how to add a Connect theme to your codebase:
+
+```tsx title="_app.tsx"
+import {
+  experimental_extendTheme as extendTheme,
+  Experimental_CssVarsProvider as CssVarsProvider,
+} from '@mui/material/styles';
+
+export default function MyApp({ Component, pageProps }) {
+  const theme = extendTheme({
+    shape: {
+      borderRadiusRound: 999,
+    },
+    components: {
+      MuiSwitch: {
+        styleOverrides: {
+          root: {
+            '&.MuiSwitch-sizeMedium:has(.MuiSwitch-colorPrimary)': {
+              '&:has(.Mui-checked):not(:has(.Mui-disabled)):not(:has(.Mui-focusVisible))':
+                {
+                  width: '40px',
+                  height: '21px',
+                  padding: '0',
+                  '& .MuiSwitch-switchBase': {
+                    transform: 'translateX(19px) translateY(2px)',
+                    padding: '0',
+                    '& .MuiSwitch-thumb': {
+                      width: '17px',
+                      height: '17px',
+                      background: '#FAFAFA',
+                    },
+                    '& + .MuiSwitch-track': {
+                      width: '38px',
+                      height: '21px',
+                      background: 'var(--mui-palette-success-light)',
+                      borderRadius: 'var(--mui-shape-borderRadiusRound)',
+                      opacity: '1',
+                    },
+                  },
+                },
+            },
+          },
+        },
+      },
+    },
+  });
+
+  return (
+    <CssVarsProvider theme={theme}>
+      <Component {...pageProps} />
+    </CssVarsProvider>
+  );
+}
+```
+
+## Feedback and bug reports
+
+Use [the dedicated Connect feedback board](https://mui-connect.canny.io/feedback) to share feedback, report bugs, or drop feature requests.
diff --git a/docs/data/material/design-resources/material-ui-for-figma/material-ui-for-figma.md b/docs/data/material/design-resources/material-ui-for-figma/material-ui-for-figma.md
@@ -0,0 +1,94 @@
+# Material UI for Figma
+
+<p class="description">Enhance designer-developer collaboration between Material UI and Figma.</p>
+
+## Getting started
+
+Material UI for Figma consists of representations of the library's React components in Figma so designers and developers can communicate and iterate more efficiently.
+The kit includes:
+
+- components with the same design as Material UI
+- additional components and features not covered by Material Design
+- shared terminology from the React library for props, variables, design tokens, and other values
+
+### Community vs. full version
+
+The Material UI design kit is available in the [community (free) version](https://www.figma.com/community/file/912837788133317724/material-ui-for-figma-and-mui-x) and the [full (paid) version](https://mui.com/store/items/figma-react/).
+
+|                                   | Community | Full version |
+| :-------------------------------- | --------: | -----------: |
+| Components without customizations |       All |          All |
+| Components with customizations    |         4 |          All |
+| Figma variables                   |         - |           ✅ |
+
+### Installing the full version
+
+Start by extracting the `.zip` archive which contains the `.fig` files.
+Then you can either follow [Figma's import guide](https://help.figma.com/hc/en-us/articles/360041003114-Import-files-into-Figma) or [add it to your team library](https://help.figma.com/hc/en-us/articles/360041051154-Getting-Started-with-Team-Library).
+
+## Theme
+
+### Local variables
+
+The design kit uses Figma's local variables to create a collection of styles comparable to the theme structure of Material UI code.
+Follow the steps in the video below to see all the variables available:
+
+<iframe width="100%" height="490" src="https://www.youtube.com/embed/u3zR6p-OjKQ?si=DDVEsedwmJQeik3T" title="YouTube video player" frameborder="0" allowfullscreen></iframe>
+
+### Customizing colors
+
+Use the variables panel to customize colors as shown in the video below:
+
+<iframe width="100%" height="490" src="https://www.youtube.com/embed/YuzkWFm0-bA?si=XvgPR0vNGtiBPqKY" title="YouTube video player" frameborder="0" allowfullscreen></iframe>
+
+### Customizing typography
+
+Typography customization uses local styles rather than local variables.
+The experience is similar to modifying colors, as shown in the video below:
+
+<iframe width="100%" height="490" src="https://www.youtube.com/embed/HepVDfrLmak?si=gklG_3ZZyxDWzlPM" title="YouTube video player" frameborder="0" allowfullscreen></iframe>
+
+### Switching between light and dark modes
+
+The design kit uses Figma's local variables to let you toggle the variable mode between light and dark, as shown in the video below:
+
+<iframe width="100%" height="490" src="https://www.youtube.com/embed/ydTF1HhLnJM?si=1Fj4CFLgVavfg4Fz" title="YouTube video player" frameborder="0" allowfullscreen></iframe>
+
+## Components
+
+### Editing the main components
+
+You can use the [Similayer](https://www.figma.com/community/plugin/735733267883397781/Similayer) plugin to select multiple components at once that share some property.
+
+<iframe width="100%" height="490" src="https://www.youtube.com/embed/eHBk0FbS0P8?si=QbOiMU2F1yvGB6s8" title="YouTube video player" frameborder="0" allowfullscreen></iframe>
+
+### Table component
+
+#### Adding new columns
+
+The video below shows how to add new columns by detaching cells from their row components, allowing you to freely move content around.
+
+<iframe src="https://www.loom.com/embed/6dd71cc374bc4d84af35ebb75d107d38?sid=1d3a4790-4c28-433e-94ce-97dd969601dd" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="width: 100%; height: 500px;"></iframe>
+
+#### Adding new columns in the main component
+
+The Table and Data Grid components come with a limited number of columns by default.
+The video below shows how to add new columns by copying cells directly on the main component:
+
+<iframe width="100%" height="490" src="https://www.youtube.com/embed/s_n3LHm1daI?si=_QbXvtYPkc8EBd5d" title="YouTube video player" frameborder="0" allowfullscreen></iframe>
+
+## Code sync
+
+You can export theme tokens and component customizations to code using [the Connect plugin for Figma](/material-ui/design-resources/connect/).
+Material UI for Figma has been built to be as close to the React components as possible, making it for a fluid integration with code.
+
+Learn more about the Material UI theme structure by visiting the [Theming](https://mui.com/material-ui/customization/theming/) and [Default theme viewer](https://mui.com/material-ui/customization/theming/) pages.
+
+## Using new design kit versions
+
+We generally don't release breaking changes in the updates—we add new content instead.
+If you need to replace a single component that's been updated, there are a couple of options:
+
+1. Add the new version of the design kit as a library and use [the new Figma library swap feature](https://www.youtube.com/watch?v=GQ2jztKpxLk). The components must have the same names in both libraries.
+2. Observe the new component and re-apply the changes to the existing projects. This is the recommended approach when you need to update multiple projects.
+3. Copy and paste the new component into your existing project, give it a different temporary name, then re-link tokens to the new component. When using [Select Similar plugins](https://www.figma.com/community/plugin/792767780551514994/Select-Similar) this shouldn't take more than five minutes. Then you can remove the old component and update the new component name.