[docs] Clearly document the CSS syntax is supported

[oliviertassinari]

Summary

Most of the community prefers the CSS syntax over the JavaScript syntax. At least, that's what I conclude from:

• https://styled-components.com/
• https://syntax.fm/show/751/ui-components-shadcn-tailwind-ui-headless-react-aria-radix-ui 56"35
• https://x.com/_AshConnolly/status/1793754388634509553

So this should be clearly documented, and honesty maybe even be the default. Inside the Material UI source, we have taken the habit of using the JavaScript syntax because it's better typed, so helps with avoiding regressions, but in the docs of Base UI, we went with the CSS syntax e.g. https://mui.com/base-ui/react-button/ for the same reason I'm opening this issue.

Even if you consider this from the perspective that the whole point of Pigment CSS is to bring CSS Modules closer to the components, then asking people to rewrite their style is a big ask, using the CSS syntax makes a lot more sense. Then it's just a matter of making sure Pigment CSS + https://stylelint.io/ works well.

I'm personally more used to the JavaScript syntax, e.g. what I used in https://github.com/oliviertassinari/react-conf-2024-pigment-css/blob/b2aae0b9c03df51960c90ff7b72246d50d372f1f/src/components/Pigment.tsx.

Examples

No response

Motivation

No response

Search keywords: -

[brijeshb42]

There are some differences to using one over the other,

1. If authoring generic components, variants api can't be used with css syntax in styled().
2. We provide a way to use dynamic prop values and use it through css variables. This is available in object syntax but not in tagged template syntax (yet).

Other than these two, both syntax can achieve the desired result. For point 2 above, I know that Linaria provides a way to do what we provide for css variables, but in Pigment, we have replaced that syntax to access theme object -

css`
 color: ${({ theme }) => theme.palette.primary.main}
`