Repeating a brand color or font stack across a stylesheet makes changes tedious. A CSS custom property gives that value one named definition. Its name begins with two hyphens, it is declared inside a rule, and var() substitutes its value where it is used. A declaration alone has no visible effect. section 2.6
Listing 2.18 Using a custom property
:root {
--main-font: Helvetica, Arial, sans-serif;
}
p { #1
font-family: var(--main-font); #1
} #1
The :root rule makes --main-font available throughout the page; the paragraph uses it as its font-family. section 2.6
Use :root for page-wide values such as a color palette. var() can take a second argument as a fallback when the named property is unavailable: var(--secondary-color, blue). Unlike preprocessor variables, custom properties also participate in the cascade and inheritance, so their values can change with an element’s context. section 2.6 section 2.6.1
One panel, two color schemes
Set --main-bg and --main-color on :root, then use them for a panel’s background and text. Redefine both on a surrounding .dark container. A panel inside that container uses the dark values; a panel outside uses the root values. The panel needs no separate dark-version rule. section 2.6.1
Choose the scope of a property to match the job:
- Put site-wide colors and fonts in a low-priority theme layer; keep a sidebar-only value beside the sidebar styles. section 8.2.2
- Change a shared gap value at a breakpoint instead of repeating every rule that uses it inside a media query. section 7.2.3
- For a growing palette, use numbered color names and, when useful, map raw colors to purpose-based foreground and background values. section 11.3.2
A property that uses var() can transition, but an unregistered custom property does not itself transition smoothly by default. To transition the custom property, register it with @property, specifying its syntax, inheritance behavior, and initial value. Check support before making this essential: Firefox did not support @property as of mid-2024. section 15.5
Listing 15.12 Transitioning a custom property
@property --hue { #1
syntax: "<angle>"; #1
inherits: false; #1
initial-value: 0deg; #1
} #1
button {
padding: 0.5em 1em;
border: none;
color: white;
--hue: 314deg;
background-color: oklch(39% 0.1 var(--hue)); #2
transition: --hue 0.5s linear; #3
}
button:hover {
--hue: 250deg;
}
The registered --hue is an angle. Changing it on hover transitions the button’s OKLCH background color. section 15.5
