Connect is a Figma plugin that generates Material UI themes directly from design to code.
+ +## 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. +::: + +
+
+## 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.
+
+
+
+## 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.
+
+
+
+Then open the Connect plugin and click on **Generate theme**.
+
+
+
+A theme containing the altered tokens is generated and displayed in the plugin's Theme tab.
+
+
+
+You can also preview the generated theme and the customized tokens by navigating to the Storybook preview tab.
+
+
+
+### 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.
+
+
+
+## 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.
+:::
+
+
+
+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:
+
+
+
+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.
+
+
+
+## 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 (
+ Enhance designer-developer collaboration between Material UI and Figma.
+ +## 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: + + + +### Customizing colors + +Use the variables panel to customize colors as shown in the video below: + + + +### Customizing typography + +Typography customization uses local styles rather than local variables. +The experience is similar to modifying colors, as shown in the video below: + + + +### 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: + + + +## 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. + + + +### 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. + + + +#### 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: + + + +## 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. diff --git a/docs/data/material/getting-started/design-resources/design-resources.md b/docs/data/material/getting-started/design-resources/design-resources.md index a99aeb2c28a711..97b939668f0230 100644 --- a/docs/data/material/getting-started/design-resources/design-resources.md +++ b/docs/data/material/getting-started/design-resources/design-resources.md @@ -2,12 +2,26 @@Be more efficient designing and developing with the same library.
-## Official kits +## Design kits -Pick your favorite design tool to enjoy and use the Material UI component inventory, including over 1,500 unique elements with their full range of states and variations. +Material UI component designs are available for Figma, Sketch, and Adobe XD, providing accurate representations using shared terminology for all states, variants, and permutations of each component. + +The design kits are composed of over 1,500 unique elements built to speed up the development process and ease communication for teams of designers and developers using the library. {{"component": "modules/components/MaterialUIDesignResources.js"}} +## Connect Figma plugin + +Connect is a Figma plugin to help bridge the gap between designers and developers using Material UI. + +It generates a theme file that you can add to your codebase with all the design tokens and component customizations from Figma. +You can quickly preview all of the changes through an embedded Storybook panel directly in the plugin interface. + +Connect is currently in beta and [available for free](https://www.figma.com/community/plugin/1336346114713490235/) in the Figma Community. +Head over to [the Connect page](/material-ui/design-resources/connect/) to learn more. + +
+
## Third-party resources
### UXPin
diff --git a/docs/data/material/pages.ts b/docs/data/material/pages.ts
index ee15159b9f27f6..42e4311a4f3b4d 100644
--- a/docs/data/material/pages.ts
+++ b/docs/data/material/pages.ts
@@ -327,6 +327,21 @@ const pages: MuiPage[] = [
{ pathname: '/material-ui/discover-more/changelog' },
],
},
+ {
+ pathname: '/material-ui/design-resources',
+ title: 'Design resources',
+ children: [
+ {
+ pathname: '/material-ui/design-resources/material-ui-for-figma',
+ title: 'Material UI for Figma',
+ },
+ {
+ pathname: '/material-ui/design-resources/connect',
+ title: 'Connect plugin',
+ beta: true,
+ },
+ ],
+ },
{
pathname: 'https://mui.com/store/?utm_source=docs&utm_medium=referral&utm_campaign=sidenav',
title: 'Template store',
diff --git a/docs/pages/material-ui/design-resources/connect.js b/docs/pages/material-ui/design-resources/connect.js
new file mode 100644
index 00000000000000..ab121664c18d87
--- /dev/null
+++ b/docs/pages/material-ui/design-resources/connect.js
@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from 'docs/data/material/design-resources/connect/connect.md?muiMarkdown';
+
+export default function Page() {
+ return