Here are some insights on how CSS variables can simplify support of reusable and customizable components. Regardless of the framework you're using, this approach remains framework-agnostic.

Sample component

Suppose I need to add the Progress Bar component to my UI kit. Using React as an example, here's a straightforward implementation.

import "./ProgressBar.css";

export function ProgressBar({percentage} : {percentage: number} ){
  return ( 
    <div className="progress-bar">
      <div className="fill"
        style={{ width: percentage + "%"}}
      />
    </div>
  )
}

And CSS to add colors and basic rules

.progress-bar{
  width: 200px;
  height: 20px;
  border: 1px solid black;
}

.progress-bar .fill{
  height: 100%;
  background: black;
}

It's black by default and looks like this

The component is supposed to be reused in various parts of my app. I expect that each consumer should have the flexibility to customize the color of the bar and its border to align with their specific needs and color scheme.

I expect consumers to provide their own CSS rules to override the default colors. For example, a consumer can write the following CSS to make the progress bar green within the upload section.

#upload .progress-bar{
  border-color: green
}
#upload .progress-bar .fill {
  background-color: green;
}

This customization works as expected.

Each consumer can adopt the same approach, and at first glance, it seems like a solid solution.

Problem

However, that way of customization comes with several drawbacks

❌ Future bugs: In the long run, the progress bar component will be updated or refactored. The customization will break if classes are renamed or the hierarchy of the tags is changed.
🤯 Consumer's cognitive load: Developers using my component need to examine its HTML structure to determine the necessary CSS rules for overriding the default values.
⚒️ Cumbersome customization code: Modifying both the color of the bar and its border requires writing two separate rules.

Of course, it's not a big deal for simple cases like our ProgressBar. However more complex components in a large UI kit, especially when used by many developers, can present significant challenges.

CSS variable as a solution

To simplify customization and mitigate these issues, we can leverage CSS variables.

In my sample component, changes are made only in the CSS file

.progress-bar{
  --progress-bar-color: black;
  width: 200px;
  height: 20px;
  border: 1px solid var(--progress-bar-color);
}

.progress-bar .fill{
  height: 100%;
  background: var(--progress-bar-color);
}

Note that I declare the variable --progress-bar-color to set the color. Consumers can now customize the component as easily as

#upload .progress-bar{
  --progress-bar-color: green;
}

With this new approach, let's revisit the list of customization problems

❌ Future bugs: As the developer of the progress bar, I can modify class names and the hierarchy as needed. However, as long as I apply the CSS variable correctly to the updated elements, color customizations made by consumers remain intact.
🤯 Consumer's cognitive load: Consumers no longer need to examine my component's code to customize colors. The CSS variable acts as an 'interface' or 'abstraction,' allowing them to simply set the desired color without delving into the implementation details.
⚒️ Cumbersome customization code: Now, a single CSS rule can customize both the fill and the border elements.

Extra benefit

In terms of color customization, relying on the CSS variable streamlines the application of a general color scheme. You can manage all color settings with a simple CSS file that defines variables across the entire page.

Now, all the colors on the page can be controlled from a single location. To update the colors for the entire page, simply replace the CSS variable definitions with a new set.

This approach also facilitates the implementation of features such as light/dark themes or user-defined color preferences.

Outcome

💸 Better maintainability: By adopting the customization through CSS variables, the codebase becomes more maintainable, making future updates simpler and less time-consuming.

👍 Reduced Bug-Prone Code: The clear separation between the component's internals and its customization interface minimizes the risk of bugs, as changes to internal implementation don't affect how the component is customized.

😀 The code gets easier to understand: The use of CSS variables makes the solution more intuitive and easier to understand. Developers can quickly grasp how to modify styles without delving into complex or opaque code.

♾️ Framework-agnostic: You can apply this approach everywhere since it relies on the browser features only.