[pigment-css][docs] Docs suggestions

[joshwcomeau]

Related page

https://github.com/mui/material-ui/blob/master/packages/pigment-react/README.md

Kind of issue

Missing information

Issue description

So excited to see Pigment CSS get released 😄. I spent some time today poking around with it and it seems solid.

I realize that this project is brand-friggin-new and that the docs are probably still under construction, but I had a couple of suggestions. I'd be happy to open a PR with my suggested edits if it would be helpful; just let me know!

Show a responsive example

After going through the docs and the code in the Next.js example project, I didn't see any examples of media queries being used. I sorta figured that maybe this wasn't supported yet.

But I did see it mention that selectors could be used, so on a whim, I tried something like this:

const Red = styled('p')({
  color: 'red',
  
  '@media (min-width: 768px)': {
    color: 'blue',
  },
});

I'm not sure if this is the expected way to do this or not, but it worked for me! And so I think there should be an example, so that others know it's supported.

Encourage users to use CSS variables directly

Under the “Styling based on runtime values” heading, it shows how a callback function can be used, and how this compiles to a CSS variable.

This is just my opinion, but I would prefer to encourage users to use CSS variables themselves! This is how I've been handling dynamic styles for years, and I sorta love it.

For example:

const Heading = styled('h1')({
  color: 'var(--color)',
});

function Heading() {
  const [color, setColor] = React.useState('red');
  
  return (
    <Heading style={{ '--color': color }} />
  );
}

There is one big drawback to this approach: CSS variables are inheritable, and so any descendant will also have access to --color. Using the approach recommended in the docs, the value would be something like Heading_class_akjsdfb-0, which all but guarantees that CSS variables won't leak beyond the bounds of their home component.

But I can tell you, after using generic-as-heck CSS variable names for years, this has never been an issue, because I never try to read a value that I'm not also writing; any inherited value would be overwritten.

I think that the callback abstraction is useful in terms of facilitating migration from styled-components/Emotion, and I like that the dynamic parts could be made type-safe with TS, so I think the ideal documentation would start by showing how it can be done directly with CSS variables, and then showing the callback abstraction and mentioning the problems that it solves. That way, developers can choose the tradeoffs based on their own priorities.

Context

No response

Search keywords: Pigment CSS

[siriwatknp]

@joshwcomeau Thanks for the feedback, really appreciate it. Both are great suggestions, I added this to the backlog. cc @samuelsycamore for more opinions.

[douglaszaltron]

One of the things I also had doubts about is how to set defaultProps on components created from styled, as well as the use of the "name" and "slot" attributes. (typescript) 🤔

Ex: Where would the configurations be in defaultProps, in the component, or in the theme?

import { styled } from "@pigment-css/react";

interface FlexProps {
  vertical?: boolean;
}

export const Flex = styled("div", {
  name: "Flex",
  slot: "Root",
})<FlexProps>(() => {
  return {
    display: "flex",
    variants: [
      {
        props: { vertical: true },
        style: {
          flexDirection: "column",
          paddingBlock: "1rem",
        },
      },
      {
        props: { vertical: false },
        style: {
          paddingInline: "1rem",
        },
      },
    ],
  };
});

@danilo-leal @siriwatknp

[siriwatknp]

One of the things I also had doubts about is how to set defaultProps on components created from styled, as well as the use of the "name" and "slot" attributes. (typescript) 🤔

To define defaultProps, use the theme. It's very similar to https://mui.com/material-ui/customization/creating-themed-components/ with the change of import from @mui/material/styles to @pigment-css/react.

Note: the API is meant for building a themable UI library, not local components.