[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 :(