Frontend style guide miniseries, part two: KSS Node

Dynamic style guides in Drupal 8 with KSS

With a smile on my face I sat down at my desk and installed Drupal 8. I’ve been following along with the all of the feature announcements and now I had my first Drupal 8 project. The client was open-minded and receptive to ideas, so I decided to not only explore Drupal 8 but to see how far I could push it—I was going to create a living style guide.

The designer in me loves style guides. They allow me to talk through design choices and serve as a point of reference for discussions with marketing, design, and development. When you have new needs you add a component to your style guide to see how it fits in, and when a component retires you can remove it. The pain point with style guides is that they are their own artifact and frankly, once created, they rarely get tended to or updated.

Keeping it living

Drupal 8 solves this problem with its “get off the island” thinking. This means that instead of needing to create something “in Drupal,” I was free to use tools from around the Web. A pair of my favorite style guide tools—Twig and KSS—work wonderfully with Drupal 8.

Every website has a wealth of components that need to be built and maintained. The header may have the site logo, navigation, search bar; the footer has utility navigation, social media, and a feed of the latest content; and the main content area has all the wonderful things that folks come to the site for, articles, image galleries, and forms to sign up for more information.

When we use a component-driven design approach, we are better able to maintain a site and provide consistency. We can predict changes across the whole site. By having a style guide, a client can see how the design comes together and understand how the whole will work.

What is KSS?

KSS (or Knyle Style Sheets) is documentation for humans. You enter some information into your CSS (or SASS, LESS, etc.) and when the CSS is processed by KSS, a style guide is created.

Let’s go through a common example: creating buttons. For our buttons, we’re going to create a call to action button and a disabled button. We’ll start by adding the following comment to the top of our buttons.scss file.

// Buttons
//
// .button--call-to-action - Call to action button.
// .button--disabled - Disabled button.
//
// Markup: buttons.twig
//
// Style guide: components.button
//

Let’s breakdown the content of this comment and how it relates to KSS.

The first line, “Buttons,” is the header for the section in the style guide.

The next few lines define our alternate classes for the buttons. This is because KSS will generate all the examples that we need to demonstrate the different states of the button.

For the markup, there are two ways to integrate it with KSS. The first, which isn’t shown here, is to actually write the code in the CSS comment, e.g. <a href="#" class="button {{ modifier_class }}">{{ label }}</a>. We aren’t doing that here because we want the markup to be in its own file so that it can be used by Drupal templates. Because of that, we point to a separate TWIG file.

The last line in the comment, “Style guide,” is how we keep the style guide organized. References can be either be numbers (1.2.1) or alpha (a.b.a or components.button). Use whatever makes sense for you and your team.

Using KSS to build components

Let’s build another component, a promo card, to show this process. This promo card is going to be a self-contained element on the site that will be used to promote content and entice users to click through.

Here is the HTML for the promo card as card--promo.twig:

<article
  {% if attributes %}
    {{ attributes.addClass('card-promo') }}
  {% else %}
    class="{{ classes }} {{ modifier_class }}"
  {% endif %}
>
  <h2>{{ label }}</h2>
  {% if content.body %}
    {{ content.body }}
  {% else %}
    {{ body }}
  {% endif %}
</article>

Then we create a card--promo.json file with the information (title, content, etc.) that we’d like to have displayed in the template. KSS was built to recognize that when a .json file shares a name with a .twig file and is in the same folder, it will import the json data into the template.

{
  "classes": " card-promo ",
  "label": "This is the card title",
  "body": "JSON Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam atque doloremque eligendi, fugiat fugit laudantium mollitia obcaecati perspiciatis quasi rem rerum saepe sint voluptate? Ab dicta eius harum magnam praesentium."
}

Here is the SCSS for the promo card as card--promo.scss:

.card-promo {
  border: 1px solid rebeccapurple;
  border-radius: 3px;
  max-width: 300px;
  padding: 20px;

  h2 {
    margin-top: 0;
    color: rebeccapurple;
    font-family: $font-family--garamond; 
    font-size: 1.5em;
    text-transform: none;
  }

  &:hover,
  &.pseudo-class-hover {
    border-color: red;
    color: red;

    h2 {
      color: red;
    }
  }
}

And now we add our KSS comment at the top of card--promo.scss:

// Promo Card
// This promo card is used to promote content on the site.
//
// :hover - Hover state for the promo card.
//
// Markup: card--promo.twig
//
// Style guide: components.card.promo
//

Bringing all this together in the style guide shows us what the card will look like.

Making components out of components

Now that the single promo card has been built we can create an example of what a row of three promo cards might look like in the site.

Since we are using TWIG, we will simply include card--promo.twig into our new component, card--triptych.twig. (A triptych is a piece of artwork shown in three panels. This is a bit of my art history studies influencing my naming conventions.)

Here is card--triptych.twig:

<section class="card-triptych-wrapper">
  {% include 'card-promo.twig' %}
  {% include 'card-promo.twig' %}
  {% include 'card-promo.twig' %}
</section>

And here is the corresponding card--triptych.scss:

.card-triptych-wrapper {
  display: flex;
  flex-flow: row nowrap;

  .card-promo {
    margin: 0 10px;
  }
}

Now that we have the HTML and CSS written, let’s add the KSS comment at the top of card--triptych.scss:

// Promo Card Triptych
// This shows the cards in a row of three, just like on the home page.
//
// Markup: card--triptych.twig
//
// Style guide: components.card.triptych
//

And here you can see the triptych in action:

Adding KSS components to Drupal templates

Now that we’ve put together a few components and got the client’s acceptance, it is time to connect our templates with Drupal templates. We’re going to connect up the promo card with an article teaser view.

Now we will setup our Drupal template. We start by creating the file that we need, node--article--teaser.html.twig. Inside this file we will be extending our original card file, card--promo.twig, and overwriting generic style guide content with Drupal-specific content.

{#
/**
 * Extending the base template for Drupal.
 */
#}
{% extends "@styleguide/card-promo.twig" %}

With this in place every change or edit that we make to our promo cards will be reflected on the live Drupal 8 site!

Creating dynamic style guides benefits the whole project

This component-driven approach is a big win for everyone in the process. The client wins because they can always see what is going on in their site via the style guide and make decisions based on live comps. Backend developers win because connecting Drupal templates to other TWIG files is an easy process. Frontend developers win because they can use their own organization structure or methodology for building components. And designers (who code) win because they can use their own skills to create components.

If you’d like to play with KSS and Drupal yourself here is a repo for you.

Read the rest of our Frontend Style Guide Miniseries:

• Part one: Introduction by Joe Tower
• Part two: KSS Node by Randy Oest
• Part three: Pattern Lab by Evan Willhite
• Part four: Discussion with Evan Willhite and Randy Oest