Tools with COG: Drupal 8 Base Theme

Cog, introduced in a previous post, was built as a toolset for satisfying the needs of enterprise clients by Acquia's Professional Service Front-end Team. It's used as a basic starting point for a new project and includes tools for reinforcing front-end best practices. In this blog post we will introduce you to some of the tools included in Cog.

SMACSS Architecture

If you are unfamiliar with SMACSS, it is a Drupal standard method for categorizing CSS rules. On initial setup of a Cog subtheme, a folder titled "sass," will appear in your theme folder containing partials that are broken out according to SMACSS methodologies. While the initial file structure is intended to enforce SMACSS, it does not inhibit the use of other methodologies. The styles.scss file is responsible for importing all the partials and folders that the sass folder contains using globbing, allowing you to easily add new partials out of the box while giving you the flexibility to customize glob patterns to your needs.

The Sass file structure is as follows:

sass/ |-- _config.scss |-- _reset.scss |-- base/ |-- layout/ |-- components/ |-- state/ |-- style-guide-only/ |---- homepage.md |---- kss-only.scss |-- style.scss

To learn more about the Sass partials and folders installed with Cog, visit the Sass Structure section of our About document.

Gulp task runner

Core tasks assignments and execution are handled in Cog by using Gulp. The standard gulpfile.js file will be located in the root of your theme, but the actual Gulp tasks are broken out in the gulp-tasks/ folder. While Cog really only uses Gulp for project-specific tasks, there are numerous other ways to use Gulp for things like image compression or advanced compiling. Cog uses Gulp for a couple of different functions, which primarily revolved around these efforts:

• Compiling Sass into CSS
• Construction of a Style Guide
• Linting of Sass & JavaScript files
• General utility functions

Susy Grid System

Cog comes with the Susy grid system out of the box, but intentionally utilizes it with a light footprint. This was done so that you can easily switch out another grid system if desired. All grid and layout rules can be located within your sass/layout folder.

Cog uses the class cog--mq for its use of the Susy container that is defined in layout/_containers.scss. This cog--mq class is then used on the primary regions of the layout within the layout/page.html.twig file. The container class is designated by default at 80em, which can be updated in that single declaration in the_containers.scss file. There is also a container declaration for panel pages in layout/_panels.scss using the class cog-panel--mq with the same 80em measurement.

Susy provides quick and useful mixins to declare column widths within your grid. An example use of the span would would be written as include span(6 of 12), and would cause your element to span 6 of 12 columns. The use of the Susy columns are used in a handful of code within two methods:

• Scenarios with sidebars with the content column in layout/_sidebars.scss
• The panel layouts included with Cog in layout/_panels.scss

Yarn package manager

Cog makes use of Yarn, which is a package manager that seeks to improve the npm experience. Yarn uses the same declarations from your package.json file and saves dependencies to the node_modules folder. We use Yarn in Cog to to improve build speeds speed and minimize dependency bloat.

Living Style Guides with KSS Node

KSS is a syntax for CSS that's used to document CSS component usage, and generate living style guide entries. KSS-Node is a node package that we use in Cog to compile KSS into a style guide. Cog automatically parses the KSS from the SASS partials into a set of HTML files as part of it's build and watch tasks.

Using a styleguide during theme development allows front-end developers to write sass and markup independent of Drupal, and apply that mark-up as features become available for theming.

A special thanks to Jason Enter for his help writing this post.