Open sakulstra opened 4 years ago
@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.
@oliviertassinari thanks for pointing me to these tickets - have to think about this a bit as all these things have a lot of drawbacks :sweat_smile:
As I see it there are basically 3 suggestions for solving different problems
Usecases: Kickstart themed & general ui development, Showcase components Pro
Con (#11242)
Usecase: Kickstart themed development, Showcase components Pro
Con
Usecase: Allow people to play around with theming Pro
Con
¹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.
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?
docs/src/pages/components/buttons/ButtonSizes.js
turns intoThis should be relatively easy to do. We can do the same as we do for the visual regression tests.
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.
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
cc @mui-org/core
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?
@sakulstra Yes. What does "csf" mean?
sorry for the unnecessary abbreviation especially as I just learned what it means a few days ago as well :sweat_smile: component-story-format(csf)
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:
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
@sakulstra Oh wow, I wasn't expecting an update that soon 😍. A couple of feedback.
/stories/components/
folder should be empty: https://github.com/sakulstra/material-ui/tree/cdd40f3bf8aac0bed41a3fa2c9cd6561fb4f9a25/storybook-starter/stories/components. (add it to the .gitignore?)theme.breakpoints
values?tsdx
dependency.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 :sweat_smile:
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 :speak_no_evil: 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) :thinking:, 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 :thinking: 10) thanks for the ref, will check that out :+1: 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.
@sakulstra Did you make progress with the storybook template? :)
Sadly, not at all - won't get to it before the end of next week :/ feel free to pick it up though
@oliviertassinari sorry i wont get back to this in the nearest future due to limited and more pressing things :(
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.
@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.
@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:
@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 https://github.com/mui-org/material-ui/issues/21111#issuecomment-631037264 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!
for point 2, I:
Material-ui|${component}|${test}
to Material-ui/${component}
)
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 (
) }
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.
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.
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).
Any further movement on this? Been struggling to implemnent storybook, seems blocked by #24282
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?
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. 👍
Are you guys using storybooks privately or only on grid-x?
@danielvianna Answered in point 1. of https://github.com/mui-org/material-ui/issues/21111#issuecomment-734496442
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.
@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"
Our first internal solution is this patch: https://gist.github.com/eudinnou/e7f5a73f7441bf138d2c583c243abc1a following these steps:
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
.
@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. 😎
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.
@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! 😄
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:
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 :thinking: 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.