Semantic Color Variable Names

In the owning bundle’s single variables.css file, choose each color variable name from its UI purpose, not its current value. Start with the narrowest meaningful element or semantic role, then add the colored property or interaction state when needed to distinguish it, such as --cardSurface, --cardBorderHover, or --footerHeadingText. If several elements use a color for the same purpose, name their shared role rather than the first element that used it; if their purposes differ, give them separate variables even when their current values match. A variable name must remain accurate at every place it is used. Avoid color words, palette shades, and numeric scales, such as green, darkBlue, or gray100, including in a one-page or one-tenant theme.

Correct

:root {
    --cardSurface: #fff;
    --cardBorderHover: #748f55;
    --ctaText: #fff;
}

.card {
    background-color: var(--cardSurface);

    &:hover {
        border-color: var(--cardBorderHover);
    }
}

.cta {
    color: var(--ctaText);
}
:root {
    --textOnDarkSurface: #fff;
    --footerHeadingText: #fff;
}

.hero .title,
.dialog .title {
    color: var(--textOnDarkSurface);
}

.footer .title {
    color: var(--footerHeadingText);
}

Incorrect

:root {
    --about-green: #748f55;
    --darkBlue: #1e3a8a;
    --gray100: #f3f4f6;
}
:root {
    --footerHeadingText: #fff;
}

.hero .title {
    color: var(--footerHeadingText);
}

Fix

Inspect every use of the variable, identify the common UI purpose or separate purposes, and name each variable accordingly. For example, replace --about-green with --aboutCardAccent, and do not use --footerHeadingText for a hero title.