Sharing Common CSS Between Themes

This approach is ideal for managing multiple child themes with slight variations across different websites.
It promotes code reusability and simplifies maintenance.

CSS Variables (custom properties) allow you to centralize styling and enable easy customization across themes. By defining a base theme and customizing it using variables, you can maintain consistent design while allowing flexibility, such as supporting dark mode.

Using CSS variables in `tailwind.config.js`

First, replace desired properties in your tailwind.config.js with CSS variables. Here's an example using primary colors:

module.exports = hyvaModules.mergeTailwindConfig({
    theme: {
        extend: {
            colors: {
                primary: {
                    lighter: 'hsl(var(--color-primary-lighter) / <alpha-value>)',
                    DEFAULT: 'hsl(var(--color-primary) / <alpha-value>)',
                    darker: 'hsl(var(--color-primary-darker) / <alpha-value>)',
                },
            },
        },
    },
});

Opacity Modifiers

This setup uses hsl or rgb CSS color functions to retain TailwindCSS's opacity modifier functionality.
Hex color values aren't compatible with Tailwind's opacity modifiers when using CSS variables.
Use HSL or RGB syntax for opacity support.

If you don't need opacity modifiers, you can use any color syntax (hex, hsl, or rgb) but at the cost of losing Tailwind's built-in opacity functionality.

Tip

We now have a newer solution for easier customization and implementation, though it has slightly less browser support. Learn more on our dedicated CSS Variables + TailwindCSS Docs page.

Defining CSS Variable Values

After updating tailwind.config.js, the CSS variables need to be declared. There are several options:

Defining CSS Variables in global CSS

The CSS variables can be added to the root selector (:root) in a separate CSS file that is imported in a theme's tailwind-source.css file.

:root {
  --color-primary: 160 100% 54%;
  --color-primary-lighter: 20 255 175; /* Example using RGB syntax */
}

Defining CSS Variables in the Magento Theme Configuration

The variables can also be defined as above in the Magento Admin under
Design Configuration → <STORE> → HTML Head → Scripts and Style Sheets.

Defining CSS Variables in `.phtml` templates

Rendering the variables in templates is a common approach if the variable values are determined dynamically based on system configuration or other user defined input.

<style>
:root {
  --color-primary: 160 100% 54%;
  --color-primary-darker: <?= $brandColor ?>; /* Dynamic value from Magento */
}
</style>

Third-party Solutions for defining CSS Variables

Some libraries allow you to set CSS variables directly within your TailwindCSS configuration. Details are out of scope of this documentation.

Importing shared CSS from a Parent Theme

In Magento 2's traditional Luma theme, CSS inheritance via LessCSS was automatic, but this is not the case with Hyvä and TailwindCSS.

In Hyvä, files such as Tailwind configurations and CSS do not inherit automatically from a parent theme if they are missing in a child theme.

This means that, unlike the Luma theme, where LessCSS files were inherited by default, you will need to explicitly import settings and styles from the parent theme to the child theme.

This can be done by adjusting the import paths to point to the parent theme or a shared folder, which avoids manual copying of files.

Note

Before proceeding, ensure that your Tailwind content settings are properly configured to reference the parent theme's phtml and xml files.
If you're unsure how to do this, refer to the guide on setting up a child theme with Hyvä.

Importing a parent theme `tailwind.config.js`

There are two methods for importing the Tailwind configuration from a parent theme.

Using Presets

The presets method allows you to inherit the parent theme’s configuration and override any part of it.
This is the simplest and most straightforward way to work with configurations from an external source, similar to how TailwindCSS loads its default configuration by default.

For more details, check the Tailwind Presets Documentation.

const { mergeTailwindConfig } = require("@hyva-themes/hyva-modules");
const parentTheme = require("../../../../../../../vendor/hyva-themes/magento2-default-theme/web/tailwind/tailwind.config.js");

/** @type {import('tailwindcss').Config} */
module.exports = mergeTailwindConfig({
    presets: [parentTheme],  // Import the parent theme config
    content: [
        // Include your own purge config for this theme’s phtml and layout XML files
        "../../**/*.phtml",
        "../../*/layout/*.xml",
        "../../*/page_layout/override/base/*.xml",
        // Parent theme’s phtml and XML files (if this is a child theme)
        "../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml",
        "../../../../../../../vendor/hyva-themes/magento2-default-theme/*/layout/*.xml",
        "../../../../../../../vendor/hyva-themes/magento2-default-theme/*/page_layout/override/base/*.xml",
        // Optionally include app/code phtml files if needed
        //'../../../../../../../app/code/**/*.phtml',
    ],
});

Using Imports

For more granular control, you can selectively import specific parts of the parent theme’s Tailwind configuration. This method allows you to extend or modify only the parts you need, such as breakpoints:

const { mergeTailwindConfig } = require("@hyva-themes/hyva-modules");
const parentTheme = require("../../../../../../../vendor/hyva-themes/magento2-default-theme/web/tailwind/tailwind.config.js");

/** @type {import('tailwindcss').Config} */
module.exports = mergeTailwindConfig({
    theme: {
        extend: {
            screens: {
                ...parentTheme.theme.extend.screens,  // Import parent breakpoints
                "3xl": "2200px",  // Add custom breakpoints
            },
            // Extend or modify other parts of the configuration as needed
        },
    },
});

This method gives you the flexibility to inherit only the specific parts of the parent configuration.

Importing CSS Files

In addition to the Tailwind configuration, you can also import CSS files from the parent theme.
This works similar to importing other files by using relative paths to reference the parent theme’s CSS files.

For example:

/* Import from Hyvä default theme */
@import "../../../../../../../vendor/hyva-themes/magento2-default-theme/web/tailwind/theme.css";

/* Import from another custom theme in the same vendor folder */
@import "../../../acme-theme/web/tailwind/theme.css";

This works for any CSS file from a parent theme you need to reuse.
However, avoid importing the whole tailwind-source.css file, as this could lead to redundant tailwindcss imports.
Instead, import only specific styles or files that should be shared between the parent and child themes.

If you have multiple shared files across themes, you can group these imports into a dedicated shared CSS file, similar to how the theme.css file is structured in the Hyvä default theme.