Two ways to use custom properties

Custom properties are commonly treated as design tokens: you declare colors, spacings and fonts at the root of the page and consume them throughout the stylesheet. That is the classic pattern, shared with preprocessor variables for years. A second, more aggressive approach can sit alongside it — using custom properties for every significant styling decision on a given element.

Take a simplified Card:

.card {
  background: hsl(200deg 15% 73%);
  border: 4px solid rgb(255 255 255 / 0.5);
  padding: 2rem;
  border-radius: 8px;
}
.card > h2 {
  margin: 0 0 1rem 0;
  border-bottom: 3px solid rgba(0 0 0 / 0.2);
}

That works until variants arrive, at which point overriding those rulesets is entirely up to you. A custom-property-based version looks like this:

.card {
  --card-background: hsl(200deg 15% 73%);
  --card-border: 4px solid rgb(255 255 255 / 0.5);
  --card-padding: 2rem;
  --card-border-radius: 8px;
  --card-title-margin: 0 0 1rem 0;
  --card-title-border: 3px solid rgba(0 0 0 / 0.2);

  background: var(--card-background);
  border: var(--card-border);
  padding: var(--card-padding);
  border-radius: var(--card-border-radius);
}
.card > h2 {
  margin: var(--card-title-margin);
  border-bottom: var(--card-title-border);
}

It is more verbose up front, but the payoff shows up in a variation:

.card-variation {
  --card-background: purple;
  --card-padding-block: 2.5rem;
  --card-title-margin: 0 0 2rem 0;
} 

Three advantages follow directly:

  • Only values that were explicitly designed to change get changed; the base Card keeps its intended integrity.
  • Children of the variation can be styled without rewriting their selectors.
  • Overrides can be passed in from the HTML style attribute for quick one-off cases.

Fallbacks and granular control

Declaring and using in one place

Instead of declaring the custom properties at the top and referencing them below, you can combine both with fallback values:

.card {
  background: var(--card-background, hsl(200deg 15% 73%));
  border: var(--card-border, 4px solid rgb(255 255 255 / 0.5));
  padding: var(--card-padding, 2rem);
  border-radius: var(--card-border-radius, 8px);
}
.card > h2 {
  margin: var(--card-title-margin, 0 0 1rem 0);
  border-bottom: var(--card-title-border, 3px solid rgba(0 0 0 / 0.2));
}

If --card-background is set elsewhere, it overrides the fallback. The tradeoff: elements above .card can now override it, which is not the same as declaring values at the .card level. Whether that matters is a matter of taste.

Individual sides

Padding can be split into its own properties:

.card {
  --card-padding-block: 2rem;
  --card-padding-inline: 2rem;
  --card-padding: var(--card-padding-block) var(--card-padding-inline);

  padding: var(--card-padding);
}

A variation can then control only part of the padding:

.card-variation {
  --card-padding-inline: 3rem;
}

Mind the big gotcha: if these are declared at the root, this breaks, because the nested properties are already resolved. As long as they are first declared on .card, it works.

The cost of going too far

Ultimate control would look like splitting a color into its components:

html {
  --color-1-h: 200deg;
  --color-1-s: 15%;
  --color-1-l: 73%;
  --color-1-hsl: var(--color-1-h) var(--color-1-s) var(--color-1-l);
  --color-1: hsl(var(--color-1-hsl));
}

It is kinda neat, but likely too far. Colors will almost certainly be declared at the root and left alone, so the same gotcha makes overriding the low-level child properties impossible. And if you have a --color-1, you probably have 2 through 9, which is fine — a color system involves far more delicate design decisions than mathematical manipulation of color parts.

Design systems delivered as custom properties

Tailwind's popularity is driven in part by its atomic approach: a slew of one-property classes, and if you pick from the pre-configured options, the design ends up fairly nice. You can't go off the rails because you're choosing from a limited, designed set. A custom-properties-heavy approach is not exactly the same — you still need a class name abstraction rather than styling HTML elements directly — but it may inherit some of those desirable constraints. Picking only from pre-defined --spacing-x, --color-x and --font-x values can yield a more cohesive design.

The author's own experience: inching toward a design system more heavily based on custom properties feels good, if only because variations and overrides become more sensible to manage.

Third parties could ship their deliverables as nothing but a large set of custom properties:

Pollen

Not every deliverable needs to be the whole kitchen sink. Adam Argyle's transition.style ships a "Hackpack" that is nothing but custom properties of transition animation helpers.

The understandability cost

One pushback against the all-in approach is newcomer comprehension. If you wrote the system, it makes sense to you, but it is an abstraction layer atop CSS: CSS knowledge is shared by everyone, while bespoke system knowledge is shared only by the people actively working on it.

MY code that uses CSS custom properties to abstract things: perfect, good, readable

YOUR code that uses CSS custom properties to abstract things: messy, impossible to understand, i die

— Chris Coyier (@chriscoyier) February 16, 2021

Joining a system that leans heavily on custom properties means a steep learning curve.