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

[zanivan]

Summary

After wrapping up the first round of design refresh that this #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

• 1. Remove links and interdependencies on different templates [material-ui][docs] Remove links and interdependencies from free templates #41941
• 2. Also make the thumbnails follow the docs appearance mode, like those in the Joy UI page [material-ui][docs] Add dark theme thumbnails for templates #41947
• 3. Turn heavy customized components into a styled component. [material-ui][docs] Simplify components styling on templates #41845
• 4. Ensure accessible labels for the inputs [material-ui][docs] Add stray design tweaks to free templates #41696
• 5. Standardize the focus style across all interactive elements [material-ui][docs] Add stray design tweaks to free templates #41696
• 6. Review and refine the colors and tokens of the custom theme [material-ui][docs] Add stray design tweaks to free templates #41696
• 7. Turn the logos into SVG [material-ui][docs] Add stray design tweaks to free templates #41696
• 8. Make the templates respect the user's system appearance mode (light or dark) by default [material-ui] Refine and unify custom template themes #43220
• 9. Persist the light/dark mode between loads [material-ui] Refine and unify custom template themes #43220
• 10. Add a theme selector on the Templates page, so visitors can pick how to see the live preview. [material-ui][docs] Refine templates theme selector #43396
  For example https://ui.shadcn.com/blocks
  
• 11. Group templates with custom themes and the ones without one yet [material-ui] Refine and unify custom template themes #43220
• 12. Rename the “landing page” template given it looks more like a home page [docs] Refine and polish out Templates page #43131
• 13. Refine paper component and its usage (remove background-image and use background-color) [material-ui] Refine and unify custom template themes #43220
• 14. Allow to click on the image to open it. Uploading Screen Recording 2024-06-10 at 18.14.18.mov… [docs] Refine and polish out Templates page #43131

Screen.Recording.2024-06-10.at.18.14.18.mov

• 15. Have all the custom theme demos share the exact same theme JavaScript structure [material-ui] Refine and unify custom template themes #43220
• Fix [material-ui] Dashboard template improvements #42610
• 22. Fix the theme toggle that overlaps the content on the page, e.g. https://deploy-preview-42605--material-ui.netlify.app/material-ui/getting-started/templates/sign-in/.
• 17. Have a CRUD dashboard with a side navigation: https://deploy-preview-42001--material-ui.netlify.app/material-ui/getting-started/templates/dashboard/ feels much more useful to @oliviertassinari than https://deploy-preview-42101--material-ui.netlify.app/material-ui/getting-started/templates/dashboard/. I think we should still have it as the first one. See the Google Analytics events, and then swap the order/retire it once it gets dethroned 🥇 by another one in use metrics.

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

• 18. Run https://pagespeed.web.dev/ on all the templates. Make sure there are no true positive warnings are reported.
• 19. Run w3c validator with all the templates, have no true positive warnings https://validator.w3.org/nu/?doc=https%3A%2F%2Fdeploy-preview-41845--material-ui.netlify.app%2Fmaterial-ui%2Fgetting-started%2Ftemplates%2Fsign-in%2F reported.
• 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)
• 20. Have https://chromewebstore.google.com/detail/lhdoppojpmngadmnindnejefpokejbdd report no errors
• 21. Have no console warning or errors

• 23. Support export to StackBlitz/CodeSandbox like https://mui.com/joy-ui/getting-started/templates/ do

More context on why it could be valuable: #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.

• 24. Add tokens for the 25 shadow levels so it won't spread strings into arrays, and result in many 1-character strings in the target array (reported on [docs][material-ui] Fixed incorrectly spread shadows in templates #43369, decision made on [docs][material-ui] Fixed incorrectly spread shadows in templates #43369 (comment))

• 25. Refactor the theme to use the new colorSchemes API (based on [material-ui][docs] Refine the free templates page #41469 (comment))

• 26. Share the TemplateFrame files through all templates

• Fix [material-ui] Sign-in template improvements #42609

Search keywords

template

[zanivan]

#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]

@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 #41757 (comment):

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

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)

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]

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)

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]

16. 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 #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.

16. 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]

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]

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]

@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]

#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]

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]

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]

Oh actually, @romgrk tried this user flow too in: emotion-js/emotion#3242 (comment)

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]

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]

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]

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]

@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]

@zanivan, let's add #43514 (review) as well (and other shared components). @siriwatknp also had some ideas on tasks to add to which he wanted to contribute to.

[zanivan]

@DiegoAndai added ✅

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

[siriwatknp]

I will start working on task 23 (CodeSandbox) and 25 (Refactor the theme to use the new colorSchemes API (based on #41469 (comment))) #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]

@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

• First step will be to use SignIn template as a POC [material-ui][docs] Open Material UI template with CodeSandbox/StackBlitz #43604 and as soon as we're happy with the result, we add it to other templates.
• We will tell users to use the download button from CodeSandbox/StackBlitz to get the project files instead of creating our own solution for it—it doesn't seem to payoff.
• Have only one theme folder that will be used and shared through all templates, that will be bundled on CodeSandbox/StackBlitz so users can download it as well.

Copy & Paste the code

• Besides the theme folders within projects, we'll have a new single file for the theme where we have the themePrimitives and components' customizations.
• This file will be updated with the changes made on the shared-theme, by the script pnpm template:update-theme.

Templates page and templates frame

• After we're happy with theme structure and other features such as CodeSandbox/StackBlitz and Copy&Paste, we'll work on the UI's to make these available.
• Build a tutorial and a how-to-guide to use the templates and/or use the theme.