[RFC] Joy color system

[siriwatknp]

To share my findings of different alternatives for applying colors to Joy components so that I get early feedback and the understanding is shared across the team.

The final approach should have these characteristics:

1. simple but also configurable between light and dark mode.

This is because colors tend to be different between light & dark on the components, take Button as an example.

Light	Dark
border-color: #BBBBBB; color: #3536BD;	border-color: #3E3E3E; color: #DDD1FA;

2. The styles inside the component should point to a variable instead of switching between colors.

This is a constraint we need to account for, otherwise, we will need to rely on JS and still have a flash issue on the SSR.

// an example of component implementation
const Button = styled('button')(({ theme }) => ({
  color: theme.vars.palette.brand.text,
}))

// the style sheet created should look like this
:root {
  --palette-brand-text: #3536BD;
}
[data-theme="dark"] {
  --palette-brand-text: #DDD1FA;
}

When the dark color scheme is picked, the Button color will use [data-theme="dark"] palette.

3. Scalable across the whole components

Component states (hover, active, focus, disabled) can reuse the same variables. Or some variants like outlined should be able to share the colors between each component.

Alternatives

Current candidate: Option 1

Option 1: Use only the color range (50-900)

Because the styles (color) is different between light and dark mode. We cannot use the range (50-900) directly, we need to create references in the theme and point to the range.

{
  colorSchemes: {
    light: {
      palette: {
        brand: {
          50: '...',
          // 100 - 900
          btnTextColor: 'var(--joy-palette-brand-200)',
          btnTextHoverBg: 'var(--joy-palette-neutral-800)',
          btnTextActiveBg: 'var(--joy-palette-neutral-700)',
          // ...
        }
      }
    },
    dark: {
      palette: {
        brand: {
          50: '...',
          // 100 - 900
          btnTextColor: 'var(--joy-palette-brand-600)',
          btnTextHoverBg: 'var(--joy-palette-neutral-100)',
          btnTextActiveBg: 'var(--joy-palette-neutral-200)',
          // ...
        }
      }
    }
  }
}

And then the Button can use the variable like this:

const Button = styled('button')(({ theme }) => ({
  color: colorPalette.btnTextColor,
  '&:hover': {
    backgroundColor: colorPalette.btnTextHoverBg,
  },
  '&:active': {
    backgroundColor: colorPalette.btnTextActiveBg,
  },
  [`&.${buttonClasses.disabled}`]: {
    color: colorPalette.btnTextDisabledColor,
  },
}))

Pros

• Most flexible way because each CSS property + variant + state + mode can be assigned a specific color available in the theme.
• It is easy to debug the color in the dev tool because it uses color tokens.

Cons

• The example above shows that the CSS property of a Button (border) is bound directly with the variable which means we will have a lot of variables and naming them can be tough.

Option 2: Use opacity

Use opacity instead of using different hue when the component state changes. Meaning, the base color is the same but with different opacity. Example:

const Button = styled('button')(({ theme }) => ({
  color: theme.vars.palette.brand.text,
  '&:hover': {
    // theme.vars.palette.brand.channelBg = '19 19 19'
    backgroundColor: `rgba(${theme.vars.palette.brand.btnChannelTextBg} / 0.2)`, // result is `rgba(19 19 19 / 0.2)`
  },
  '&:active': {
    backgroundColor: `rgba(${theme.vars.palette.brand.btnChannelTextBg} / 0.3)`,
  },
}))

The example above can reduce some variables compared to the first approach. The default theme can look like this:

{
  colorSchemes: {
    light: {
      palette: {
        brand: {
          btnChannelTextColor: '53 54 189',
          btnChannelTextBg: '106 106 106',
          btnChannelTextOutline: '221 209 250',
        }
      }
    },
    dark: {
      palette: {
        brand: {
          btnChannelTextColor: '53 54 189',
          btnChannelTextBg: '31 31 31',
          btnChannelTextOutline: '221 209 250',
        }
      }
    }
  }
}

Opacity scale can be used to have consistency between components.

{
  colorSchemes: {
    light: {
      palette: {
        brand: {
          // ... same as above
        }
      },
      opacity: {
        hover: 0.12,
        active: 0.24,
        disabled: 0.5,
      }
    },
    dark: {
      palette: {
        brand: {
          // ... same as above
        }
      },
      opacity: {
        hover: 0.2,
        active: 0.32,
        disabled: 0.6,
      }
    }
  }
}

This approach can be applied in other components as well.

Cons

• Using opacity might not get the exact color as in design.

Light	Dark

border-color: rgba(var(--palette-brand-border) / 0.6); // using opacity cannot adjust the hue
color: var(--palette-brand-text);

• The variables are not readable in the devtool. The variable has to be in the channel form of '$r $g $b' such as 221 209 250. As of now, this is unavoidable due to the limitation of CSS.
• It does not work to use the same opacity scale with different variants. See the POC (the contained variant in "Channel + Opacity" section)

[danilo-leal]

I understand the cons about the first option but, in general, relying on opacity kinda limits a lot of possible designs we could use in the components - at least it was what struck me while reading it.

...we need to create references in the theme and point to the range.

This is put as a con but it seems to be pretty similar to what we saw Primer - GitHub's DS - does. So, it kinda makes me think, how much component-specific color definition do we want to have on the theme object? And why? What also evokes a better DX?

I know there's a trade-off about the theme's length. If every component state color is defined there, the theme might get big (see Primer's). But what are other trade-offs to consider? The main con about the second option I see is not that it "might not get the exact same color as in the design" but rather that it limits the design expression of the component, which to me is a big con!

Also, the <Button color="success" /> got me thinking. Do we need to expose a color prop for the button? Why do we need to optimize for this? Again using Primer as a major reference, they don't expose it and have types of buttons depending on semantic use, so ButtonPrimary and ButtonDanger, for example. To think about (maybe off-topic though, we probably should continue the button specific discussion on its PR 😬 )

[danilo-leal]

Also, I must say that, in a broader sense, backgroundColor: theme.vars.palette.button.bgHover, seems way simpler and easier to understand than rgba(${theme.vars.palette.brand.channelBg} / ${theme.vars.opacity.hover}). 👀 At least for me as a designer!

[siriwatknp]

how much component-specific color definition do we want to have on the theme object? And why? What also evokes a better DX?

As far as I can tell, this is driven by the community to have the component with the color prop support all palettes that have the color range (50-900).

Also from my experience using material-ui in a production dashboard website, there are needs for <Button color="success | danger" />. As a developer, it is quite strange if the component does not work by changing color that has the same color range (50-900).

Another point is that I would be a bit careful to use Primer as a reference as a design system because it is built for Github. They can force some rules to keep the consistency. I don't see many use cases that rely on Primer react components, so it is hard to say if their approach works. Only 1.5k dependents on primer react library whereas material-ui has 730k dependents

relying on opacity kinda limits a lot of possible designs we could use

Agree, but I think it is a trade-off that we have to choose.

I will do the full POC on the button to see how many variables we need to achieve the design compared with using opacity and share the findings again.

[siriwatknp]

@danilo-leal I have done the POC in more detail and I feel like option 1 is better than using opacity because

• Color and be hand-picking and adjust without affecting other property.
• Debugging is much better because you can see what color it is using.

Note: using opacity does not work well in some cases like Button variant contained. Also, both ways are able to achieve other color props like <Button color="success" />.

[mbrookes]

Use only the color range (50-900)

Slightly off topic, but is 50-900 a broadly accepted scale, or specific to Material Design 1 & 2? In MD 3 they've moved to a 0-100 scale:

[siriwatknp]

Thanks for the input! I'm also aware of the MD3 color scale. What I think for Joy color scale is that it should have the scale that people are familiar with. Currently, 50-900 seems to be the most common one.

• material design 2
• https://accessiblepalette.com/
• https://tailwindcss.com/docs/customizing-colors

[mbrookes]

Use opacity instead of using different hue

I presume that's meant to say "tone" (or "shade" using MD 1-2 terminology).

Opacity is an important tool where you do want the background color to affect that of a component, for example with states as in MD 1/2 (and so @mui/material); but you can't use opacity as a general alternative to a tonal scale, because you can't make any assumptions about the hue or tone of the layer(s) below.

[mbrookes]

Corollary: Option 2 isn't viable.

[siriwatknp]

Option 1 is the way to go, I'm closing this.