[docs][pigment-css] Add guide for Pigment CSS quickstart #43395

alelthomas · 2024-08-21T17:18:54Z

Added to material-ui/guides for now, but let me know where it should live in the meantime

Preview: https://deploy-preview-43395--material-ui.netlify.app/material-ui/experimental-api/pigment-css/

mui-bot · 2024-08-21T17:21:17Z

Netlify deploy preview

docs/data/material/experimental-api/pigment-css/pigment-css.md

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 0c3c3d7

Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

samuelsycamore · 2024-08-21T17:51:54Z

I'm curious to hear @mnajdova 's thoughts on where this doc should live!

DiegoAndai

Thanks for working on this @alelthomas!

About the failing test_static test, running pnpm prettier will fix it, but I recommend you set up auto-format on save on your editor so you don't have to do it manually 😊. Let me know if you need help with that.

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.

Besides that, a couple of comments:

docs/data/material/guides/pigment-css/pigment-css.md

stunaz · 2024-08-22T12:17:36Z

It would be great to add a working sandbox

samuelsycamore · 2024-08-22T15:12:54Z

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.

DiegoAndai · 2024-08-22T15:22:49Z

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.

samuelsycamore

Great piece @alelthomas! This review is mostly about copyediting.

One thing I'd really like to see in the next draft is more specific details about why/when to use each of the utilities. You started to do this with the theming section—themes are for applying consistent values across an entire app. It would be really helpful to add a similar description for the other APIs as well, so users know which one to pick for any given use case (e.g., "the sx prop is best for one-off styles when you need to customize a single instance of a component.")

docs/data/material/guides/pigment-css/pigment-css.md

Co-authored-by: Diego Andai <diego@mui.com> Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

Co-authored-by: Sycamore <71297412+samuelsycamore@users.noreply.github.com> Co-authored-by: Diego Andai <diego@mui.com> Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

Co-authored-by: Sycamore <71297412+samuelsycamore@users.noreply.github.com> Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

alelthomas · 2024-08-29T03:04:04Z

Made a bunch of small changes based on feedback - let me know what you think @samuelsycamore @DiegoAndai

DiegoAndai

LGTM 😊
Thanks @alelthomas

samuelsycamore

This is looking really good! Just some small copyediting suggestions on the newer bits here, otherwise I'd say it's about ready to publish.

docs/data/material/experimental-api/pigment-css/pigment-css.md

siriwatknp · 2024-09-04T03:11:28Z

Here is my suggestion for the Next.js and Vite instructions, you can make them as tabs, see alelthomas#1.

It's similar to package manager installation. If you pick Vite, all of the tabs will switch to Vite.

Screen.Recording.2567-09-04.at.10.10.44.mov

Co-authored-by: Sycamore <71297412+samuelsycamore@users.noreply.github.com> Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

oliviertassinari · 2024-09-14T14:10:34Z

docs/data/material/experimental-api/pigment-css/pigment-css.md

+```js
+  extendTheme({
+    colorSchemes: {


Wrong pragma and wrong indentation, should be:

Suggested change

```js

extendTheme({

colorSchemes: {

```diff

extendTheme({

colorSchemes: {

oliviertassinari · 2024-09-14T14:11:39Z

docs/data/material/experimental-api/pigment-css/pigment-css.md

+
+If you use the `sx` prop on an HTML element, you'll need to augment the `HTMLAttributes` interface:
+
+```js


Should get the correct color highlighting:

Suggested change

```js

```ts

oliviertassinari · 2024-09-18T16:33:15Z

Fixed those small issues in #43812.

Now, I don't understand this docs (I didn't look at the content before). Why 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 also don't understand https://mui.com/material-ui/migration/migrating-to-pigment-css/. This is not about Material UI v5 to Material UI v6. 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

[docs] Add guide for Pigment CSS quickstart

b7157fd

alelthomas requested review from DiegoAndai, siriwatknp and samuelsycamore August 21, 2024 17:18

add snippet for global styles

2733723

alelthomas changed the title ~~[docs] Add guide for Pigment CSS quickstart~~ [docs][pigment-css] Add guide for Pigment CSS quickstart Aug 21, 2024

non-breaking spaces pigment-css.md

b091ee9

Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

samuelsycamore added docs Improvements or additions to the documentation package: pigment-css Specific to @pigment-css/* labels Aug 21, 2024

DiegoAndai reviewed Aug 21, 2024

View reviewed changes

docs/data/material/guides/pigment-css/pigment-css.md Outdated Show resolved Hide resolved

docs/data/material/guides/pigment-css/pigment-css.md Outdated Show resolved Hide resolved

samuelsycamore reviewed Aug 22, 2024

View reviewed changes

alelthomas and others added 11 commits August 22, 2024 12:33

fix code snippet typo

d5b9169

Co-authored-by: Diego Andai <diego@mui.com> Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

apply copy edit changes

858ce82

Co-authored-by: Sycamore <71297412+samuelsycamore@users.noreply.github.com> Co-authored-by: Diego Andai <diego@mui.com> Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

change description

c2337c8

Co-authored-by: Sycamore <71297412+samuelsycamore@users.noreply.github.com> Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

change description to be more generic

b7de169

Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

Merge branch 'mui:master' into pigment-css-quickstart

cdc89b8

fix indentation

8e7ed78

add prerequisites

24e4b21

move to Experimental APIs

9cc0c9a

add more context to each section

5330f6d

non-breaking space

30ebd1d

sx prop definition

8c3f0e2

alelthomas requested review from DiegoAndai and samuelsycamore August 29, 2024 03:03

DiegoAndai approved these changes Aug 30, 2024

View reviewed changes

samuelsycamore reviewed Sep 4, 2024

View reviewed changes

alelthomas and others added 7 commits September 4, 2024 16:04

Merge branch 'mui:master' into pigment-css-quickstart

31feabe

copy edits

35ce82d

Co-authored-by: Sycamore <71297412+samuelsycamore@users.noreply.github.com> Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

add framework tabs

86817c8

Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

remove next.js distinction

74260a2

Signed-off-by: Ale <93217218+alelthomas@users.noreply.github.com>

Merge branch 'mui:master' into pigment-css-quickstart

15ae51e

remove trailing space

1084219

final commit

0c3c3d7

alelthomas merged commit 1ad4c8d into mui:master Sep 10, 2024
22 checks passed

alelthomas deleted the pigment-css-quickstart branch September 10, 2024 16:11

oliviertassinari reviewed Sep 14, 2024

View reviewed changes

This was referenced Sep 14, 2024

[docs][pigment-css] Fix typo globalCSS -> globalCss #43754

Merged

[docs] Format Pigment CSS docs #43812

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs][pigment-css] Add guide for Pigment CSS quickstart #43395

[docs][pigment-css] Add guide for Pigment CSS quickstart #43395

alelthomas commented Aug 21, 2024 •

edited by oliviertassinari

Loading

mui-bot commented Aug 21, 2024 •

edited

Loading

samuelsycamore commented Aug 21, 2024

DiegoAndai left a comment

stunaz commented Aug 22, 2024

samuelsycamore commented Aug 22, 2024

DiegoAndai commented Aug 22, 2024 •

edited

Loading

samuelsycamore left a comment

alelthomas commented Aug 29, 2024

DiegoAndai left a comment

samuelsycamore left a comment •

edited

Loading

siriwatknp commented Sep 4, 2024

oliviertassinari Sep 14, 2024

oliviertassinari Sep 14, 2024 •

edited

Loading

oliviertassinari commented Sep 18, 2024 •

edited

Loading


		If you use the `sx` prop on an HTML element, you'll need to augment the `HTMLAttributes` interface:

		```js

[docs][pigment-css] Add guide for Pigment CSS quickstart #43395

[docs][pigment-css] Add guide for Pigment CSS quickstart #43395

Conversation

alelthomas commented Aug 21, 2024 • edited by oliviertassinari Loading

mui-bot commented Aug 21, 2024 • edited Loading

Netlify deploy preview

Bundle size report

samuelsycamore commented Aug 21, 2024

DiegoAndai left a comment

Choose a reason for hiding this comment

stunaz commented Aug 22, 2024

samuelsycamore commented Aug 22, 2024

DiegoAndai commented Aug 22, 2024 • edited Loading

samuelsycamore left a comment

Choose a reason for hiding this comment

alelthomas commented Aug 29, 2024

DiegoAndai left a comment

Choose a reason for hiding this comment

samuelsycamore left a comment • edited Loading

Choose a reason for hiding this comment

siriwatknp commented Sep 4, 2024

oliviertassinari Sep 14, 2024

Choose a reason for hiding this comment

oliviertassinari Sep 14, 2024 • edited Loading

Choose a reason for hiding this comment

oliviertassinari commented Sep 18, 2024 • edited Loading

alelthomas commented Aug 21, 2024 •

edited by oliviertassinari

Loading

mui-bot commented Aug 21, 2024 •

edited

Loading

DiegoAndai commented Aug 22, 2024 •

edited

Loading

samuelsycamore left a comment •

edited

Loading

oliviertassinari Sep 14, 2024 •

edited

Loading

oliviertassinari commented Sep 18, 2024 •

edited

Loading