[RFC] Renaming Joy APIs

This RFC list several points related to renaming Joy UI APIs so that we can discussed before making the changes.

1. ~Rename color prop to palette~ Decided to go with textColor prop instead, details here:

   • The color prop creates confusion around the palette & CSS color property as indicated in

     • https://github.com/mui/material-ui/issues/29564.
     • https://github.com/mui/material-ui/issues/29564#issuecomment-1088626841.
     • https://github.com/mui/material-ui/issues/32270#issuecomment-1098173875
     • https://github.com/mui/material-ui/issues/32274

   • ~The Link component needs to support both palette and color props (using color prop alone would make the logic very complicated and code suggestion would not work because the color type is a string)~

   • ~In Joy, most components have variant prop which most of the time needs palette to work, so the palette prop sounds like the best option.~

   • Add textColor prop to the components that support shorthand props eg. Link

   <Link color="primary" textColor="#000">
   

2. ✅ Rename variant values: The reason to rename the values is to set apart from these existing names (CSS properties, color modes) and make them meaningful as much as possible. https://github.com/mui/material-ui/pull/32489

   • text to plain (as discussed in https://github.com/mui/material-ui/pull/31090#issuecomment-1046610235)
   • outlined to frame | shell | pod | crust. (we haven’t discussed about this yet but using outlined is too close to the CSS outline property)
   • light to soft (as discussed in https://github.com/mui/material-ui/pull/31090#issuecomment-1046610235)
   • contained to solid (as discussed in https://github.com/mui/material-ui/pull/31090#issuecomment-1046610235)

   These are other names that we can consider.

   • bordered (but it is too close to CSS property border)
   • ghost (similar to Chakra UI)
   • filled, subtle (from Mantine)

3. ~Rename primary palette to brand: continue from https://github.com/mui/material-ui/pull/31090#issuecomment-1047435912 to gather more thoughts. ~

   • @siriwatknp https://github.com/mui/material-ui/pull/31090#issuecomment-1047435912
   • @mnajdova https://github.com/mui/material-ui/pull/31090#issuecomment-1047830978
   • @danilo-leal https://github.com/mui/material-ui/pull/31090#issuecomment-1047726842

4. Add/Remove typography scale: After doing POC with several apps, it becomes clear that the current h1 and h2 are too big and I have never used h5, h6 (as an HTML tag). I have to always do this <Typography level="h2" fontSize="lg" />. It makes more sense to have display1, 2 for the headline like in MUI branding.

   • ✅ add display1 and display2
   • ~remove h5 and h6~

   From tailwind CSS https://play.tailwindcss.com/uj1vGACRJA?layout=preview We haven’t used an h4 yet But now we have. Please don’t use h5 or h6 in your content, Medium only supports two heading levels for a reason, you animals. I honestly considered using a before pseudo-element to scream at you if you use an h5 or h6.

We don’t style them at all out of the box because h4 elements are already so small that they are the same size as the body copy. What are we supposed to do with an h5, make it smaller than the body copy? No thanks.

1. ~Rename level prop on the typography component to scale for consistency with the system: level was initially added in Joy to replace the variant (because Joy’s variant is different). Some discussion is in https://www.notion.so/mui-org/MUI-System-890bb3d81cbf45008fd5d2f90f53539d#5de65bde31ec4a84931cd62081d27e04~

If you think other APIs need to be renamed, feel free to add it to the list. Not every bullets have to be decided in this RFC, we can start working on the first batch and revisit the rest later.

[mnajdova]

1. Rename color prop to palette

I am not sure only on this one. I think the problem is not with the color prop itself, but how we use the same term for different things. In my opinion, we should keep the API close to how you would describe the UI if you see it. For example if I see a button with blue background I would say that the button has a blue color, not that it uses the blue palette. The problem is with the CSS properties that we use on some of the components as props. If I go one step further, I would say that the css prop color is a bad chosen name (I am being wild here 😄), it should be something like textColor, similar to backgroundColor. My proposal would be renaming the CSS prop we use on the components from color to textColor. This way people won’t confus this with the color prop that exists on other components (or on the same component as in the case of the Link component).

[danilo-leal]

I’d say that using outlined, in the past tense, is enough to avoid confusion with CSS’s outline. It’s widely used and following convention here seems like a safe thing to do.