Palette

The theme palette provides a collection of common color settings for the UI.

There are some predefined "basic" and "elevation" colors. By default, they are set up with predefined color values, but these values are not intended to be used in production, but rather configured according to the project needs, since they do not follow a proper visual guideline.

Basic Colors

The palette is composed by the following basic colors:

primary - Primary interface component elements.
secondary - Complementary color.
success - Successful messages. It should tend to be green.
error - Error messages. It should tend to be red.

Each color has the following variations:

main
dark1
dark2
dark3
light1
light2
light3

Only the main color is required. If the other variations are not configured, they are calculated based on the palette setting tonalOffset.

tonalOffset is the color tone variation factor. It is used to calculate dark and light variations. From 0 to 1, by default 0.1. The higher the number, the stronger the effect.

An example of configuring the primary color with all its variations so no calculations are made:

tsx

import { createTheme } from '@arwes/design';
const theme = createTheme({
  palette: {
    primary: {
      main: '#0ff',
      dark1: '#0cc',
      dark2: '#099',
      dark3: '#066',
      light1: '#3ff',
      light2: '#6ff',
      light3: '#9ff'
    }
  }
});

An example of configuring the secondary color with only the main color, leaving the remaining variations to be calculated with custom the tonal offset:

tsx

const theme = createTheme({
  palette: {
    tonalOffset: 0.15,
    secondary: {
      main: '#f0f'
    }
  }
});

The resulting theme palette will have all the color variations.

The theme palette can be accessed like:

tsx

const theme = createTheme();
theme.palette.primary.main; // '#0ff'
theme.palette.primary.dark1; // '#0cc'
// ...

Custom basic colors can be created using the utility createThemePaletteBasic like:

tsx

import { createTheme, createThemePaletteBasic } from '@arwes/design';
const theme = createTheme({
  palette: {
    yourOwnBasicPalette: createThemePaletteBasic({ main: '#00f' }, 0.1)
  }
});
theme.palette.yourOwnBasicPalette.main; // '#00f'
// ...

Elevation Colors

There are some colors used as "levels" or "elevations" to delimit or prioritize surfaces. The elevation effect is basically a color which becomes lighter or darker progressively for different surfaces according to the color luminosity.

The palette is composed by the following elevation effect colors:

neutral - For general surface and containers backgrounds.

The neutral color does not have variations automatically generated, but rather they are calculated when requested.

To calculate the elevation of a color, the elevationOffset setting is used.

elevationOffset is the tone offset to darken or lighten according to the color luminosity. It goes from 0 to 1, by default 0.025.

An example of defining the neutral color:

tsx

const theme = createTheme({
  palette: {
    elevationOffset: 0.025,
    neutral: {
      main: '#111'
    }
  }
});

Then the color elevation can be calculated based on a multiplier number of the tone offset:

tsx

// Since it is a "dark" color, it is lightened.
theme.palette.neutral.elevate(0); // '#111' (The unchanged color)
theme.palette.neutral.elevate(1); // '#171717'
theme.palette.neutral.elevate(2); // '#1e1e1e'
theme.palette.neutral.elevate(3); // '#242424'
// ...

Custom elevation colors can be created using the utility createThemePaletteElevation like:

tsx

import { createTheme, createThemePaletteElevation } from '@arwes/design';
const theme = createTheme({
  palette: {
    yourOwnElevationPalette: createThemePaletteElevation('#101', 0.025)
  }
});
theme.palette.yourOwnElevationPalette.elevate(0); // '#101'
// ...

Extra Settings

The palette can be setup with any extra color settings with no enforced structure as needed.