[RFC] Renaming Joy APIs
See original GitHub issueThis RFC list several points related to renaming Joy UI APIs so that we can discussed before making the changes.
-
~Rename
color
prop topalette
~ Decided to go withtextColor
prop instead, details here:-
The
color
prop creates confusion around the palette & CSS color property as indicated in -
~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 needspalette
to work, so thepalette
prop sounds like the best option.~ -
Add
textColor
prop to the components that support shorthand props eg. Link
<Link color="primary" textColor="#000">
-
-
✅ 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
toplain
(as discussed in https://github.com/mui/material-ui/pull/31090#issuecomment-1046610235)outlined
toframe
|shell
|pod
|crust
. (we haven’t discussed about this yet but usingoutlined
is too close to the CSS outline property)light
tosoft
(as discussed in https://github.com/mui/material-ui/pull/31090#issuecomment-1046610235)contained
tosolid
(as discussed in https://github.com/mui/material-ui/pull/31090#issuecomment-1046610235)
These are other names that we can consider.
-
~Rename
primary
palette tobrand
: continue from https://github.com/mui/material-ui/pull/31090#issuecomment-1047435912 to gather more thoughts. ~ -
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 havedisplay1, 2
for the headline like in MUI branding.- ✅ add
display1
anddisplay2
- ~remove
h5
andh6
~
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.
- ✅ add
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.
- ~Rename
level
prop on the typography component toscale
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.
Issue Analytics
- State:
- Created a year ago
- Reactions:2
- Comments:8 (8 by maintainers)
Top GitHub Comments
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 propcolor
is a bad chosen name (I am being wild here 😄), it should be something liketextColor
, similar tobackgroundColor
. My proposal would be renaming the CSS prop we use on the components fromcolor
totextColor
. This way people won’t confus this with thecolor
prop that exists on other components (or on the same component as in the case of theLink
component).I’d say that using
outlined
, in the past tense, is enough to avoid confusion with CSS’soutline
. It’s widely used and following convention here seems like a safe thing to do.