Creating style guides with Atomic Docs: Awesome or Awful?

Leave a Comment

Designers and developers are increasingly creating style guides to decouple front and backend concerns. Atomic Docs is a new tool that helps you manage your frontend components and generate style guides. I put it to the test to see if it makes the process easier.

Atomic Design is the concept that we aren’t designing pages anymore. Rather, we’re designing systems of components. In short, we can start with atoms, such as a title, a byline, or a link. From those atoms you can create molecules and organisms, i.e. a blog post preview or site header. Our page templates are then made up of different combinations of our organisms. Atomic Docs is a new tool that manages your components (and their underlying code) and automatically generates a frontend style guide. I recently came across it in an article and wanted to put it to the test to see how it would impact my workflow. Here are my takeaways.

Easy Setup

Atomic Docs was very easy to get started with. I set up a WordPress site with our distro and starter theme. Then, I downloaded the source files from github and moved them into the root of my theme. That’s pretty much it. I simply needed to change the destination CSS file path in our gulpfile.


Naming Things

One of the hardest and most important tasks of a frontend developer is naming things such as classes, ids, field names, filenames, etc. The names we choose must convey meaning to other developers, designers, and site admins and the choices are endless. Atomic Docs makes this task much simpler. The user interface is intuitive and easy to use and you can easily rename your components and categories, saving you from needing to go into many different places in your project to manually change names. The best part is, it generates all the SCSS and PHP partials you need for development, and puts them in organized folders and in the proper order. The extra head space Atomic Docs provides allows you to focus on what your components will be called, rather than where they will live and if they’re in the right place in your folder structure.

Design Driven Development

As the name suggests, Atomic Docs is a great tool for the Atomic Design process or Style Guide Driven Development. Atomic Docs isn’t limited to these processes though. The practice of developing and designing your user interface separate from backend technology can benefit any team. You can also deliver a living style guide to your client and design team for future use.


BEMr’s Beware

When using Atomic Docs, it’s important to remember to name categories and components the same way you would manually. Most importantly, do not use spaces, as filenames with spaces are obviously invalid. This is not a major fault, however, it wasn’t clear initially that there was a one-to-one correlation between the generated filename and the name you assign it in the tool. This is also worth noting if you use BEM naming conventions. Filenames have the potential to get a little confusing when you get down to the Modifier level as you can see in the screenshot above.


Atomic Docs is awesome! It delivers a great developer experience for creating and managing SCSS partials and makes it easy to create a living style guide. I’m looking forward to utilizing it on my next project.

If you’d like to learn more, get in touch!

A Quick, Responsive Grid System with Flexbox

Leave a Comment

Until recently there has never been a purposeful CSS layout tool. Early web designers were forced to create their own methods for achieving designs. Although very clever, these methods were basically hacks. In this article I’ll talk about some of those hacks, and a new tool called Flexbox; a method specifically designed with layout in mind. Please note: the example in this article is intended for people with a basic understanding of Flexbox and Sass. For a complete guide to Flexbox check out this article on

Hack 1: Tables

Before CSS was fully supported in web browsers, designers used table markup to create page layouts. The intended purpose of tables is to display data, but it became a means of achieving web designs. Using tables for page layout solved a problem for designers, but was far from an ideal solution. The markup was heavy and complicated and there was no separation of concerns (structure vs style). As the web grew up and CSS became more widely supported designers began using the CSS float property for laying out pages.

Hack 2: Floats

Although it’s original intent was to allow text to flow around images, the CSS float property became prominent for creating full page layouts. In earlier times of web development we had to contend with browser bugs and clearing <div>’s. We’ve come a long way since then. The browser wars have stabilized, and with the advent of front end frameworks like Neat and Foundation, creating bulletproof, responsive layouts is less of a challenge.


Now we have Flexible Box Layout or Flexbox for short. A method developed with the intention of being used for layout, it allows us to create flexible layouts for both desktop and mobile in an intuitive way. With the help of a few Sass mixins we can create a pretty robust and useful grid system with Flexbox. The first thing to do is setup column width variables. In my case I’m using a 12 column grid:

// Columns
$one: 8.33%;
$two: 16.667%;
$three: 25%;
$four: 33.333%;
$five: 41.667%;
$six: 50%;
$seven: 58.333%;
$eight: 66.667%;
$nine: 75%;
$ten: 83.333%;
$eleven: 91.667%;
$twelve: 100%;

Then, I create a mixin for containers:

// Container Mixin
@mixin grid($width: $container) {
  $container: $width;
  display: flex;
  flex-direction: row;
  flex-flow: wrap;
  flex: 0 1 auto;
  max-width: $container;
  margin: 0 auto;

Lastly, add a mixin for columns:

// Column Mixin
@mixin column($span: $columns) {
  $columns: $span;
  box-sizing: border-box;
  flex: $columns $columns auto;
  flex-basis: $columns;
  max-width: $columns;
  padding-right: $gutter;
  padding-left: $gutter;
  padding-bottom: $gutter*2;

You can see it all in action this codepen below.

See the Pen flex box semantic grid system by jmacaluso711 (@jmacaluso711) on CodePen.


Part of Flexbox’s power is it’s simplicity. As you can see in the above example, we can build a responsive grid system in less than fifty lines of code. If your users are still largely on IE9 or below, you may want to stick with float based systems, otherwise, support for Flexbox is strong, and getting stronger. The days of layout hacks are behind us and the the future of CSS layout is bright.

This article original appeared on Constructive Insights by John Macaluso

3 Ways to Hit Your Website Development Deadline

Leave a Comment

When there’s a tight deadline to develop a website it’s tempting to jump right in and start building. It’s best to take a step back and take some time to plan in order to save time and effort in the long run. In rebranding our firm to coincide with ComNet15, we were faced with the daunting task of going from no name to having a new website in three months—an audacious goal where a lot had to happen in tandem in order to get things right. In this article, I’ll explore three techniques our web developers used along the way that really helped us hit our launch date: creating re-usable modular pieces of code, using CSS naming conventions, and collaborating closely with our designers as they generated content.

Keep Code Organized and Re-usable

The key to any successful web project is organization, especially when the development deadline is aggressive. When you’re working quickly, file structure, PHP includes, JavaScript, and Sass all need to be easily readable and decoupled (i.e. modifying one piece of code should not affect another.) This was especially important for our team because we had two developers simultaneously developing on the same code base. We divided up responsibilities in an effort to not step on each others toes: Quinton Mosley handled most of the back end work while I focused on the front end.

Of course, organization goes beyond the code you write; it extends to the way you represent the building blocks for site content in your CMS. At Constructive, we love Open Source CMSs like WordPress and Drupal, and because we apply design thinking in web development, almost all of the WordPress sites we build make heavy use of the Advanced Custom Fields (ACF) plugin. ACF is a great tool out-of-the-box, but when you use advanced features like flexible content fields, your page templates can get a little crazy. To keep things neat and organized and help speed up development we created some reusable patterns with ACF.

In the backend we created one field group that would house all of our flexible content groups:


Then in one file we wrote:

<?php if (have_rows( $acf_flexible_content )) : $row_count = 0; ?>

   <?php while (have_rows( $acf_flexible_content )) : the_row(); $row_class = 'fc-row-' . ++$row_count; ?>

      <?php if (get_row_layout() == 'text_column_image_column' ) : ?>

         <?php include(locate_template('/flexible_content/acf-text-image.php')); ?>

      <?php elseif (get_row_layout() == 'large_image' ) : ?>

         <?php include(locate_template('/flexible_content/acf-large-image.php')); ?>

      <?php elseif (get_row_layout() == 'image_gallery' ) : ?>

         <?php include(locate_template('/flexible_content/acf-image-gallery.php')); ?>

      <?php elseif (get_row_layout() == 'text_block' ) : ?>
         <?php include(locate_template('/flexible_content/acf-text-block.php')); ?>

      <?php endif; ?>

   <?php endwhile; ?>

<?php endif; ?>

The above code loops through the flexible content fields and locates the appropriate template part to use for that group.

In another file, we created a template:

<?php $matchesPrevious = get_sub_field('matches_previous_color'); ?>

  <section class="fc-text-image row <?php the_sub_field('order'); ?> <?php echo $row_class; ?> <?php if ($matchesPrevious == 1 ) :?>row--matches-previous<?php endif; ?>" <?php echo acf_background_color_style('text_column_background_color'); ?>>

    <div class="container">


        $headline = get_sub_field('headline');

        $content = get_sub_field('content');


      <?php if (!empty($headline) || !empty($content) ) { ?>

        <header <?php if(get_sub_field('knockout')): ?> class="fc-knockout-text" <?php endif; ?>>

          <h2><?php the_sub_field('headline'); ?></h2>

          <?php the_sub_field('content'); ?>


      <?php } ?>

      <div class="fc-image__column fc-text__column--image" <?php echo acf_background_color_style('image_background_color'); ?>>

        <img src="<?php echo acf_image_url('image', 'text-with-image-thumbnail'); ?>" alt="<?php the_sub_field('subheading'); ?>" />




We could now use any of our fields in whatever template we wanted and have all the power of flexible content fields.

  $acf_flexible_content = 'flexible_content';

Block, Element, Modifier

Lately we’ve been warming to the idea of using BEM syntax for all our styling. This was especially important for our project because we had UI, UX, coding and content development all happening on at once. Keeping the CSS modular and clean was essential. Here’s a small sample of how we styled the flexible content field groups:

.fc-carousel {}

.fc-carousel__image {}

/* for carousels with a browser container graphic */

.fc-carousel--browser {}

The fc prefix, is given to all the styles. In this example, carousel is the element and browser is the modifier.

We also made use of Sass @extends wherever possible so that we weren’t repeating ourselves. Here’s how we did links for fc text blocks:

%fc-text-links {
   color: $body;
   position: relative;
   display: inline-block;
   transition: all 0.3s ease-in-out;
   @include font-serif;
   &:after {
     content: " ";
     display: block;
     position: absolute;
     height: 1px;
     width: 100%;
     bottom: 2px;
     border-bottom: 1px dotted $body-dark;
   &:hover {
     &:after {
       border-bottom: 1px solid $body-dark;

.fc-header {
   a {
      @extend %fc-text-links;

Collaborating and Catching Edge Cases

A benefit of designing, developing, and generating content at the same time is you can discover edge cases and address them immediately. Our project pages have several different layouts and options that can be combined in a number of different ways.

We decided early on that we wanted to give content editors some control over the look and feel of the page they are creating, as they create it. As our Director of Technology, Ian Mariano, often says, “Admins are users too” – a topic worthy of its own article and more. Keeping that in mind, we included a color picker on all flexible content groups so that they can use an appropriate color for a particular project. But this presented a problem: what if the color the editor selects clashes with the sites body text color? Checkboxes to the rescue! The simplest way to solve this problem was to add a checkbox to the field group that will add a class when selected. We could then target that class in the CSS and take care of the clashing color issue.


Here we opted to give the editor the option to select “Knockout Text.” This adds the class .fc-knockout-text to that group and we change the text color to white in the CSS.

You’ll notice in the previous image there is also a checkbox labeled “Matches Previous Row’s Color.” This brings us to another edge case. Like any well built site there are default styles set. In our case we have 90px’s of padding on each of our rows of content. In some cases there will be two consecutive rows that the editor wants to be the same color. Remembering that we have 90px of padding top and bottom on all our rows and in this scenario we’ll end up with 180px of padding on top. That doesn’t look so hot. In comes another checkbox. Basically, it tells us if this row matches the previous row’s color. If that is true, remove the padding from the top of that row.

Moving Forward

Keep it simple. All projects present numerous challenges. When there’s a tight deadline and you’re doing design, development, and content all at once, the complexity of these challenges can escalate exponentially. Surprisingly, my blood pressure stayed under control during this one and I think that’s largely because we maintained tight collaboration and organization. The tools we used enabled us to also focus on the Admins’ user experience and more easily collaborate with our whole team. For example, our founder, Matt Schwartz, could enter content into a new field group and then pop over to my desk to work through a design problem that needed to be addressed. Adding new field groups was easy because of all the ground work we did and styling them was simple with our naming conventions.

Of course, the above examples came from our experience with an in-house project; client projects present another layer of complexity. But regardless of whether we are working on an internal project or a client project, many of these lessons hold—and we’ve incorporated many of the techniques and approaches developed in this project to our core WordPress Distro and client work flow.

This post originally appeared by John Macaluso on Constructive Thinking.

Creating Tabs with Advanced Custom Fields and jQuery


I was recently working on a WordPress project that required me to create multiple content tabs per page. Considering this was a WordPress project naturally all the tab content needed to be powered through the CMS. With Advanced Custom Fields this is actually a pretty straight forward task.

Step 1

Create a repeater field for the tabs

Repeater Group

Repeater Text

Repeater Content

as you can see I’ve created a Tab Label (text) field and a Tab Content (wysiwyg) field.

Step 2

Next we need to create the PHP template. The main thing here is that we want to generate some dynamic classes and ids that we can use later in our jQuery. The link tab-section--<?php echo $tabSection++; will generate a class called .tab-section--0, .tab-section--1, an so on, for as many tabs that exist. Likewise the anchor tags within the tab-nav will get a hash id that matches the id of a corresponding .tab-content.

  $tabSection = 0;
  $tabLabel = 0;
  $tabContent = 0;

<section class="tab-section tab-section--<?php echo $tabSection++; ?>">
  <nav class="tab-nav">
   <?php if(have_rows('tabs'): ?>
    <?php while(have_rows('tabs'): the_row(); ?>
     <a href="#tab-content--<php $tabLabel++; ?>"><?php the_sub_field('tab_label'); ?></a>
    <?php endwhile; ?>
   <?php endif; ?>

  <?php if(have_rows('tabs'): ?>
    <?php while(have_rows('tabs'): the_row(); ?>
     <div id="tab-content--<?php $tabContent++; ?>" class="tab-content">
      <?php the_sub_field('tab_content'); ?>
    <?php endwhile; ?>
  <?php endif; ?>


Step 3

Next let’s give our tabs some styles. Pretty straight forward.

.tab-nav {
  span {
    display: inline-block;
  a {
    color: #fff;
    @include font($roboto-bold);
    display: inline-block;
    padding: .5em 1em;
    background-color: lightgray;
  .tab-nav--active {
    a {
      background-color: gray;

.tab-content {
  border: 1px solid lightgray;
  padding: 1em;


Step 4

Finally, it’s time to make them work with jQuery. We want to initially hide all the .tab-content div except for the first one. Also, we give the first .tab-nav an active state by default. I’m using an each function with an iterator variable that will match up with the iterator variable in the php template. This way all the tabs sets will function independently from each other.

    $('.tab-section--' + i + ' .tab-content').not(':first').hide();
    $('.tab-section--' + i + ' .tab-content:first').show();

    $('.tab-section--' + i + ' .tab-nav span:first').addClass('tab-nav--active');

    $('.tab-section--' + i + ' .tab-nav').on('click', 'span', function(){
        //Remove class of active tab
        $('.tab-section--' + i + ' .tab-nav').removeClass('tab-nav--active');
        //Add class of active to clicked tab
        $('.tab-section--' + i + ' .tab-content').hide();
        //Show clicked tab
        return false;


ClimateWorks wins Commarts Webpick of the Day

Leave a Comment

Read about it here


Leave a Comment

Hello and welcome to my new website.  You are now in the blog section where I will attempt to share my thoughts, experiences and discoveries in all things code.  I’ll do my best to be as clear and thorough as possible.

Here’s a breakdown of some of the stuff you might see.

Preformatted Text

Typographically, preformatted text is not the same thing as code. Sometimes, a faithful execution of the text requires preformatted text that may not have anything to do with code. Most browsers use Courier and that’s a good default — with one slight adjustment, Courier 10 Pitch over regular Courier for Linux users. For example:

“Beware the Jabberwock, my son!
    The jaws that bite, the claws that catch!
Beware the Jubjub bird, and shun
    The frumious Bandersnatch!”

Code can be presented inline, like <?php bloginfo('stylesheet_url'); ?>, or within a <pre> block. Because we have more specific typographic needs for code, we’ll specify Consolas and Monaco ahead of the browser-defined monospace font.

<div class="foo">
   <h3 class="__bar">Hello World!</h3>
#container {
	float: left;
	margin: 0 -240px 0 0;
	width: 100%;