CSS Best Practices for AEM Part I

In any large scale project CSS can often be put on the back burner while some of the more “important” features of the project are built out. In reality, CSS can make or break your site (literally!). You may be thinking “it’s just CSS – it can’t be that hard” but when building an enterprise level site, a well thought out CSS design can save you a tremendous amount of time in the future. For the sake of this post, we’ll assume you have a basic understanding of CSS and a basic understanding of Adobe Experience Manager (AEM) component development.


Selectors are arguably the most important concept to grasp in modern CSS, even more than styling. Without selectors, there isn’t a “cascading” part of the style sheets. Incorrect selectors can cause even more problems. A general rule of thumb is to use about 2-3 selectors, and no more than 6. Too few selectors, and your CSS will likely affect more elements than intended. Too many, and your CSS becomes limited, confusing, and difficult to maintain.

Thus, the number one rule for selectors is: Select classes at the lowest level, and make them as specific as possible, while still being reusable.
Otherwise, you’ll often find your CSS more difficult to maintain, and sometimes it’ll even have unintended consequences on other parts of your site. Just because CSS is loaded for a specific component, does not mean that it will not affect other elements on the same page.

This typically means we should try to:

A general rule for making the component reusable across pages, is to rely on classes only present in the component itself. Rarely is there a guarantee that your wrapper class will always be the same, especially in future reuse cases. In AEM, this includes the generated wrapper and its classes, as the classes will change based on the “path” specified in the include statement.

Exceptions include tightly coupled wrapper classes (I want a different style if the component is in this wrapper), and implementing CSS for a specific component instance, where you’re usually better off with page-specific CSS.

Why is that? Preferring page-specific CSS imports vs. instance-specific:

Design Order

  1. Global default style
  2. AEM design-level CSS defaults
  3. Component CSS defaults using only markup in the component
  4. Tightly-coupled components CSS defaults
  5. Page-level/page components CSS defaults
  6. CSS for specific component instances (usually with loosely coupled wrapper)

Overriding CSS will typically follow this order as well, where the lower levels override the ones above them.

A well planned and thought out CSS design is just as important as any other part of your site, and is a major contributor to the success or failure of a project. When dealing with complex sites, you should really take the time to sit down and think about a strategy for your CSS, while keeping the above-mentioned points in mind.

Check out part 2 of our CSS series, where we touch on accessibility, selector priority, and how to better organize your CSS. If you’re in the process of optimizing or implementing your AEM solution, we can help. Reach out to our team today.

Subscribe to Our Newsletter

Get the latest insights from Blue Acorn iCi