Understanding color schemes in Joy UI

Color schemes is one of the most important aspect in JoyUI. It is an important source for customizing the look and feel of your web app.

Let us understand what each part does inside this schemes file so we could customize it later to our needs.

Palette

Understanding properties of the palette object is key. It houses all possible color combination the theme derives from. The palette object has colors which could be divided into

1. Accents.
2. Body defaults

1. Accents

These six accents are similar to Bootstrap's color types.

{
    pallete: {
        primary: {}, // the important one
        success: {},
        danger: {},
        warning: {},
        info: {},
        neutral: {}
    }
}

JoyUI comes with default color values for all those six accents. However you could add or remove accents as you like.

To use an accent use the color prop

<Button color="info">Follow me</Button>

From the above six accents, primary is the crucial one, determining the colors for the theme's four global variants (plain, soft, solid, outlined).

Each of the accent is an object housing properties with a valid CSS color code as its value.

These properties can further be divided into

1. Numeric color palette
2. Global variants palette

a. Numeric color palette

These are key value pairs of numerical value and a valid css color ranging from lightest to darkest. This is a common standard representing color ranges in web styling.[1]

The range of acceptable numeric value keys are

1. 50
2. 100
3. 200
4. 300
5. 400
6. 500
7. 600
8. 700
9. 800
10. 900

b. Global variants palette

These are key value pairs of a global variant name and a valid css color.

The four global variants (plain, soft, solid, outlined) by default has their colors picked from one of the above numeric color palette. Overriding the color of any one of the global variant can be done right here.

Let's say you want to change the background color for all soft variant components. The way to do is

{
    pallete: {
        primary: {
            softBg: '#fcba03'
        },
    }
}

By doing this all soft variant components will show that background color.

<Button variant="soft">Normal Button<Button/>
<IconButton variant="soft"><Icon /><IconButton/>

Each variant follows a naming convention for easy override.

(in camelCase)
<plain | soft | solid | outlined>
<hover | active | disabled>
<bg | border | color | (other css properties)>

2. Body defaults

I call this second category as body defaults because these houses colors for common things like body background, text color etc.

palette: {
    background: {
        backdrop: '',
        body: '',
        leve1: '',
        level2: '',
        level3: '',
        popup: '',
        surface: '',
        tooltip: '',
    }
    common: {
        black: '',
        white: ''
    },
    text: {
        primary: {},
        secondary: {},
        tertiary: {}
    },
    divider: '',
    focusVisible: ''
}

Color Schemes

Now that we have some understanding of configuring the palette object. We can put this object inside any one of the available colorSchemes available.

{
    colorSchemes: {
        light: {
            palette: {
                // your configured palette
            }
        },
        dark: {
            palette: {
                // your configured palette
            }
        }
    }
}

Each color scheme is either synced with

1. System color scheme.
2. User selection scheme.

This is a powerful feature which gives us the ability to have two different looks of the same app in light and dark mode.

Conclusion

And thats how you customize the theme configuration in JoyUI. Again, the palette object is the key.

References:

1. https://n8d.at/the-numeric-colour-palettes-in-modern-web-frameworks-explained
2. https://mui.com/joy-ui/customization/theme-colors/