A guide to providing semantic aliases for colors.
Referencing color scales by their actual scale name can work well, like blue and red. But often, creating semantic aliases like accent, primary, neutral, or brand can be helpful, especially when it comes to theming.
import { createCss } from '@stitches/react';
import {
blue,
green,
yellow,
red
} from '@radix-ui/colors';
const { styled } = createCss({
theme: {
colors: {
...blue,
...green,
...yellow,
...red,
accent1: '$blue1',
accent2: '$blue2',
accent3: '$blue3',
accent4: '$blue4',
accent5: '$blue5',
accent6: '$blue6',
accent7: '$blue7',
accent8: '$blue8',
accent9: '$blue9',
accent10: '$blue10',
accent11: '$blue11',
accent12: '$blue12',
success1: '$green1',
success2: '$green2',
// repeat for all steps
warning1: '$yellow1',
warning2: '$yellow2',
// repeat for all steps
danger1: '$red1',
danger2: '$red2',
// repeat for all steps
},
},
});With this approach, you will likely run into issues where you need to use the same scale for multiple semantics. Common examples include:
If you map yellow to "warning", you might also need yellow to communicate "pending".
If you map red to "danger", you might also need red to communicate "error" or "rejected".
If you map green to "success", you might also need green to communicate "valid".
If you map blue to "accent", you might also need blue to communicate "info".
In this scenario, you can choose to define multiple semantic aliases which map to the same scale.
import { createCss } from '@stitches/react';
import {
blue,
green,
yellow,
red
} from '@radix-ui/colors';
const { styled } = createCss({
theme: {
colors: {
...blue,
...green,
...yellow,
accent1: '$blue1',
accent2: '$blue2',
info1: '$blue1',
info2: '$blue2',
success1: '$green1',
success2: '$green2',
valid1: '$green1',
valid2: '$green2',
warning1: '$yellow1',
warning2: '$yellow2',
pending1: '$yellow1',
pending2: '$yellow2',
},
},
});
Or you can simply recommend that your teammates defer to the original scale name for situations where there is no appropriate semantic alias.
Each step in Radix Colors scales is designed for a specific use case. To help your team know which step to use, you can provide aliases based on the designed use cases.
import { createCss } from '@stitches/react';
import {
blue,
green,
yellow,
red
} from '@radix-ui/colors';
const { styled } = createCss({
theme: {
colors: {
...blue,
...green,
...yellow,
...red,
accentBase: '$blue1',
accentBgSubtle: '$blue2',
accentBg: '$blue3',
accentBgHover: '$blue4',
accentBgActive: '$blue5',
accentLine: '$blue6',
accentBorder: '$blue7',
accentBorderHover: '$blue8',
accentSolid: '$blue9',
accentSolidHover: '$blue10',
accentText: '$blue11',
accentTextContrast: '$blue12',
successBase: '$green1',
successBgSubtle: '$green2',
// repeat for all steps
warningBase: '$yellow1',
warningBgSubtle: '$yellow2',
// repeat for all steps
dangerBase: '$red1',
dangerBgSubtle: '$red2',
// repeat for all steps
},
},
})
Again, with this approach, you will likely run into issues where you need to use the same step for multiple use cases. Common examples include:
Step 9 is designed for solid backgrounds, but it also works well for input placeholder text.
Step 8 is designed for hovered component borders, but it also works well for focus rings.
In these cases, you can choose to define multiple aliases which map to the same step.
import { createCss } from '@stitches/react';
import {
gray,
blue,
green,
yellow,
red
} from '@radix-ui/colors';
const { styled, theme } = createCss({
theme: {
colors: {
...gray,
...blue,
...green,
...yellow,
...red,
graySolid: '$gray9',
grayPlaceholderText: '$gray9',
accentBorderHover: '$blue8',
accentFocusRing: '$blue8',
},
},
});
Or you can simply recommend that your teammates defer to the original step number for situations where use cases don't have an alias.
When designing for both light and dark modes, you sometimes need to map a variable to one color in light mode, and another color in dark mode. Common examples include:
Components that have a white background in light mode and a subtle gray background in dark mode. For example, Card, Popover, DropdownMenu, HoverCard, Dialog etc.
Components that have a transparent black background in light mode and a transparent white background in dark mode. For example, Tooltip.
Shadows that are saturated, transparent gray in light mode, and pure black in dark mode.
An overlay that is light transparent black in light mode, and a darker transparent black in dark mode.
import { createCss } from '@stitches/react';
import {
slate,
slateA,
grayA,
blackA
} from '@radix-ui/colors';
const { styled, theme } = createCss({
theme: {
colors: {
...slate,
...slateA,
...grayA,
...blackA,
panel: 'white',
panelContrast: '$grayA12',
shadow: '$slateA3',
overlay: '$blackA8',
},
},
});
const darkTheme = theme({
colors: {
...slateDark,
...slateDarkA,
...grayDarkA,
// Remap your colors for dark mode
panel: '$slate2',
panelContrast: '$grayA3',
shadow: 'black',
overlay: '$blackA12',
},
});
Avoid using specific variable names like "CardBg", or "Tooltip", because you will likely need to use each variable for multiple use cases.
If you wish, you can rename scales. Reasons might include:
Rename a saturated gray to "gray" to keep things simple.
Rename "sky" or "grass" to "blue" or "green" to keep things standard.
Rename a scale to match your brand, like how Discord use "Blurple".
Just to have some fun :)
import { createCss } from '@stitches/react';
import {
slate,
sky,
grass,
violet,
crimson
} from '@radix-ui/colors';
const { styled } = createCss({
theme: {
colors: {
gray1: slate.slate1,
gray2: slate.slate2,
blue1: sky.sky1,
blue2: sky.sky2,
green1: grass.grass1,
green2: grass.grass2,
blurple1: violet.violet1,
blurple2: violet.violet2,
caribbeanSunset1: crimson.crimson1,
caribbeanSunset2: crimson.crimson2,
},
},
});