Custom properties are frequently treated as a convenience for avoiding repeated hardcoded values. Used deliberately, they're something more powerful: an actual API surface for a component, with the same design considerations any function or class API deserves.
1Fallback Values Are Default Parameters, Not An Afterthought
var(--property, fallback)'s second argument is what a consumer gets automatically if they never customize that property — which, in the overwhelming majority of real usage, is most consumers most of the time. Treating this fallback as a throwaway value ('eh, 6px seems fine') rather than a deliberate design decision is a missed opportunity: it's exactly analogous to choosing a sensible default parameter value for a function that most callers won't override.
This reframing matters practically: fallback values deserve the same design review and documentation as any other default behavior in a component library, not an implementation detail nobody thought carefully about.
2Distinguishing Public API From Private Implementation
A component's stylesheet often contains custom properties for two genuinely different purposes: some are meant to be a stable, documented surface consumers customize (--card-padding), while others are purely internal plumbing the component uses to avoid its own repetition, never meant for external use and free to change between versions without notice (an internal spacing calculation, say).
CSS itself has no mechanism to enforce this distinction — there's no private keyword — so teams establish it through naming convention, commonly a leading underscore or a distinct prefix like --_internal-gap. This isn't just cosmetic; it's a direct communication to anyone reading or consuming the component's CSS about which properties they can safely build on.
3Using Inheritance Deliberately For Context-Aware Components
Custom properties inherit through the cascade by default — a property genuinely worth exploiting rather than working around. Setting --card-background once on a .dark-section wrapper means every .card nested inside automatically picks up the dark background via inheritance, with zero per-card override logic needed; move a card in or out of that section and its background adapts automatically, purely from where it sits in the DOM.
This pattern — an ancestor establishing context, descendants automatically adapting via inherited custom properties — is a genuinely powerful, CSS-native alternative to prop-drilling context values through a component tree in JavaScript, worth reaching for specifically when a value needs to vary based on rendering context rather than needing an explicit override on every instance.
4Step-by-Step Breakdown
Custom Properties Are An API, Not Just Variables. It's tempting to treat CSS custom properties as simple find-and-replace variables. Production component libraries treat them as something more deliberate: a public API surface with sensible defaults, documented fallback behavior, and a clear line between what consumers are meant to touch and what's private implementation detail.
Fallback Values As Documented Defaults. var(--button-radius, 6px) isn't just a syntax quirk — the second argument is the property's default behavior when a consumer hasn't customized it, functioning exactly like a default parameter value in a function signature, and should be chosen and documented as deliberately as one.
Fallback Values As API Design. How should the fallback value in var(--button-radius, 6px) be thought of, from an API design perspective?
- →As pure error handling for a broken or missing variable
- →As the deliberate default value a consumer gets if they don't customize the property, exactly like a function's default parameter
- →It doesn't really matter what the fallback is, since most consumers will always override it anyway
Public vs Private: A Naming Convention For Intent. Not every custom property inside a component's CSS is meant to be touched by consumers. Many teams adopt a naming convention — a leading underscore or a distinct prefix for internal-only properties — to signal which custom properties are the supported public API versus private implementation detail that could change without notice.
Public vs Private Custom Properties. Why might a component library distinguish 'public' from 'private' (internal-only) custom properties via naming convention?
- →There's no functional or practical reason — CSS doesn't enforce this distinction anyway
- →To signal to consumers which properties are a stable, supported customization surface versus internal detail that might change without notice
- →Private-prefixed properties render measurably faster
Cascading Defaults For Context-Aware Components. Because custom properties inherit through the cascade, a component can define a sensible default that automatically adapts based on where it's rendered — a --card-background set once on a .dark-section ancestor cascades down into every card inside it, without each card needing its own explicit dark-mode override.
Cascading Custom Property Defaults. Why does setting --card-background on a .dark-section ancestor automatically affect every .card inside it?
- →Because .dark-section .card is an implicit CSS selector
- →Because custom properties inherit through the cascade by default, so descendant elements pick up the ancestor's declared value
- →It wouldn't actually work without an explicit override on every card
Custom Properties As Real API Design. You now think of CSS custom properties as a genuine API surface: fallback values chosen as deliberately as function default parameters, a naming convention distinguishing public from private properties, and inheritance used deliberately to create components that automatically adapt to their rendering context.
Provide A Fallback For An Undefined Token. var()'s second argument is used automatically whenever the custom property itself isn't defined.
Level Up 🚀
Advanced cheat sheets, SEO tricks, and interview prep for this topic.
Browser Support
Fully supported.
Fully supported.
Fully supported.
Fully supported.
Accessibility (A11y)
1Public Custom Property Fallbacks Should Default To Accessible Values
Since most consumers will rely on the fallback, choosing an accessible default (sufficient contrast, adequate touch target spacing) for public custom properties means accessibility is the out-of-the-box behavior, not something every consumer needs to opt into.
2Context-Inherited Properties Should Preserve Accessibility Guarantees Across Every Context They Apply To
A --card-background inherited into a dark section must still be paired with correctly-adapted text color guaranteeing sufficient contrast in that context — inheritance handles the mechanism, but the actual contrast relationship still needs deliberate design.
SEO Implications
- 1
A Well-Designed Custom Property API Reduces Component Duplication Across A Growing Codebase
When components expose sensible, documented customization points, teams are less likely to fork or duplicate a component just to achieve a slightly different look, keeping the overall CSS footprint leaner.
- 2
Context-Aware Inheritance Patterns Reduce The JavaScript Needed For Theming Logic
Using CSS inheritance for context-dependent styling (like section-level dark mode) can eliminate JavaScript-driven conditional class logic that would otherwise be needed to achieve the same adaptive behavior.
Best Practices
Treat Every Public Custom Property's Fallback Value As A Reviewed, Documented Design Decision
Since most consumers rely on the default, its quality directly determines the component's out-of-the-box experience — it deserves the same care as any other default behavior choice.
Adopt And Consistently Apply A Public/Private Naming Convention Across The Whole Design System
A convention applied inconsistently provides little value — consumers need to be able to trust that the pattern reliably distinguishes safe-to-use properties from internal implementation detail everywhere in the system.
Frequent Bugs
A component library update silently breaks consumer code that depended on an internal, undocumented custom property.
The property should have used a private-naming convention (like a leading underscore) signaling it wasn't a supported API surface; document and enforce the public/private distinction going forward.
A dark-mode section's cards don't pick up the correct background color automatically.
Verify the component references the custom property via var() with inheritance in mind (not a hardcoded value), and that the ancestor section actually declares the custom property for descendants to inherit.
Real-World Examples
A Documented Component API Via Custom Properties
A design system's button component exposing a small, deliberate set of public custom properties as its customization API, with clearly-named internal properties kept separate.
.button {
/* Public API */
--button-background: var(--color-action-primary);
--button-radius: 6px;
/* Private implementation detail */
--_button-icon-gap: 6px;
background: var(--button-background);
border-radius: var(--button-radius);
}