various changes and tweaks

docs/data/material/design-resources/connect/connect.md

@@ -7,12 +7,6 @@
 [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/).
 You can customize design tokens and components, export the generated theme as a JSON file, and visualize your customizations through an embedded Storybook instance.
 
-:::info
-This plugin is in beta.
-Component customization support is currently limited to the Button, Switch, and Typography components.
-More components will follow soon!
-:::
-
 :::warning
 Connect works in combination with the Material UI for Figma Design Kit [v5.16.0 and later](https://github.com/mui/mui-design-kits/releases).
 Other kits, such as the Joy UI Design Kit, are not supported yet.
@@ -32,12 +26,12 @@ Select the Design Kit file.
 
 ## Customizing design tokens
 
-Design tokens consist of the styles that are defined through Figma's [local variables](https://help.figma.com/hc/en-us/articles/15145852043927-Create-and-manage-variables) and [local styles](https://help.figma.com/hc/en-us/articles/360039820134-Manage-and-share-styles#:~:text=Local%20styles%20are%20styles%20that,or%20from%20the%20style%20picker.).
+Design tokens consist of the reusable styles that are defined through the design kit's [local variable collections](https://help.figma.com/hc/en-us/articles/15145852043927-Create-and-manage-variables) (i.e. palette, breakpoints, shapes & spacing) and [local effect and text styles](https://help.figma.com/hc/en-us/articles/360039820134-Manage-and-share-styles#:~:text=Local%20styles%20are%20styles%20that,or%20from%20the%20style%20picker.) (i.e. elevations and typography).
 
-### Existing tokens
+### Altering existing tokens
 
 The Material UI 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/).
-Connect can read all of the existing tokens in the theme.
+Connect can read all of the existing tokens present in the design kit, and generate a theme containing all customizations made to these tokens.
 
 To customize them using local variables, open the modal by clicking on the filter icon as shown below.
 Tweak any of the variables available there as you see fit.
@@ -51,73 +45,104 @@ The theme will then be updated in the code editor with your customizations.
 
 ### Adding new tokens
 
-You can add custom tokens such as new colors or shadows to the existing list.
-After adding them, click on **Regenerate theme** again to see them in the code editor tab.
+Next to altering the existing tokens that come out of the box, you can also create your own custom tokens either by creating new variables in the existing local variable collections (i.e. palette, shape, breakpoints, spacing) or by creating new elevation or typography styles.
+After you've added your custom tokens, click on **Regenerate theme** again to includes these tokens in your theme.
 
-## Customizing the components
+## Customizing components
 
-You can customize how a component looks in all of its variants and states and generate its theme using Connect.
+You can customize how a component looks in all of its variants, and generate its theme using Connect. Connect will generate the appropriate theme styles for the customized variants.
+
+:::info
+This feature is currently limited to the **Button** and **Switch** components.
+:::
+
+:::warning
+The default component layer names and hierarchy should not be changed in order for Connect to generate the correct theme output. You can however freely alter all style properties of each layer.
+:::
 
 <video controls muted loop width="1584" height="1080" style="border-radius: 12px; border: 1px solid; border-color: hsla(0, 0%, 0%, .1);">
   <source src="/static/material-ui/design-resources/custom-component.mp4" type="video/mp4">
 </video>
 
 ## Using the generated theme
 
-The code generated by Connect uses [the `CssVarsProvider` API](/material-ui/experimental-api/css-theme-variables/migration/) under the hood.
-This primarily impacts you if your project supports both light and dark modes, whereas component customization code should work on your theme regardless of which API you're using because Connect utilizes CSS classes to target component slots.
+The theme generated by Connect is meant to be used in combination with Material UI's [`CssVarsProvider`](/material-ui/experimental-api/css-theme-variables/migration/). While using the generated theme together with the default [`ThemeProvider`](/material-ui/customization/theming/#theme-provider) might work in some cases it is not recommended.
 
 ### Theme tokens
 
-For example, say you've changed the primary main color in light mode as well as the border-radius value.
-This is how your code should be inserted into your theme:
+For example, say you've changed the border-radius token by in the design kit altering the `local variable > shape > borderRadius` variable value from 4 to 12.
+
+<img src="/static/material-ui/design-resources/connect-border-radius.png" style="width: 814px" alt="A screenshot of the Connect plugin UI highlighting the Generate theme button." width="1628" height="400" />
+
+This is what the theme generated by Connect will look like:
 
 ```js
-const theme = extendTheme({
-  colorSchemes: {
-    light: {
-      palette: {
-        primary: {
-          main: '#BBDEFB', // example color
-        },
-      },
-    },
-  },
+{
   shape: {
     borderRadius: 12,
-  },
-});
+  }
+}
 ```
 
-:::info
-The `colorSchemes` node and `extendTheme` function are the only elements particular to the `CssVarsProvider` API.
-Remove the former and change the latter to `createTheme` if you're using [the standard `ThemeProvider` API](/material-ui/customization/theming/) instead.
-:::
+You can then copy this object and paste it into Material UI's [`extendTheme`](https://mui.com/material-ui/experimental-api/css-theme-variables/customization/) function and use the function's output in the `CssVarsProvider` in your app's root component:
+
+```ts
+import {
+  experimental_extendTheme as extendTheme,
+  Experimental_CssVarsProvider as CssVarsProvider,
+} from "@mui/material/styles";
+
+export default function App({ Component, pageProps }) {
+  const theme = extendTheme({
+    shape: {
+      borderRadius: 12,
+    }
+  });
+
+  return (
+    <CssVarsProvider theme={theme}>
+      <Component {...pageProps} />
+    </CssVarsProvider>
+  );
+}
+```
+
+### Component customizations
+
+Next to theme tokens Connect also generates custom component styles (currently limited to the **Button** and **Switch** components).
 
-## Component customizations
+For example, imagine you've customized a variant of the Switch component to resemble an iOS switch instead of the default Material Design style.
 
-The code Connect generates for component customizations can be copied and pasted into your theme's `component` node.
-For example, imagine you've customized the Switch's track and thumb size.
-Here's how you'd add the code to your theme:
+<img src="/static/material-ui/design-resources/connect-switch.png" style="width: 814px" alt="A screenshot of a customized Switch component" width="1628" height="400" />
+
+Here's how the theme generated by Connect would look:
 
 ```js
-const theme = createTheme({
+{
   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(20px) translateY(5px)',
+                  transform: 'translateX(19px) translateY(2px)',
+                  padding: '0',
                   '& .MuiSwitch-thumb': {
-                    width: '15px',
-                    height: '15px',
-                    boxShadow: 'none',
+                    width: '17px',
+                    height: '17px',
+                    background: '#FAFAFA',
                   },
                   '& + .MuiSwitch-track': {
-                    height: '20px',
+                    width: '38px',
+                    height: '21px',
+                    borderRadius: '999px',
+                    background: 'var(--mui-palette-success-light)',
+                    opacity: '1',
                   },
                 },
               },
@@ -126,15 +151,15 @@ const theme = createTheme({
       },
     },
   },
-});
+}
 ```
 
 You can clean it up further by removing all of the `has()` pseudo-classes.
 Connect needs those to be able to isolate changes made through Figma, but you might not need it on your code.
 Here's the updated code:
 
 ```js
-const theme = createTheme({
+const theme = extendTheme({
   components: {
     MuiSwitch: {
       styleOverrides: {