A Living Style Guide

1. Is modular and re-usable

A Living Style Guide

1. Is modular and re-usable
2. Uses real world css and markup
3. Is always kept up to date
4. Is testable

Has this ever happened to you?

One tiny css change causes a regression deep in the outer reaches of your site

(and, it goes unnoticed for lord knows how long)

Cleaner Markup

Base Themes

• Classy
• Stable

Clearer seperation between logic and display

{%
	set classes = [
		'block',
		'block-' ~ configuration.provider|clean_class,
		'block-' ~ plugin_id|clean_class,
	]
%}
< div {{ attributes.addClass(classes) }}>
						

(From block.html.twig)

{% if attributes.hasClass('myClass') %}
  {# do stuff #}
{% endif %}
            

CSS Coding Standards

SMACSS

1. Base
2. Layout
3. Component (aka Module)
4. State
5. Theme (aka Skin)

BEM

Naming convention for components

• Block
• Element
• Modifier

.block {}
.block__element {}
.block--modifier {}
.block__element--modifier {}
						

Twig Extends

field.html.twig

Twig Blocks

Custom field.html.twig

Twig Extends

field--field-hero-header.html.twig

Style Guide API

hook_styleguide()

hook_styleguide_alter()

Style Guide D8 Port In-Progress

https://www.drupal.org/node/2606942

Style Guide Generators to the Rescue

Many options

• Pattern Lab
• Hologram
• KSS

KSS

• Human readable documentation syntax
• Any flavor of CSS
• Node JS implementation
• Grunt plugin

Install

(There's a module for that...)

npm install kss --save-dev

npm install grunt-kss --save-dev

KSS Syntax

// Solution Teaser
//
// A teaser for solutions taxonomy as displayed on the homepage
//
// Markup: kss_markup/solution_teaser.html
//
// Style Guide: Solutions.Teaser
.view-solutions .views-row {
  .views-field-field-category-icon .col-xs-3 {
    padding: 3%;
    border-radius: 50%;
    background-color: $gray_light;
    img {
      @extend .img-responsive;
    }
  }
}
            

Build Style Guide

grunt kss

or:

kss-node --source sass --destination styleguide --css css/style.css

Behat

Behavior Driven Development Framework

@javascript
Scenario: Footer style matches style guide
  Given I am an anonymous user
  And I am on "assessments/practice-assessments"
  When I am browsing using a "phone"
  Then "body" should have a "background-color" css value of "rgb(112, 84, 125)"
  And "#page" should have a "background-color" css value of "rgb(255, 255, 255)"
  And "footer" should have a "padding-top" css value of "50px"
  And "footer" should have a "padding-bottom" css value of "30px"
            

View Gist for detail of steps

Wraith

Screenshot Comparison Tool

• Compares two URLs
• Simple configuration
• Typically 'all or nothing' diffs

Phantom CSS

CSS Regression Testing

• PhantomJS/SlimerJS - Headless Browser
• CasperJS - Navigation and Scripting
• ResembleJS - Screenshot Comparison

Strengths: interactivity, easier to target components.

WebdriverIO

Selenium Bindings for NodeJS

• Selenium - Browser Automation
• WebdriverIO - Node library to drive selenium
• WebdriverCSS - CSS Regression Testing

Strengths: interactivity, easier to target components.

Install

npm install webdriverio@3.4.0 webdrivercss@2.0.0beta-rc1 selenium-standalone --save-dev

./node-modules/.bin/selenium-standalone install

Creating a Test

wdio-tests.js

var wdio = require("webdriverio");
var webdrivercss = require("webdrivercss");
var assert = require("assert");

var options = {
  desiredCapabilities: {
    browserName: "chrome"
  }
}
var browser = wdio.remote(options);
webdrivercss.init(browser, {
  screenshotRoot: "screenshots"
});

function assertShots (err, shots) {
  assert.ifError(err);

  Object.keys(shots).forEach(function(element) {
    shots[element].forEach(function(shot) {
      assert.ok(shot.isWithinMisMatchTolerance, shot.message);
    })
  });
};
            

browser
  .init()
  .url("http://breaktech.dev.dd:8083/")
  .webdrivercss("solutions", [
    {
      name: "solution teaser",
      elem: ".view-solutions .views-row:first-child"
    }
  ], assertShots)
  .click(".fa-bars")
  .webdrivercss("navigation", [
    {
      name: "Off Canvas Menu",
      elem: ".sidebar-offcanvas"
    }
  ], assertShots)
  .end();
            

Still Chasing...

• My workflow - tools continue to evolve
• Component Based Rendering Initiative
• Drupal and Style Guide Sharing Markup