PPK's post "Two options for using custom properties" describes a split between him and Stefan Judis over how to write link hover and focus styles. One pattern gives each state its own custom property; the other collapses them into a single one.
With separate properties per state:
.component1 {
--linkcolor: red;
--hovercolor: blue;
}
.component2 {
--linkcolor: purple;
--hovercolor: cyan;
}
a {
color: var(--linkcolor);
}
a:hover,a:focus {
color: var(--hovercolor)
}
With one property shared between states:
.component1 a {
--componentcolor: red;
}
.component1 :is(a:hover,a:focus) {
--componentcolor: blue;
}
.component2 a {
--componentcolor: purple;
}
.component2 :is(a:hover,a:focus) {
--componentcolor: cyan;
}
a {
color: var(--componentcolor)
}
The two-property version reads as more explicit about what each custom property does. The single-property version has its own appeal beyond saving a declaration: the custom property maps 1-to-1 onto a single real property.
Extending it into a "menu" of change
The idea can be pushed further: one ruleset holding one custom property per property, so the block becomes a kind of menu of what will change. PPK's framing:
Now you essentially found a definition file. Not only do you see the component's default styles, you also see what might change and what will not.
Anything you expect to alter gets a custom property; anything you don't, doesn't. It's an approach worth trying, but the objections are real.
.lil-grid {
/* will change */
--padding: 1rem;
padding: var(--padding);
--grid-template-columns: 1fr 1fr 1fr;
grid-columns: var(--grid-template-columns);
/* won't change */
border: 1px solid #ccc;
gap: 1rem;
}
Why it's only a hint
At best, the convention signals intent. Custom properties don't enforce anything:
- Styles can still be changed without a custom property involved, by overriding the declaration directly later. That wipes out the custom property's role.
- A property set in a custom property can be left untouched forever —
--grid-template-columnsmay look like it varies by circumstance but never actually does. - A modifier class can change something the base ruleset implies is fixed, such as border width, without any custom property being involved.
To make the pattern work at all, it has to be treated as a convention, much like a generic coding standard. The cost is maintenance: every declaration you decide to change has to be refactored to either be a custom property or stop being one.
A related case for direct overrides and modifiers:
.lil-grid.two-up {
grid-columns: 1fr 1fr;
}
.lil-grid.thick {
border-width: 3px;
}
The broader point is that HTML and CSS already constitute an implicit styling API. HTML becomes the DOM in the browser, and CSS styles that DOM: select things, style them. A menu of what can and cannot be styled may be unnecessary because that menu already exists. A well-crafted set of custom properties can still be part of the picture — it just doesn't need to function as a hard rule about what changes.
The Shadow DOM's cost to the same API
Jim Nielsen, writing in "Shadow DOM and Its Effect on the Unofficial Styling API":
[…] the shadow DOM breaks the self-documenting style API we've had on the web for years.
What style API? If you want to style an element on screen, you open the dev tools, look at the DOM, find the element you want, figure out the right selector to target that element, write your selector and styles, and you're done.
That's pretty remarkable when you stop and think about it.
This is the sharpest criticism of web components: not the Shadow DOM itself, which is arguably the best part of them, but the requirement to invent a styling API for each component — custom properties that pierce inward, or ::part — in place of the DOM + CSS approach that has worked all along.



