[joy-ui] Change background color name scale

zanivan commented 1 year ago

Duplicates

[X] I have searched the existing issues

Latest version

[X] I have tested the latest version

Summary 💡

After a Discord discussion, I wondered if the background scale naming that we currently have on Joy UI is the best one.

Today, the scale works linearly from light to dark, when in dark mode, and from dark to light when in dark mode. We have 7 surface levels, where the body is the first level, and level3 being the last. Body, as the name says, is meant for the <body>, like the base background. In turn, the surface level is used by the components, like the first layer above the <body>, and level1 to 3 subsequently.

The biggest problem is that some names have a semantic approach (body, surface, tooltip, popup) and some have non-semantical names (level 1, level 2 and level 3). This ends up providing a bad DX since it's non-intuitive to know that this is meant to be a linear scale.

Examples 🌈

For instance, these are the scales we currently have for light background:

background: {
        body: getCssVarColor('palette-common-black'),
        surface: getCssVarColor('palette-neutral-900'),
        popup: getCssVarColor('palette-common-black'),
        level1: getCssVarColor('palette-neutral-800'),
        level2: getCssVarColor('palette-neutral-700'),
        level3: getCssVarColor('palette-neutral-600'),
        tooltip: getCssVarColor('palette-neutral-600'),
}

Proposal

As I see, a better experience for this would be:

background: {
        level-0: getCssVarColor('palette-common-black'), //to be used for body
        level-1: getCssVarColor('palette-neutral-900'), //to be used on components
        level-2: getCssVarColor('palette-neutral-800'),
        level-3: getCssVarColor('palette-neutral-700'),
        level-4: getCssVarColor('palette-neutral-600'),
}

mwskwong commented 1 year ago

For the record, I'm the other guy involved in the Discord discussion.

If the background colors are meant to be a scale, instead of enforcing what bg color should each type of component use, then I believe the proposed changes are better at reflecting that.

But this raises a question, if a section of a page, e.g., drawer, is using level-1 as the background, should elements in it, e.g., chips, keep using level-1 as the background (current behavior), or should they be auto bumped to level-2?

zanivan commented 1 year ago

But this raises a question, if a section of a page, e.g., drawer, is using level-1 as the background, should elements in it, e.g., chips, keep using level-1 as the background (current behavior), or should they be auto bumped to level-2?

IMHO by default, they should keep their level for the consistency sake, at least for the Joy UI default theme—otherwise, we can end up with a lot of visuals for the same components. However, if this 'background auto-adjust' is something that would really improve the DX, I believe it could work like a feature, similar to what we have with color inversion.

In the meantime, I believe changing the name already helps users to better understand and tweak the levels as they need.

siriwatknp commented 1 year ago

But this raises a question, if a section of a page, e.g., drawer, is using level-1 as the background, should elements in it, e.g., chips, keep using level-1 as the background (current behavior), or should they be auto bumped to level-2?

IMHO by default, they should keep their level for the consistency sake, at least for the Joy UI default theme—otherwise, we can end up with a lot of visuals for the same components. However, if this 'background auto-adjust' is something that would really improve the DX, I believe it could work like a feature, similar to what we have with color inversion.

In the meantime, I believe changing the name already helps users to better understand and tweak the levels as they need.

Totally agree with @zanivan. For context, the body and surface are meant to create confidence for customization. For example, as a Joy UI new user, if I want to change the background of the app I can update the background.body without worrying that the rest of the app will change.

But maybe it's better to go with just scale. What's important is the docs that we should cleary communicate how the scale works.

mui / material-ui