[material-ui][examples] Create a Storybook template

[sakulstra]

• I have searched the issues of this repository and believe that this is not a duplicate.

When working with material-ui you usually end up adjusting the typography, overwriting some global styles and so on to create your own "themed variant" of material-ui. Within material-ui some of these styles/overwrites affect another as e.g. Typography is part of more or less any other material-ui component. So adjusting typography might adjust tabs without you noticing. In our current workflow we have one relatively gigantic storybook showcasing all the components we have (including a re-export of basically all material-ui components).

I think it might be a good idea to create a "template" as part of material-ui to get new component libraries started more quickly & to share themed variants with no-code designers. The current "color selection theming" in the material-ui docs is relatively limited.

Summary 💡

It would be great if there was a "ready to go & up-to-date" storybook example within the examples folder to showcase all the components.

Examples 🌈

Sadly our storybook is closed source atm, but we might think about abstracting & open sourcing the material-ui part of it.

Motivation 🔦

Did this once manually, don't want to do it twice and I assume other companies have similar workflows.

---

Just when writing this:

The current "color selection theming" in the material-ui docs is relatively limited.

I started wondering if we couldn't just deploy a custom themed variant of the docs instead of doing things in storybook. Doing things in storybook would be nicer in terms of our testing setup, but the docs are much more in-detail as the ones we have in storybook 🤔
Is this sth people are doing?

---

OT: while writing that i was wondering if that actually is a feature request or would be better suited for discussions. I'd love if you enabled discussions, as e.g. in the styled-components tickets that's a pretty endless "discussion", but seems to not provide any value to the actual ticket.

[oliviertassinari]

@sakulstra This issue makes me think of #11242. I'm all in for exploring this path 👍.

What do you think about using your previous storybook to seed the exploration? Maybe we could create a new https://github.com/mui-org/material-ui-storybook repository with it. If it gets traction, we integrate the project back into the main repository?

Also, there is this alternative direction: #20275.

[sakulstra]

@oliviertassinari thanks for pointing me to these tickets - have to think about this a bit as all these things have a lot of drawbacks 😅

As I see it there are basically 3 suggestions for solving different problems

1. Maintaining a storybook example (this ticket)

Usecases: Kickstart themed & general ui development, Showcase components
Pro

• is likely to help a lot of people (at least from personal experience within the last 4 years, storybook as a widely accepted tool and there are barely react teams not using it)
• is usually well integrated into developer/testing workflows (if it's with chromatic or jest addon)

Con (#11242)

• just maintaining it outside(also inside) of material-ui brings a gigantic maintenance overhead as you have to write stories & demos¹

2. Shipping a docs generator

Usecase: Kickstart themed development, Showcase components
Pro

• probably doable without to much effort 🤔. Have to check the code, but one could probably "just alter the build pipeline to inject a theme". In a very basic implementation, people could build their own docs from checking out material-ui.

Con

• is likely to not integrate well with developers workflows dependent on the implementation
• forces you out of storybook at least for the material-ui part

3. Live customization in demos ([docs] Allow providing a custom theme and preview it live #20275)

Usecase: Allow people to play around with theming
Pro

• that's just very cool 🌈 🚀
• (might have to nice side-effect of teaching people how theming works #learningByDoing - I just joined a frontend team, where the theme usage can just be described as abusing. All material-ui functionality is literally destroyed.)

Con

• Disclaimer: it's not a real con: this is simply another usecase I think

¹I think "co-maintaining" this might be unreasonable. The docs are incredible good IMO and even with our current custom storybook implementation I checkout the docs from time to time :)
That said I'm wondering if one could generate the storybook stories & docs from material-ui/docs source to reduce maintenance burden & automatically get all the new features & fixes into the storybook.

[oliviertassinari]

I was looking at the sales metrics (over 50 days) and came to a very strange observation. We have two ads that link to the exact same URL:

A.

B.

Ad A. leads to 18% more clicks than ad B., however, if we look at the conversions to orders later down the road. We have a lot less $ for ad A. This makes me believe that there is a non-neglieable demand for themes on top of Material-UI (free or paid) that is poorly addressed.

What if we were moving with the following plan?

---

1. [material-ui][examples] Create a Storybook template #21111. We expose a storybook right from this repository. We automatically generate stories from the existing demos. We create a new category per parent folder and item per name of the demo. For instance, docs/src/pages/components/buttons/ButtonSizes.js turns into

This should be relatively easy to do. We can do the same as we do for the visual regression tests.

https://github.com/mui-org/material-ui/blob/8357c68cdc37c2b9c2a84891adb4df705f8ef155/test/regressions/index.js#L172

So, we create a new folder in the repository, let's say a /storybook folder that developers can clone. When they go into it, they must run a command to copy the demos from the version of Material-UI they have installed. It copies the demos from this repository, or update them if they upgrade to a new version. The repository has a section that explains how to customize the theme and how to add new stories. It can be used as a seed for a new design system. We make it MIT as it's an important foundation for what comes next.

2. Add global presets of MD2 "Material Studies" for the theme provider #18908. We provide multiple built-in themes. Something a developer can import as easy as follow.

import AntdTheme from '@material-ui/core/antd-theme';
import { ThemeProvider, createMuiTheme } from '@material-ui/core/styles';

<ThemeProvider theme={createMuiTheme(AntdTheme)}>
  <YourApp />
</ThemeProvider>

I would say that 1 or 2 should be enough to make a point that it's possible and well supported

3. [docs] Allow providing a custom theme and preview it live #20275. We make it possible to copy and paste a theme and to see it live on the documentation.
4. Community themes #21113. We list a couple of popular themes from the community, that they can preview right in the documentation, maybe using an external fetch.
5. material-ui-theme-editor Update #17991. We create a theme builder/design system builder. Something developers can use to quickly create a new theme. If it could output a ready storybook, Figma and Sketch assets at the same time, it would be awesome, even something we could make behind a subscription service.
6. We enable third-party authors to sell gorgeous themes. It would contain the documentation, using the storybook of 1. as well as Figma and Sketch assets.

cc @mui-org/core

[sakulstra]

That sounds actually great! I might try to prototype sth on the weekend - in essence, what we need for 1 would be some script that simply copies demos into a folder and enriches them with some csf as I get it?

[oliviertassinari]

@sakulstra Yes. What does "csf" mean?

[sakulstra]

sorry for the unnecessary abbreviation especially as I just learned what it means a few days ago as well 😅
component-story-format(csf)

[sakulstra]

Short update on this:
I wrote a little codemod which essentially transforms the tsx files inside docs/src/components to named export & adds a new default export for component-story-format syntax. https://github.com/sakulstra/material-ui/blob/cdd40f3bf8aac0bed41a3fa2c9cd6561fb4f9a25/storybook-starter/scripts/csf-transform.js ... it worked for most components out of the box.

It that the correct direction. Wdyt?

Issues I faced so far:

1. Typescript support for defining component Interface through React interface reactjs/react-docgen#387 - for new we don't have prop type docs for ts. Might be solved at some point 🤷‍♂️
2. Some demos use 3th party libraries (e.g. material-table) which we would have to either install or drop the demos
3. It's a lot of stories and i'm not sure if all of them are actually useful
4. i tried to make this work with typescript, but there might be users using storybook with js as well 🤔
5. the codemod currently breaks export default withStyles() statements as that's not easily transformable to a named export. For the sake of "quickly testing this" I just removed the corresponding stories.

edit: cleaned this up a bit, using vanilla storybook over tsdx:
https://github.com/sakulstra/material-ui/pull/2/files#diff-a09da5a06815b8e6589db87b874bb247
https://github.com/sakulstra/material-ui/pull/2/files#diff-c5cace55ad6e0ec26be98ee19fe0dac2

[oliviertassinari]

@sakulstra Oh wow, I wasn't expecting an update that soon 😍. A couple of feedback.

2. For the third-party libraries, the documentation has a module to resolve the required dependencies and the version to run all the demos in CodeSandbox. We could share this util. There are definitely a lot of missing dependencie.
3. The more the merrier 🤷‍♂️, but we could ignore the same one that we ignore for the visual regression tests. After all, isn't the objective the same? https://github.com/mui-org/material-ui/blob/5f2a237ff689ef067b048459e82dd05379069658/test/regressions/index.js#L20. I would also fix the broken story issues: https://github.com/sakulstra/material-ui/pull/2/files#diff-a09da5a06815b8e6589db87b874bb247R21.
4. What about we go full TypeScript? Developers would still be able to add new JavaScript stories anyway?
5. We could potentially migrate them to hook. But I'm not sure it's worth spending time on.

---

6. Are you sure we should bundle prettier? https://github.com/sakulstra/material-ui/blob/cdd40f3bf8aac0bed41a3fa2c9cd6561fb4f9a25/storybook-starter/package.json#L31 I would expect developer already have a custom prettier config in their repository.
7. v8 as the other packages? https://github.com/sakulstra/material-ui/blob/cdd40f3bf8aac0bed41a3fa2c9cd6561fb4f9a25/storybook-starter/package.json#L11
8. Please no pre-commit rules https://github.com/sakulstra/material-ui/blob/cdd40f3bf8aac0bed41a3fa2c9cd6561fb4f9a25/storybook-starter/package.json#L28.
9. I believe the /stories/components/ folder should be empty: https://github.com/sakulstra/material-ui/tree/cdd40f3bf8aac0bed41a3fa2c9cd6561fb4f9a25/storybook-starter/stories/components. (add it to the .gitignore?)
10. Vuetify has a similar package we can use to benchmark: https://github.com/nidkil/vuetify-with-storybook.
11. Would it make sense to add the @storybook/addon-viewport plugin and have it configured using the theme.breakpoints values?
12. I don't understand what we need the tsdx dependency.

[sakulstra]

Oh wow, I wasn't expecting an update that soon heart_eyes

We might want to sue this soonish internally so it didn't make sense to wait 😅

2)3) will check that out
4) i'm personally fine with that
5) It's just Hidden and SwipeableTextMobileStepper - might refactor it or adjust the jscodeshift to be a bit more clever about replacing exports

---

I think you looked at an outdated commit 🙊 https://github.com/sakulstra/material-ui/pull/2/files
6) comes with tsdx, which i already dropped¹
7) i don't care to much, but 8 is EOL afaik (https://github.com/nodejs/Release) - would discourage usage if possible
8) see 6)
9) 🤔, you mean it should come empty by default and people have to run the script on their own? Having this "synced" with the current codebase would have the advantage of dropping that step. For me it's not clear yet how the distribution path will look like 🤔
10) thanks for the ref, will check that out 👍
11) It might, have to think about how to actually do the theming part as well - probably just a global decorator expecting src/theme.ts to exist or sth like that
12) see 6)

¹I initially started of with tsdx as that's what I currently use, dropped it though as not everyone might want to use it. Comes in handy though if you want to develop your "ui-kit"/themed material-ui as a stand-alone package.

[oliviertassinari]

@sakulstra Did you make progress with the storybook template? :)

[sakulstra]

Sadly, not at all - won't get to it before the end of next week :/
feel free to pick it up though

[sakulstra]

@oliviertassinari sorry i wont get back to this in the nearest future due to limited and more pressing things :(

[lancegliser]

I've been having a conversation on Twitter with @MaterialUI about a sidecar, parallel feature to this. Just for quick context to wrap that conversation here:

I can imagine a docs page that points developers to a naive approach that provides one step composition to the official version, with users guided toward the fully themed localized approach in that issue when it's complete. Stronger initial hook, before moving to a purchase.

I'd personally prefer the full implementation that includes theme as discussed here. The Storybook team might be excited to have that basic option. Both options depend on this issue, which looks like it could use a hand. Would ya'll be interested in outside contribution to get this moving forward? Any specific issues I could help target if this is a little too tightly constrained? My time is a little constrained, but I'm interested.

[shilman]

@lancegliser thanks so much for getting this conversation on my radar. for my part, i can do my best to prioritize storybook issues that improve the dev experience for MUI, as I've already done in the case of #12734. i believe @tooppaaa is also interested in contributing.

[oliviertassinari]

@lancegliser It seems that there are a couple of different topics related to a tighten integration with Storybook, I'm not sure which one should be focused on:

1. Material-UI using Storybook. We are using it for some use cases in https://github.com/mui-org/material-ui-x. We always work documentation first, but Storybook is great for us when the case doesn't fit in the documentation, nor in the end-to-end tests, nor in the visual regression tests. We maintained a list of edge cases in Storybook. We could probably extend its usage for listing the end-to-end tests and listing visual regression tests. Regarding why we are not using Storybook more: we need to experience our docs first-hand, it's slower to load than Next.js, it lacks server-side rendering support, the environment is too isolated (disconnects us to real life). I personally feel more productive working inside the Next.js documentation than inside the Storybook but not all the maintainers feel the same.
2. A Storybook template generator. A tool to pull out the demos from Material-UI and quickly create one for your components. When I talk with users of the library, what most seem to want is the capability to generate custom documentation like the one we have on http://material-ui.com/. However, I think that it's not in opposition to having the capability to quick start a lot of demos. @kutnickclose how did you solve this problem in the end?
3. A Storybook inside Material-UI. It's a reference to https://storybook.js.org/docs/react/workflows/storybook-composition. I have to admit, I don't understand the use cases for a developer using Material-UI. It would be great to provide more information :).
4. Storybook using Material-UI. I recall they were experimentation with it for Storybook v4 two years ago https://github.com/storybookjs/SBNext. With Material-UI v5 coming with emotion instead of JSS and unstyled components, or even planning a non-Material Design base theme Support a second design system #22485, maybe some of the blockers were solved 🤷‍♂️.

---

@lancegliser I don't follow the logic around the commercialization aspects of this issue "Stronger initial hook, before moving to a purchase". My comment in #21111 (comment) might have led you down this road. However, I think that better integration with Storybook can be interesting independently.

At this point, I think that what's important is to maximize adoption, focus on the points before 5. and 6.

In 5. I was referring to leveraging the best ideas from existing attempts, e.g. anima, Modulz. It seems that anima gets the integration with designers right. They have created a plugin for Figma/Sketch/AdobeXD. Modulz seems to get the importance of allowing designers and developers to interact on the same content, as well as the generation of the documentation right. If we were to go down this road, we would raise, starting by building a plugin for Figma, create a SaaS to store your components, have a GitHub integration to sync them with your code, have a way to generate high-quality documentation for it. However, we likely have identified a better opportunity ahead so I can't say if we will pursue this one (at least not first, e.g. give it two years for the unstyled components #6218 to gain traction).

In 6. and in hindsight, data suggests the opportunity cost is too high relative to other problems. It's likely not worth carrying, we have a store this could be enough. Our latest plan on this is to build a second and only theme: #22485. Then, have premium templates for it.

Would ya'll be interested in outside contribution to get this moving forward?

Yes!

[kutnickclose]

for point 2, I:

1. copied https://github.com/sakulstra/material-ui/pull/2/files
2. Separately, I did a Create React App w/ typescript and added Storybook 6
3. manually copied over the generated results from point 1 above. (note: I also had to change https://github.com/sakulstra/material-ui/pull/2/files#diff-091fd7e09f049e1b700bd85156091bf83c38d3edec473feeea4a200f9753f857R23 slightly to get it to work for storybook 6 which came out after this PR. I think I changed it from Material-ui|${component}|${test} to Material-ui/${component})
4. I needed to install a lot of dependencies and @types before it would compile
5. Added a preview.js file kinda like this to see light/dark theme

import React from 'react';
import { ThemeProvider } from "@material-ui/styles";
import { CssBaseline, createMuiTheme } from "@material-ui/core";

const darkTheme = createMuiTheme({
  palette: {
    type: 'dark',
  },
});

const lightTheme = createMuiTheme();

export const globalTypes = {
  theme: {
    name: 'Theme',
    description: 'Global theme for components',
    defaultValue: 'light',
    toolbar: {
      icon: 'circlehollow',
      items: ['light', 'dark'],
    },
  },
};

const withThemeProvider = (Story,context) => {
  const theme = context.globals.theme === 'light' ? lightTheme : darkTheme

  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      <Story {...context} />
    </ThemeProvider>
  )
}

export const decorators = [withThemeProvider];

6. for deployment, there's a storybook deployer addon that can deploy to github pages which is nice for public storybooks but wasn't an option for the private storybook I worked on.

My biggest complaint is that storybook doesn't auto-detect the controls of a component. Their docs specifically state that the controls won't be auto detected if "You're trying to generate controls for a component defined in an external library" https://www.npmjs.com/package/@storybook/addon-controls.

[mbrookes]

It might be overkill, but it seems like you could repurpose much of https://github.com/mui-org/material-ui/tree/next/framer/scripts to create the annotated wrapper shown in https://www.npmjs.com/package/@storybook/addon-controls#my-controls-arent-being-auto-generated-what-should-i-do. It does something similar for Framer controls.

[shilman]

My biggest complaint is that storybook doesn't auto-detect the controls of a component. Their docs specifically state that the controls won't be auto detected if "You're trying to generate controls for a component defined in an external library" npmjs.com/package/@storybook/addon-controls.

We might be able to fix this as part of improving MUI support in Storybook. @mbrookes your workaround sounds great as a short-term fix.

That said, if you place the stories alongside the MUI library and refer to them with relative paths, it should "just work" (famous last words).

[danielvianna]

I am building a Design System with MUI + other third party components changing them to look like MUI, I think this is important
Are you guys using storybooks privately or only on grid-x?

[ricardodoberstein]

I am building a Design System with MUI + other third party components changing them to look like MUI, I think this is important
Are you guys using storybooks privately or only on grid-x?

It would be awesome if MUI supported this out of the box. 👍

[oliviertassinari]

Are you guys using storybooks privately or only on grid-x?

@danielvianna Answered in point 1. of #21111 (comment)

It would be awesome if MUI supported this out of the box

@ricardodoberstein if you could expand on the pain, and the solution you envision, it would greatly help us shape a solution.

[danielvianna]

@oliviertassinari we started privately but it took so much time to pull basic components into stories that we gave up (the same thing as you have in docs). We are not using grid-x yet* (maybe will soon)
The challenge is that on top of material UI we also building custom components, so just the effort to make them work is already too much work for a startup with 2 frontend guys only, as we need to focus on making the system work and focus on product-market fit. I'm working on a system that is not the typical CRM, but it involves video streaming, control of robotic cameras, AI machine vision, and many things that material wouldn't have. The initial idea was just really to get a collection of the basic stuff and see when we make changes how the impact would be and compare visually the design. We not only have different components - I'm talking about new smaller "atoms" but also combination "molecules" "pages"

[eudinnou]

Our first internal solution is this patch: https://gist.github.com/eudinnou/e7f5a73f7441bf138d2c583c243abc1a following these steps:

1. clone the repo and checkout the tag version that you need
2. apply the patch
3. run yarn
4. run yarn docs:build-bundle

Usage:

import { MuiDocs } from 'mui-docs';
import theme from 'your custom theme';

const Wrapper = ({ children }) => (
  <MuiDocs.Providers theme={theme}>{children}</MuiDocs.Providers>
);

export const Accordion = () => (
  <Wrapper>
    <MuiDocs.Accordion />
  </Wrapper>
);

...

Additionally, we also copied some static images from docs/public/static and prism-okaidia.css.

[ryota-murakami]

@eudinnou That's really reasonable for create default MUI components Storybook. 😀
I used to have a project that was converted from MUI's Components Docs to Storybook, but it is not currently maintained as I am mainly working on the backend now.

storybook: https://main--632a01c394385880b3383063.chromatic.com/?path=/docs/components-alert--default
repo: https://github.com/laststance/mui-storybook

Recently I saw a blog post on the official Storybook blog about how to handle MUI Components in Storybook in a way that is partially similar to my approach.
https://storybook.js.org/blog/material-ui-in-storybook/

I have a complaint about generating from the TS type information in docgen only results in a useless Object button for parameters other than primitive types, and does not create a control panel where you can intuitively learn all the various parameters a component can accept.

I think MUI Official Team could make better Storybook for all MUI default compoments. 😎

[ShaunEvening]

Hey @ryota-murakami! I'm a Developer Experience Engineer for Storybook 😁 I wrote the article that you mentioned.

You're right that our controls for object props aren't ideal. Do you have a way that you envisioned being able to control object types?

---

Hey friends!

I recently put together an example repository for Material UI and Storybook for our recent article, Material UI in Storybook.

I'd be happy to expand on it a bit and put up a PR for the examples directory.

[ryota-murakami]

@integrayshaun Thank you for reacting to my comment!
Frankly, I don't think it is possible to generate control UI other than scaler values with the current docgen-typescript.
Therefore , it will be necessary to manually write Controls Addon settings.
this will need a lot of community contribution and time...

I'm working as a backend engineer now so I don't use MUI and Storybook heavily.
I hope Storybook/MUI official and community will produces better integration Storybook x MUI, and I'm glad to see it when I bring back frontend in the future! 😄