Automating Styleguides with Styleguide-Driven Development

In the past four years there has been an explosion of new technologies in front-end development. We are inundated with new projects like Bower, Cucumber, Behat and KSS. It is a lot to take in. At the past two Drupalcons there have been sessions about this overload (Austin 2014, My Brain is Full: The state of Front-end developement). Essentially those sessions are asking “What the hell is going on?”

As John Albin pointed out in his 2015 DrupalCon presentation, Style Guide Driven Development: All hail the robot overlords!, being a front-end developer now means constantly learning. The pace at which front-end development is evolving is too much to keep up with. There’s not enough time to read about the latest tools and techniques, let alone implement them! What we need is someone — or something — to do most of the work for us, so we can focus on better development.

Everyone is describing the one little piece they’ve created, but don’t explain (or even reference!) the larger concepts of how all of these elements link together.

So what big picture will help us understand today’s new front-end technologies? I’ve been doing front-end web development since 2007 (when building layouts with tables was the thing to do). Recently I realized that the current front-end flux is easily explainable as the beginning of a momental shift in web development: web development is embracing agile development. And the entire way we build websites is being turned inside out.

How does web development do agile? It creates styleguide-driven development (SGDD).

Styleguide-Driven Development (SGDD)

Styleguide-Driven Development (SGDD) is a practice that encourages the separation of UX, design & frontend from backend concerns. This is achieved by developing the UI separately in a styleguide. By separating the UI and backend tasks so they don’t rely on each other, it allows teams to iterate fast on prototypes and designs without having to make changes to the backend. With careful planning they should plug-and-play together nicely.

Styleguide-Driven Development isn’t just limited for big teams working on large applications, but the core concepts of developing UI elements separately in a style guide (living or static) can still benefit a sole developer working on a single page app.

The only requirements for styleguide-driven development are:

Front-end Technology Categories

We can categorize new front-end projects into just three categories:

• Front-end Performance (make shit faster)
  The front-end is where you see most of the lag while browsing websites, so it is critical to focus in this area.
• Components (make shit modular)
  Automation to ensure what you build today doesn’t break what you built yesterday.
• Continuous Integration (Automate shit)
  A way of bundling reusable chunks of HTML, CSS, JavaScript and other assets.

If you understand those three concepts, you can make sense of any of today’s new front-end technologies. There may be hundreds of new projects, but they are just different programming languages, different platforms, different projects and different APIs implementing one or more of those three ideas.

A core concept of agile development is reducing risk by controlling and minimizing your risk. One of the tools to prevent risk of regressions and minimize the risk of refactoring is continuous integration. While back-end developers and devops have been working on this for a while now, we are only now starting to see it in the front-end as those developers slowly get training in agile.

And to minimize complexity and risk of failure, front-end developers have started to develop components of HTML, CSS, and JS that are reusable and maintainable. Bootstrap? Foundation? Those are just pre-made reusable component libraries. But custom-designed websites and apps are also using the same technique while building custom component libraries.

Even as agile creeps into all the layers of web development, we still need a grand-unifying process that makes the new agile web development possible, unifying back-end, front-end, design, everything. Surprisingly, the once-derided style guide is the key.

Back in the day, website designs were always accompanied by style guides. Even if they weren’t out-of-date before they were delivered (“Ignore that part… I didn’t have time to update it after client feedback”), they always became out-of-date quickly. Since they were separate documents, they didn’t get maintained to reflect the current state of the website and became orphaned documents. But thanks to agile’s continuous integration, style guides can now be auto-generated from the website’s own source code, ensuring that the style guide and the website never get out of sync.

Component-based Web Designs

Patterns are big business in IT. You can’t get far in OO programming before hitting a book about design patterns, stressing the need for standardized solutions to particular problems. When it comes to web development though, design patterns never really hit off. Maybe because of the chaotic nature of the so-called web standards, maybe because we as an industry are just not ready for them yet. That’s no reason to ignore their potential though.

Large web applications generally have a lot of CSS files and often have many developers working on those files simultaneously. With the advent of so many frameworks, guidelines, tools, and methodologies (OOCSS, SMACSS, BEM, etc.), developers need a CSS architecture that is maintainable, manageable, and scalable. The answer is web components.

Web components are a collection of standards that are working their way through the W3C. They allow us to bundle up markup and styles into reusable HTML elements that are truly encapsulated. What this means is we need to start thinking about component-based CSS development. You’ll hear web development components go by many names:

• “Object” in OOCSS
• “Module” in SMACSS
• “Block” in BEM’s Block-Modifier
• “Web component” in HTML

Once components are planned, it’s easy to write a structure that handles all requirements. Components should be built to be:

1. Applied to a loose collection of HTML elements
2. Repeatable
   (even if never repeated)
3. Specific
   Replace CSS specificity with specific names
4. Self containing
   Styles do not bleed onto anything else
5. Nest-able

This especially helps when building a site with user contributed content. WordPress, Drupal, Joomla and other CMS‘s use WYSIWYG editors where often times you’ll have no control of the elements or classes used. Having a base component that set’s default styles for anchors, headlines, paragraphs and others will make it a lot easier to style contributed content.

CSS Design Components

When building projects, think of everything as a component. A great example is the SMACSS approach:

1. Base Components
2. Layout Components
3. Components
   • Component (BEM) (.flower)
   • Element (BEM) (.flower__petals)
   • Modifier (BEM) (.flower--tulip)
   • State (.flower:hover, .flower.is-pollinating, media queries, print styles)
   • Skin (.is-night .flower, should effect many components)

Drupal 8 Component-based CSS Approach

Drupal 8 uses the same component-based CSS design pattern (https://www.drupal.org/node/1886770):

.the-component
.the-component--modifier
.the-component__an-element
.the-component--modifier__an-element
.the-component.is-state
.the-component:hover
@media all { .the-component {} }
.the-skin .the-component

Remember not to make it complicated. Never build a class like .channel-tab__guide__upcoming-video__info__time. Avoid nesting components, elements and modifiers all in one. Also don’t try to be a perfectionist. You’ll end up spending a ton of time trying to decide what to name something instead of developing it.

Sucking at something is the first step to becoming sorta good at something.

The “Fugly” Selector Hack for Drupal

Have trouble inserting a class on an element in Drupal? This is especially a problem with links. Though Drupal offers many hooks to drill down to most containers, it’s sometimes hard to add a class to minor elements like the anchor tags.

// Pretty classes.
%feature__title-link {

}

// Ugly classes.
.feature__title a {
  &:link,
  &:visited {
    @extend %feature__title-link;
  }
  &:hover,
  &:focus {
    @extend %feature__title-link-is-hover;
  }
}

In the example above, the anchor tag is the container I don’t have access to. Instead I would have preferred to add the class .feature__title-link directly to the anchor tag. Unfortunately, sometimes you’ll be forced to apply this kind of selector hack when working with Drupal.

Continuous Integration with Automated Style Guides

Style guides promote a systematic approach to composing layouts, which used to be just a task within the user interface development process. Incorporating style guides into the development process places importance on the tools used to build the component catalogue.

With an automated style guide documenting your custom component library, building a website becomes straight-forward.

1. Pick a feature to begin development on.
2. Look through the existing style guide to see if it already contains a design component that you can use as-is or tweak.
3. If the new feature requires a new component, designers and front-end developers should work together to design and implement it.
4. Repeat.

Immunize your code — don’t get sick!

The problem with style guides is keeping them up-to-date. It takes time, valuable time that could be used to develop your project. Due to the resources and time involved, many companies completely avoid building them as it becomes cost prohibitive. Doing this is like not immunizing your kid. Sooner, rather than later your project will become sick. Symptoms include bloat, spaghetti code and design inconsistencies. As time goes on, the symptoms will become overwhelming and you’ll feel the need to put your project down and start from scratch.

That’s where styleguide-driven development comes into play. It’s ability for continuous integration or automation will save you time to focus on actual development.

Knyle Style Sheets (KSS) to the rescue!

As you write your CSS, software like KSS can automatically generate style guides for you with styleguide-driven development. KSS (https://github.com/kss-node/kss-node) is a popular one due to it’s simplicity. It’s basically a spec to write CSS comments so the parser can automatically generate a style guide for you.

/*
Button

Your standard button suitable for clicking.

:hover     - Highlights when hovering.
.shiny     - Do not press this big. shiny, red button.

Markup: index.html (optional)

Style guide: components.button (defines hierarchy)
*/
.button {

}
.button.shiny {

}

Used in conjuction with a task runner like Grunt, it’ll become a powerful allie in your web development workflow saving you a ton of time. With one command you can:

1. Build CSS from Sass/LESS/etc.
2. Linting for CSS/Sass/JavaScript
3. Minify and concatenate scripts/images
4. Build a updated style guide
5. Visual regression testing
6. Live reload

Take it further and create a gem file to install and load your project dependencies (Sass, Susy, Grunt, etc.) This makes it easier for new developers to get the project setup on their locals.

Additional Resources