[docs] Create docs to recommend when to use each API

[oliviertassinari]

Steps to reproduce

We have 3 main APIs in Pigment CSS: https://react-conf-2024-pigment-css.netlify.app/?slideIndex=31&stepIndex=0

I would much rather not make the same mistake as in https://youtu.be/UlY-Ixddjm0?si=WTs9IU9K47mOfUzE&t=1538. Meaning, we should document clearly when to use each prop so developers get consistency.

---

styled API:

Pros:

• https://github.com/mui/pigment-css/issues/86#issuecomment-2132689102 can respond do props more easily.

Cons:

• https://github.com/vercel/next.js/issues/35030 hides the host element to eslint rules.
• Need to come up with names

Current behavior

No response

Expected behavior

No response

Context

No response

Your environment

npx @mui/envinfo

``` Don't forget to mention which browser you used. Output from `npx @mui/envinfo` goes here. ```

Search keywords: -

[damusnet]

@oliviertassinari does/will Pigment CSS ever support the css prop like Emotion? For instance:

<div css={{ backgroundColor: "red" }} />

or is the solution here to use the css method? For instance:

<div className={css({ backgroundColor: "red" })} />

[oliviertassinari]

@damusnet I doubt it. The sx prop seems to serve the same purpose.

<div sx={{ backgroundColor: "red" }} />

But maybe we would want this, with a deprecation, helping people to migrate from Emotion.

[damusnet]

Gotcha, thanks for the quick reply.

I was under the impression that sx was a little different, with support for things like px and py (that's fine), but maybe also stricter requirements (thought I read that border has to be a number, and can't be 1px solid red for instance). If it's a perfect superset, then that's great.

[oliviertassinari]

@damusnet The sx prop is meant to be a superset of the css prop. I would expect border: 1px solid red to work.