There is a push in the industry to code against an external style guide to maintain consistent styling, have a reusable set of components to build applications with and provide a shared vocabulary for teams to communicate. The goal is that any web application built in an organisation can make use of this style guide to re-use existing CSS rules and/or Javascript functions. For example, one of the more well-known and recently-published style guides is the U.S. Web Design Standards, which will enable U.S. government agencies to create a unified user experience throughout their web applications.

When dealing with modern web applications, integrating a style guide is a relatively straightforward process. It often involves leveraging the existing Javascript build tooling to pull assets down via npm, and then having those assets processed as part of the build pipeline along with your application’s styles/scripts. Alternately, you can simply copy-paste a version of your style guide’s artifacts into your application – the quick and dirty way.

However, things are not always this easy. In my experience working with AEM/CQ, integrating a style guide into a project has consistently been a challenge.

To be fair, style guides are not to be blamed for this. AEM’s strict file structure, meta-data (.content.xml files and the like) and reliance on Java technologies can make it challenging to integrate with Javascript-based tooling. Each project generally ends up with a set of custom scripts to achieve this integration, resulting in a solution that is simply not maintainable. If you’ll indulge me for a moment, I’d like to take this opportunity to run through a few solutions I’ve come across to integrate style guides with AEM.