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.
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
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
- 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
Cog uses the class
cog--mq for its use of the Susy container that is defined in
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
- The panel layouts included with Cog in
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.