Plugin stylesheets must use CSS custom properties for colors

In a few days, I will merge this PR in core that makes a change to how plugin stylesheets are compiled. The change affects SCSS color variables used in plugin stylesheets. The tl;dr is that they need to be replaced with CSS custom properties. Most plugins are already updated, and in many cases, this is a simple change, the SCSS variable needs to be replaced with a CSS custom property:

-   background-color: $primary-low;
+   background-color: var(--primary-low);

The guide at Updating themes and plugins to support automatic dark mode has more examples and also shows how to handle more complex color transformations. (That guide should be all that plugin authors need to ensure their styles will work correctly.)

If you are wondering why we are making this change, read on.

Previously, core and plugin stylesheets were being compiled per theme in order to include the theme’s color scheme wherever SCSS color variables were used. This meant that a site with many themes (or a multisite environment) would take a long time to precompile because it would have to multiply the number of core and plugin stylesheets with the number of active themes in order to cover all the necessary combinations.

Since August 2020, and to support automatic dark mode switching, we added a separate color definitions stylesheet which stores the color variables as CSS custom properties. This change allowed us to switch color schemes on the fly, but it also abstracted colors out of most stylesheets. Thanks to the magic of CSS custom properties, we can now reference colors everywhere (core, plugins, themes) without having to load each theme when the stylesheet is compiled.

Over the past few months, we have been converting all plugins to use CSS custom properties. The vast majority of Discourse plugins are now up to date, but there is probably the odd plugin out there that still uses SCSS variables for colors and it will need to be updated.


Thanks for the clear explanation. Even I mostly understand it!

Is this going to cause upgrades and rebuilds to fail on sites with theme components that don’t play by these rules? As happened to Failed to Bootstrap, due to deprecated logo theme component for another reason?

If so, is there a way to make the error message more clear (to people who can’t make sense of the build logs)? And say something like “remove x plugin before trying to upgrade”. Or, better, is there a way to warn people on the admin panel when we know such a change is coming? (or maybe there already is one that no one reads).

1 Like

No, this won’t cause rebuilds to fail. It will only cause colors to be wrong on plugins that haven’t been updated. That should only happen on homemade plugins, I’ve gone through most plugins that are published here on meta and made sure they’re up to date.

The issue you linked has nothing to do with this change, that’s a theme component and we do block rebuilds currently if a theme component marked for auto-update can’t be auto-updated.


Ah. Hooray. Sorry about that. I’m still wrapping my head around these pieces.

1 Like