How to Make Plugin CSS Consistent Across Themes

If you are developing the plugin for distribution, the professional way to deal with the plugin’s CSS is to adopt the philosophy of never fighting the theme, but integrating with it. That means the plugin’s CSS should not fight with the theme’s CSS. By adopting this philosophy, which is possible by the use of theme or user-defined CSS variables, you will be able to match the plugin’s CSS color to the color of every theme.

Let’s make the plugin’s CSS color:

• Work with any theme
• Match theme colors automatically
• Not break layouts
• Look native everywhere

Use Theme CSS Variables

The modern WordPress theme, especially WP 5.8+ or the block theme, defines global CSS variables. The plugin developers should use those variables in their plugin’s CSS. Some examples of global CSS variables and their usage in plugin CSS include the following:

# CSS
--wp--preset--color--primary
--wp--preset--color--secondary
--wp--preset--color--contrast
--wp--preset--color--base

# Usages in plugin
.custom-plugin-class {
  background: var(--wp--preset--color--base, #ffffff);
  color: var(--wp--preset--color--contrast, #000000);
}

This is the most modern way to implement CSS in a plugin that automatically matches the theme and falls back if the CSS variable is missing. Furthermore, use the core WordPress-provided button classes (button, button-primary, button-secondary, button-link-delete, button-link, button-large, button-small) instead of designing your own, like the following:

.root-plugin-class .button {
  @extend .button;
}

Inherit Typography and Colors

Instead of directly assigning the color and text style, inherit them from the parent and let the theme control the styling. Moreover, use relative units like em, rem, %, etc. for typography.

# CSS
.custom-plugin-class {
  font: inherit;
  color: inherit;
  font-size: 1.5em;
}

Use CSS currentColor

The currentColor is a CSS variable-like property that holds the computed value of an element’s color property. If the element has no color property defined, it inherits the value from the parent element. This property is very useful for styling the color properties, such as border-color, outline-color, icon color, etc.

# CSS
.custom-plugin-class {
  border: 1px solid currentColor;
}

Local Scope the Plugin CSS

Do not define the plugin CSS in the global scope; wrap it in plugin-specific root classes. Specifically, avoid global resets, overriding body styles, setting large margins, and hardcoded fonts in plugin CSS. Scope everything within plugin-specific root classes to prevent conflicts like the following:

.custom-plugin-class h1 {}

Use WordPress Color Palette

If you are building the block theme, enable the WordPress-provided color palette, which allows the theme users to pick the color of choices to match their needs when editing the block theme. The theme.json file or a single piece of PHP code enables these features. This feature generates the CSS classes in the form of has-{color-slug}-color, has-{color-slug}-background-color, and so on. You can use those classes in your theme. The PHP example to enable this feature is as follows:

# PHP
add_theme_support('editor-color-palette', $args);
$args = array(
	array(
		'name'  => __( 'Color Name', 'textdomain' ),
		'slug'  => 'color-slug',
		'color' => '#ffffff',
	),
);

Dynamically Read Theme CSS

If you are customizing the older theme, like the classic theme, you can dynamically read the theme CSS set by the theme customizer and pass that CSS value to the frontend using an inline style. Likewise, give a plugin option to set the button class name to match the theme button style. Look at the following example:

# PHP
$primary = get_theme_mod('primary_color');

wp_add_inline_style(
  'plugin-style-handle',
  ".custom-plugin-class { background: {$primary}; }"
);

Using Custom CSS Variables

You can also use the custom CSS variables in your plugin CSS and let the user customize them from the theme.

# CSS
:root {
  --custom-plugin-css-variable: var(--wp--preset--color--primary, #0073aa);
}

# use the variable like.
.plugin-css-class {
  background: var(--custom-plugin-css-variable);
}

Provide Support for the Color Scheme and Dark Mode

Provision for the color scheme detection from the operating system using the color-scheme property and the light-dark() function to automatically adapt to the user’s operating system preferences or enable support for the dark mode. You can also provide the user’s preferred color choices in the plugin settings and save them in the database to render later in CSS.

Final Remarks

Ideally, you should scope CSS within plugin-specific CSS classes, use theme variables, provide customization options, and let themes override styles to achieve plugin CSS consistency across themes.