search

mui / material-ui

Material UI: Comprehensive React component library that implements Google's Material Design. Free forever.
https://mui.com/material-ui/
MIT License
93.51k stars 32.18k forks source link

[material-ui][docs] Refine the free templates page #41469

Open zanivan opened 6 months ago

zanivan commented 6 months ago

Summary

After wrapping up the first round of design refresh that this https://github.com/mui/material-ui/issues/37555 issue is going for, we'll do a global revision so that every template feels like part of a single app. So, this issue gathers small adjustment opportunities that have surfaced through working on all templates so far.

Tasks

https://github.com/mui/material-ui/assets/3165635/31b0d917-535d-49fc-aea1-1ece6331fcc8

More generally, @oliviertassinari thinks that having this type of layout https://blocks.tremor.so/templates would be amazing, I would want to use this 👌✨:

SCR-20240601-shhh SCR-20240610-tvam SCR-20240703-rndg

More context on why it could be valuable: https://github.com/mui/material-ui/issues/14604. It becomes something they can then just click on export, and have it working as a starting point.

But to look at the GA event first on Joy UI to see the use. It's only a guess, maybe nobody uses it.

Search keywords

template

zanivan commented 5 months ago

41947 was a short term solution for dark/light theme switching in the templates' page. However, a long term solution would be to have a script that generates these images automatically, like we have for Joy UI. @siriwatknp can you help me with this?

zanivan commented 4 months ago

@oliviertassinari I'll answer the items here, to make things more organized, since this issue is to track the improvements for template's page—feel free to add items or ideas here as well 💙

about https://github.com/mui/material-ui/pull/41757#issuecomment-2143550531:

7.4 When I go to the source, it's a struggle to use this. Would it be much better if everything was in a single file? With I guess the theme not inside it though. Since, down the line, this theme toggle will be the one between Material Design (custom MUI made) and Joy Design

  1. Merge all the sources of the templates into a single file. Make it much easier to copy and paste into your project (might demand a bit more research but likely to be much better)

Is this related to https://mui-org.slack.com/archives/C061V6JNZ9Q/p1708354100659669 somehow? If so, what would be the best file structure in your opinion?

7.5 The different custom theme templates don't share the same theme if I understand this right. I would have expected the opposite.

The only different theme is the Dashboard. This is because the approach for the other templates was more focused on following marketing UI trends. For the Dashboard, the theme design is lighter and more sober, as it is intended for SaaS and tooling.

danilo-leal commented 3 months ago
  1. Merge all the sources of the templates into a single file. Make it much easier to copy and paste into your project (might demand a bit more research but likely to be much better)

Mixed feelings about this one—I'm not sure about this. I think having everything on one gigantic file is much harder to deal with. Even if you're copying the whole template to use it almost without any customizations, it will be very hard to find yourself amidst a file that will very likely have thousands of lines if you want to change just the logo or a little icon or anything like that.

oliviertassinari commented 3 months ago
  1. Is this related to https://mui-org.slack.com/archives/C061V6JNZ9Q/p1708354100659669 somehow? If so, what would be the best file structure in your opinion?

@zanivan Right, it sounds related. For the theme file, I agree, I think it should be separate from the template files. I was more thinking of https://github.com/mui/material-ui/tree/v5.15.19/docs/data/material/getting-started/templates/dashboard. It feels a bad DX. @mbrookes added this back in the days with https://github.com/mui/material-ui/pull/12410. It's infinitely better than nothing, but when compared to some of the other options out there, I don't see how we can make accessing the source of templates from the GitHub UI a great DX.

The only different theme is the Dashboard. This is because the approach for the other templates was more focused on following marketing UI trends. For the Dashboard, the theme design is lighter and more sober, as it is intended for SaaS and tooling.

It reminds me of https://www.notion.so/blog/migrating-notion-marketing-to-next-js "It got to a point where we felt our entire codebase would be easier to maintain by splitting the app and marketing site apart". But I don't know, it feels like Notion's engineering team gave up, running out of time, they took the technical/design dept path. If Vercel can use the same Tailwind CSS config for its marketing and dashboard app, the same theme could work? Now, if we have a base theme, and an extension of it with small tweaks depending on the case, I think this could work close enough.

  1. Mixed feelings about this one—I'm not sure about this. I think having everything on one gigantic file is much harder to deal with. Even if you're copying the whole template to use it almost without any customizations, it will be very hard to find yourself amidst a file that will very likely have thousands of lines if you want to change just the logo or a little icon or anything like that.

@danilo-leal It's easier for me to search in one file than multiple, and I know I will need to use the search feature no matter what. So I would have a better time with one big file. Maybe it's just me, like I'm an advocate for things like this: https://github.com/nodejs/node/blob/main/lib/fs.js. For example https://github.com/mui/material-ui/blob/next/packages/mui-material/src/Autocomplete/Autocomplete.test.js, it works well for me.

zanivan commented 3 months ago

It reminds me of https://www.notion.so/blog/migrating-notion-marketing-to-next-js "It got to a point where we felt our entire codebase would be easier to maintain by splitting the app and marketing site apart". But I don't know, it feels like Notion's engineering team gave up, running out of time, they took the technical/design dept path. If Vercel can use the same Tailwind CSS config for its marketing and dashboard app, the same theme could work? Now, if we have a base theme, and an extension of it with small tweaks depending on the case, I think this could work close enough.

Sure thing! I think both themes can work for both applications (and an e-commerce template in the future) if we polish them. Since I have already designed the two themes, we can have a theme selector with the default style plus these two options. Maybe we can call one 'Sober' and the other 'Sleek' (inspired by the Base UI marketing page 😅).

@danilo-leal It's easier for me to search in one file than multiple, and I know I will need to use the search feature no matter what. So I would have a better time with one big file.

In this case, I believe that if we design the experience well enough, we can provide both options. I created an example where we can have a complete theme file with all styles that can be copied to the clipboard, and a button to access the template folder, with a well-organized and structured project.

In this prototype, we can offer a more scalable experience for the templates, as well as a better UX and DX (Figma prototype). Besides, these prototypes fulfill almost all the tasks in this issue.

oliviertassinari commented 3 months ago

I think both themes can work for both applications (and an e-commerce template in the future) if we polish them.

@zanivan So we would have 3 themes? I think it's the same problem, but a 3rd one feels like a distraction. I think developers should be able to see Material UI and what will be the second theme as part of their options for the templates. If we want to have a landing page mode for the theme, then fair enough, why not. I would try to avoid this as much as possible though. In the past, I solved this problem with one theme and variants.

with a well-organized and structured project

I don't know how we can organize the code, it feels like it depends on each developer's use case. The organization in https://github.com/mui/material-ui/tree/v5.15.19/docs/data/material/getting-started/templates/dashboard feels not helpful to me. The first thing I would do might be to put everything back into one file, and then split based on what I need to build. For example, I would create something for the navigation, so I can share this layout between multiple pages.

If the template/block become really complex, then yes, makes sense to me, like https://github.com/tremorlabs/template-dashboard-oss but at this point, it's has grown to something beyond the purpose of the free templates.

zanivan commented 3 months ago

@zanivan So we would have 3 themes? I think it's the same problem, but a 3rd one feels like a distraction. I think developers should be able to see Material UI and what will be the second theme as part of their options for the templates. If we want to have a landing page mode for the theme, then fair enough, why not. I would try to avoid this as much as possible though. In the past, I solved this problem with one theme and variants.

I don't know if I captured your idea correctly—please feel free to correct me if not—, but I actually think it's easier to build more themes (obviously after building the first one very well) than to add variants to the themes. This is because, with our current setup, to work with the default MD theme, the template itself doesn't have extra styles, tokens, or variants from other themes. It only has different values for the existing variables in the theme and styleOverrides to customize the existing component variants.

In this case, if we did something like <Button variant="marketing"/>, switching to the default MD theme would break the button's styling—because "marketing" wouldn't work. If we added logic inside the template to map variants (e.g., if variant="marketing" in the marketing theme, use variant="contained" in the default MD theme), we'd be adding unnecessary code for users who want to use the template, as they likely wouldn't need this functionality.

So, I think the ideal approach right now is to refine the two existing themes (dashboard and marketing) and merge them into a single theme that meets both needs. Does it make sense?

siriwatknp commented 3 months ago

41947 was a short term solution for dark/light theme switching in the templates' page. However, a long term solution would be to have a script that generates these images automatically, like we have for Joy UI. @siriwatknp can you help me with this?

I can help with this.

oliviertassinari commented 1 month ago

I have just tried to compare the experience between v5 and v6 as a user who needed to quickly start a project and test the performance. I felt point 16.

Merge all the sources of the templates into a single file. Make it much easier to copy and paste into your project (might demand a bit more research but likely to be much better)

The experience of copying the source was better before.

zanivan commented 1 month ago

The experience of copying the source was better before.

Thanks for the feedback! The previous experience, with all the code in the same file, was indeed better for copying and pasting. It’s on my roadmap, along with adding StackBlitz/CodeSandbox support (item 23). With the new appbar, it’s possible to include buttons for both things (copy theme and open in CodeSandbox)

oliviertassinari commented 1 month ago

Oh actually, @romgrk tried this user flow too in: https://github.com/emotion-js/emotion/pull/3242#discussion_r1728797218

I switched to a new dataset that is directly extracted from the MUI dashboard template, which I think is more realistic and reflects production setups even better.

I'm curious about the friction point he got along the way.

zanivan commented 1 month ago

I reached out to @siriwatknp for help, and we’ll be working on this next week, exploring what we can offer to users. IMO we could support both structures and give users the option to either copy the entire code at once or download the project folder with the current theme structure.

oliviertassinari commented 1 month ago

we could support both structures

@zanivan True, this shouldn't too hard to do. We can use the same dependency as used by the live demo editor to resolve the dependencies. We add analytics to see how people use both, and we will learn from it.

romgrk commented 1 month ago

Friction was ok, had to cp -r the folder but it was already checked out it my local material-ui clone. It would have been nice to have a way to copy/paste the dependencies on the CLI but that's because I was including the folder in an existing project rather than using it as a starting point. The x-charts performance was a disappointing part of the template.

DiegoAndai commented 1 month ago

@zanivan let's add a task to refactor the theme to use the new colorSchemes API, which should improve the color mode handling: https://mui.com/material-ui/customization/dark-mode/#built-in-support & https://mui.com/material-ui/customization/dark-mode/#toggling-color-mode

DiegoAndai commented 1 month ago

@zanivan, let's add https://github.com/mui/material-ui/pull/43514#pullrequestreview-2270198956 as well (and other shared components). @siriwatknp also had some ideas on tasks to add to which he wanted to contribute to.

zanivan commented 1 month ago

@DiegoAndai added ✅

@siriwatknp let's pop some time in the calendar next week to organize the ideas 😊

siriwatknp commented 3 weeks ago

I will start working on task 23 (CodeSandbox) and 25 (Refactor the theme to use the new colorSchemes API (based on https://github.com/mui/material-ui/issues/41469#issuecomment-2318989742)) https://github.com/mui/material-ui/pull/43604

Can you explain the task 16? It's not clear to me what exactly are the sources (the whole template files or theme files).

zanivan commented 3 weeks ago

@siriwatknp just documenting the things we've discussed in the meeting to have it here too, feel free to edit it and add stuff :)

Add support for CodeSandbox and StackBlitz

Copy & Paste the code

Templates page and templates frame