SMACSS in Drupal 8

This is an overview of Drupal 8's adoption of SMACSS for CSS architecture and file organization, along with some of the best practices outlined in the documentation at You can checkout the links at the end for reference.

SMACSS stands for Scalable and Modular Architecture for CSS and is a guide to CSS structure written by Jonathan Snook.

CSS Architecture for Drupal 8

The CSS Architecture for Drupal 8 aims to apply emerging best-practices for CSS, including the SMACSS system of modular CSS architecture.

The goals for Drupal 8 are to make CSS Predictable Reusable Maintainable and Scalable. Keeping those goals in mind Drupal 8 will Categorize CSS rules by applying the SMACSS system to rulesets and file organization.

The 4 main categories for SMACSS in Drupal 8 are Base, Layout, Component and Theme:

  • Base rules are to be used for styling HTML elements only.
  • Layout rules are for styling the arrangement of elements on the page, including any grid systems.
  • Components, which is referred to as modules in the SMACSS guide, are the reusable UI elements which should form the bulk of Drupal's CSS.
  • BEST PRACTICES for COMPONENT RULES: Indicate that instead of relying on markup structure and overly-generic class names, component elements will be defined using their own classes. A component's element, or sub-objects, should be defined using their own classes, prefixing them with the component's name followed by two underscores.
  • Using the same methodology, create component variants explicitly, adding a suffix with the variant name preceded by two dashes.
  • State rulesets are for applying Component styling for transient changes like hovering links, that deal with a component's appearance.
  • BEST PRACTICES FOR STATES RULES: say that style should be separated from behavior by using dedicated classes for JavaScript so that we can modify styling classes without breaking our JavaScript and vice versa. Prefix classes used for JavaScript with 'js-' and avoid applying inline style using JavaScript using a state class name whenever possible.
  • Theme styles. These will be used for the purely visual styling such as border, colors and backgrounds, font properties, etc. These rules should be separated from a component's structure enough so that omitting them won't break the functionality or usability.

CSS File Organization

The CSS File Organization will also follow a SMACSS style of categorization  in Drupal 8 organizing the css directory file structure into Base, Layout, Component and Theme stylesheets, or break them out further by using the structure as sub-directories of the CSS directory.

So starting with the CSS directory:

  • The Base subdirectory would contain stylesheets for HTML elements and any reset and normalize css files.
  • The layout subdirectory would hold various layout and grid system stylesheets.
  • In the Components subdirectory we could drop our stylesheets pertaining to the reusable components like buttons, tabs, etc. State rules and media queries should be included in the stylesheet of the component they apply to.
  • And finally, the Theme subdirectory would then contain those stylesheets with the visual styles.



CSS Architecture for Drupal 8 -

CSS file organization (for Drupal 8) -

Drupal CSS Formating Standards -

Article tags: