mui
[docs][pigment-css] Add guide for Pigment CSS quickstart
Added to material-ui/guides for now, but let me know where it should live in the meantime
- [x] I have followed (at least) the PR section of the contributing guide.
Netlify deploy preview
Bundle size report
No bundle size changes (Toolpad) No bundle size changes
Generated by :no_entry_sign: dangerJS against 0c3c3d78219eaeb51ea6824d43ebb16a2fa55a46
I'm curious to hear @mnajdova 's thoughts on where this doc should live!
About the placing of the guide, How-to guides is what makes the most sense to me, but if the team prefers to move it to Experimental APIs I'm not against that.
As I think about it more, Experimental APIs makes the most sense to me. Pigment CSS is still in the "experimental" stage of development after all, at least to some degree. Eventually it should have its own standalone docs space and this doc would be part of the Getting Started sequence. I think putting it in the Experimental APIs section helps to signal that the content is subject to change and could be relocated at a later date. If we want to publish multiple Pigment docs in the Material UI space, we could add a Pigment CSS subheader in the Experimental APIs section as we've done for CSS Theme Variables.
My biggest worry re: publishing Pigment docs in the Material UI space is that this will signal that Pigment is "merely" a Material UI utility, rather than a standalone product in its own right. I suppose this is part of a larger, ongoing conversation about the GTM strategy for Pigment CSS, which seems unclear to me at this stage. But I digress. In any case, when it's time to launch Pigment CSS v1, I would expect it to have its own dedicated docs space, and so I think we should organize "interim" docs like this one with that in mind.
As I think about it more, Experimental APIs makes the most sense to me
That's good for me. Let's move it to Experimental APIs šš¼ @alelthomas
My biggest worry re: publishing Pigment docs in the Material UI space is that this will signal that Pigment is "merely" a Material UI utility, rather than a standalone product in its own right.
We won't publish Pigment docs in the Material UI space. This is a user-friendly guide for Material UI users who want to check out Pigment CSS, as without it we might get little feedback for v1 (the migration guide is more focused on migration but not using Pigment). When Pigment has its docs and guides, we can point them there and/or move this guide.
Made a bunch of small changes based on feedback - let me know what you think @samuelsycamore @DiegoAndai
Here is my suggestion for the Next.js and Vite instructions, you can make them as tabs, see https://github.com/alelthomas/material-ui/pull/1.
It's similar to package manager installation. If you pick Vite, all of the tabs will switch to Vite.
https://github.com/user-attachments/assets/2e50443f-ed5a-41c7-ab51-2d10a8679c97
Fixed those small issues in #43812.
Now, I find the docs misleading. We have the Pigment CSS docs (not the Material UI integration of Pigment CSS) in the documentation of MaterialĀ UI: https://mui.com/material-ui/experimental-api/pigment-css/. Please no.
@alelthomas How about we?
- Move all content that is about Pigment CSS to https://github.com/mui/pigment-css/blob/master/README.md (most of the page it seems today).
- Remove all content that is about Pigment CSS only from https://mui.com/material-ui/experimental-api/pigment-css/. I think it's critical that we clearly separate the concerns. An example of what success looks like: Shadcn UI migrating to PigmentĀ CSS.
- Use https://mui.com/material-ui/experimental-api/pigment-css/ to host docs that is Material UI specific on how to use Pigment CSS. I would dream of a world where this page is useless, as Shadcn UI has nothing about how to use TailwindĀ CSS, it's naturally extended it. But still, I gues we will need content there, we are not there yet.
Actually, I'm also confused by https://mui.com/material-ui/migration/migrating-to-pigment-css/. It is located in a place that makes it seem like it's about MaterialĀ UI v5 to Material UI v6. But it's about Emotion to Pigment CSS. How about we move this content? To:
- In https://mui.com/material-ui/experimental-api/pigment-css/ if the production direction is to have: Material UI = Base UI + Pigment CSS, nothing in between, or to have Base UI + Pigment CSS System, nothing in between. Pigment CSS has an emotion runtime engine + a static extraction engine.
- In https://mui.com/system/getting-started/ if the production direction is to have Material UI = Base UI + MUI System (wrapping Emotion and Pigment CSS).
cc @aarongarciah
I have updated https://github.com/mui/pigment-css/issues/73 to reflect the direction suggested in https://github.com/mui/material-ui/pull/43395#issuecomment-2358928850.