[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.