CSS file organization (for Drupal 8)

Last updated May 5, 2013. Created by JohnAlbin on January 14, 2013.
Edited by tim.plunkett, izus, carwin, manish_mics. Log in to edit this page.

Note: This document describes a file organization and aggregation strategy that has not yet been implemented in Drupal 8. See this core issue for that on-going work: http://drupal.org/node/1921610

File Structure

Rulesets should be grouped into logical files that enforce the separation of concerns within the CSS, that can be aggregated efficiently and that can be easily overridden by themers.

Drupal 8 follows a SMACSS-style categorization of its CSS rules:

1. Base — CSS reset/normalize plus HTML element styling.
2. Layout — macro arrangement of a web page, including any grid systems.
3. Component — discrete, reusable UI elements.
4. State — styles that deal with client-side changes to components.
5. Skin — purely visual styling (“look-and-feel”) for a component.

For more information about Drupal 8’s use of SMACSS, see the “Separate Concerns” section of the CSS Architecture page.

These categories help us keep CSS styles with different purposes from getting intertwined with one another. However, they don’t directly dictate file structure. Drupal 8 recommends the following guidelines for structuring CSS across files:

CSS files for Drupal modules

All of a module's styles should be placed in a css/ sub-directory and broken into one or more of the following files:

module_name.module.css: This file should hold the minimal styles needed to get the module's functionality working. This includes layout, component and state styles. Any needed RTL styling would go in a file named module_name.module-rtl.css.

module_name.theme.css: This file should hold extra styles to make the module's functionality aesthetically pleasing. This usually just consists of theme styles. Any needed RTL styling would go in a file named module_name.theme-rtl.css.

module_name.admin.css: This file should hold the minimal styles needed to get the module's admin screens working. This includes layout, component and state styles. On admin screens, the module may choose to load the *.module.css in addition to the *.admin.css file. Any needed RTL styling would go in a file named module_name.admin-rtl.css.

module_name.admin.theme.css: This file should hold extra styles to make the module's admin screens aesthetically pleasing. This usually just consists of theme styles. Any needed RTL styling would go in a file named module_name.admin.theme-rtl.css.

Note: Modules should never have any base styles. Drupal core's modules do not have any base styles. Instead Drupal core uses the Normalize.css library augmented with a drupal.base.css library.

If a module attaches a CSS file to a template file, the CSS file should be named the same as the template file, e.g. the system-plugin-ui-form.html.twig CSS file should be named system-plugin-ui-form.css

CSS files for Drupal themes

• Always separate Base, Layout, and Component styles into their own files. (Drupal will aggregate these separate files into one file, so there is no performance problem with this practice.)
• For complex themes, consider placing each component or component family in its own file.
• State rules, including media queries, should be included with the component to which they apply.
• Theme rules may or may not have their own file(s). Starter themes are encouraged to separate their theme CSS into separate files. Otherwise, include theme rules with their corresponding component.

Most themes will have at least the following:

Optionally, these can be further broken out. Below the base/layout/component level, naming is up to the module or theme. A more complex file structure using normalize.css and a mobile-first approach might look like this:

Aggregating CSS

In Drupal 7 and earlier, the “group” option and the “every page” option of drupal_add_css() controlled which files would be aggregated together. The groups were CSS_SYSTEM, CSS_DEFAULT (for Drupal modules), and CSS_THEME (for Drupal themes) and the every_page option was a simple boolean flag. This meant there were up to 6 aggregated files.

In Drupal 8, themes now have the ability to override stylesheets without affecting the “every page” option of the original stylesheet. See http://drupal.org/node/1876600. This means conditionally-loaded CSS remains conditionally loaded.

This also means it’s now simple for themes to affect conditionally-loaded styles, so all the theme-added CSS no longer needs to load after all conditionally-loaded styles. This greatly simplifies the default grouping strategy that Drupal 8 can employ. Instead of 6 aggregated files, we can just have 2:

1. The “Every page” aggregate. Includes:

   1. Base styles from libraries (like Normalize.css and drupal.base.css) and then Drupal themes.
   2. Layout styles from Drupal modules and then Drupal themes.
   3. Component styles (and their associated states and themes) from Drupal modules and then Drupal themes.
   4. State styles that are not included with components, from Drupal modules and then Drupal themes.
   5. Theme styles that are not included with components, from Drupal modules and then Drupal themes.

2. The conditionally-loaded aggregate. Includes:

   1. Layout styles from Drupal modules and then Drupal themes.
   2. Component styles (and their associated states and theme) from Drupal modules and then Drupal themes.
   3. State styles that are not included with components, from Drupal modules and then Drupal themes.
   4. Theme styles that are not included with components, from Drupal modules and then Drupal themes.

Note: there should never be conditionally-loaded base styles.

The order of styles within an aggregate are determined by the “weight” option of drupal_add_css() which will be:

The aggregated file itself is determined by the "group" option and the "every page" flag of drupal_add_css(). The group option defaults to the CSS_AGGREGATE_DEFAULT constant. Drupal core does not provide any other aggregate constants, but contrib can define their own aggregate groups.