Skip to content

Instantly share code, notes, and snippets.

Last active Sep 24, 2018
What would you like to do?

Styleguide Throwdown - Part 1



Large goals of style guide:

"Platform agnostic enough” (to be useful to other teams) To make our development process easier Developers report that the current SG2 approach is not furthering those goals. In particular, there are complaints about having to do double work, and the fragility of our build and deploy process.

Some (possibly unreasonable) possibilities

  1. Return to SG1 style (Drupal ingests ONLY JS and CSS; twig templating done in Drupal)
  2. Ditch Pattern lab, do everything in Drupal, export a style guide artifact
  3. Decouple frontend and backend. Use Drupal for backend, use AngularJS or something else for frontend
    • We don't have enough time to move forward with this at the time but it could be a post-launch enhancement.
  4. Stick with SG2

Current problems

Main goals of the styleguide

  1. Platform "agnostic enough" branding guide for digital properties (us and every body else)
  2. Make our development process better.
    • stable
    • time efficient
    • robust

Are we agnostic enough?

Manning says yes, Neil says no. Why not just make an angular front end that we could use for everything. That will definitely not happen this year, but would be a really great thing for next year.

When we built it we were thinking of it in terms of Topics pages, but can other properties consume SG2 today? Could Frieda right now link to the CSS and JS.

It's currently incredibly difficult to get the CSS just for a single pattern. It is possible to just the HTML for the pattern but not to get the HTML for the whole thing.

We previously decided to not make it agnostic because it serves Drupal and it is the theme. This was a goal that drove a number of decisions. If we change the direction, then that will change the way that we make the decision.

Are we serving the Drupal team?

We're having to do the twig in both places or we have to write additional twig to make it use the twig. We're writing more complicated twig but we're only writing it once.

It is fragile because it is easier to break because we're using it twice.

We have to fit in "Drupal things" like attributes and suffixes and prefixes. These items don't have a natural home in the styleguide. This has a negative effect on the style guides.

CacheTags don't work if we don't render a {{content}] render.

There is a lot of duplicity because you're putting in a block element and then you need to create that block in both places.

In the SG1 approach the markup had to live in two places. The styleguide was just kind of "this is what it will probably look like." The visual regressions are fewer and farther between at this point. However, if there is a regression the theme straight up breaks and throws an error.

What's working

With PatternLab we would can prototype with UX. I don't know how prototyping would work without PatternLab.

The way that PatternLab is structured allows us to create our components is beneficial.

Possible approaches

Are these reasonable or unreasonable. We will decide who wants to defend one of these approaches on Friday. Friday we will be making a decision.

  • Switch just using a styleguide artifact like KSS
  • Using something like Emulsify or Particle and continuing to contribute back to those.

Should we ditch PatternLab?

Are modules a good idea? Should we be using something like Emulsify? Is there any reason for this to be separate and instead just put everything in D8. Is SG2 more coupled to Drupal? Not really. It's closely coupled in the governance. He is consuming everything. So maybe we just need to "nerdstein-ify" it more.

Why was SG1 abandoned?

Because it was a pattern organization chaos. Were there problems having a D8 theme work with SG1. The lots of small bugs (the minor differences in markup was causing a lot of bugs in D8). There were a lot of different ideas of how to do things and the high number of different developers led to a lot of different things.

Chat w/Jes

Yes we've done all of that.


I started looking at Lonely Planet's Rizzo And that got me thinking "I want Drupal do less" which is where it feels like we're all going.

What about Node Pattern Lab where it might play nicer with Angular or React? React has a built in styleguide called story book. Mass started building React components for Mayflower.

Storybook is a really great tool to help with building those js components really fast.

Twig from PatternLab

Yes you're still doing work, but you're writing less twig than you would be if you're trying to make Drupal match.


Hasn't solved the CacheTags problem. There is a drupal issue tracking that. So last year we were trying to converge them but we ran into some political issues. But this starts to take steps towards that.

Layout Builder

How important is the authoring experience? If this is important then that might eliminate a number of possibilities. If this experience is a can't change thing then what we're already doing is probably best.

Emulsify Coffee & Code


They're using PatternLab. Emulsify basically takes PatternLab and bridges everything to Drupal to make the theming process a bit more seamless.

Front end

There is a lot of things that are "baked in" when you download Emulsify, so we're trying to stick with that as much as possible. That way we're leveraging the tool as much as possible and making our lives easier when it comes to implementing in Drupal.

We're starting to put pages together. From a designer standpoint we're working really hard with engineers to make sure design is delivering exactly what he needs. Making sure we're naming things properly {{ preHeading }}, {{ heading }}, {{ postHeading ]]. This really forces us to think in that way. We weren't doing that as much before. There's a lot of back and forth to ensure we're doing things correctly in the way things are architected to make sure we're doing the PatternLab to fit the Drupal. There is "quiet a bit" of back and forth to establish this.

We didn't really know if we were using the same standard for design and Drupal development. We're trying to be on the same page as much as possible not only within Twig but also with the structure of the Drupal files and everything. We've been really trying to get on chats as often as possible to ensure we're setting the foundation for future PRs. We're working a lot together to learn how to make sure that everything is setup properly.

From a design standpoint "I don't know what I don't know" so being educated by Byron on what is expected from the Drupal, this is really helping me understand how to build what I build in Drupal. This requires some balance to ensure that the prototypes stay semantic and stay according to best practice without trying to force to much of Drupal with that.

When I'm putting things together I'm thinking about things should have been organized or named but I don't want to mess up things on the Drupal side by changing it. But it helps me realize that for the future I shouldn't make that same mistake.


We don't want to have to recreate any of the markup in the Drupal template, which is what we've been doing a lot of previously. So we use a lot of {% include %} and {% extend %}.

We're overriding a Drupal template with {% extends %} and then setting variables for what I want to pass to it with {% set %}. When you use extends you can replace blocks, so what I've done as part of the process creating a twig block to replace an entire section a replace it with {% block %} and the values that we need from Drupal. You can also do twig blocks inside of other twig blocks.

{% extend %} has to be the very first line of the file. {% include %} you can pass variables but you can't override anything. {% embed %} allows you to pass variables and override anything.

According to fourkitchens on when you should use which checkout this.

It makes some things more challenging but in the end if you need to modify it you only need to modify it one place and you don't have to worry about a difference in markup.


Emulsify actually includes the menu template from Drupal, so if you're building a menu component in PatternLab it's using the Drupal menu file and make sure that the markup is correct for Drupal. Then you don't have to worry about refactoring that for Drupal.

It looks like some of it is going not just PatternLab to Drupal but also Drupal to PatternLab. This makes some things easier because of how Drupal generates a very specific markup. This also limits some of the amount templates that have to override.

It's a mashup of both PatternLab and Drupal. It bridges the gap so that you can integrate easier.

Emulsify using the underscore to denote these files so that they are ignored from the menu system in PatternLab. These are pulled from the stable theme.

If designers have the ability to use that structure to build out each of the menus that appears on the site then that seems to speed up the process for the Drupal developer. It gives them the option to just include the block in the region template then that's all done. A lot of blocks are being placed in the templates. Are any being placed in the UI? Yes, in the footer.

It requires me to think about what's the best way to build this in a way that it can be seamless for the developers.


As we move forward we've been tightening it up between how things should be broken down and named. So we originally were prototyping first and then doing the theming, but the more we move forward the more we're tightening things up. So we're having a lot of conversations around how we should be doing things in PatternLab so that it aligns with the Drupal artifact.

Knowledge Share

  • Documentation
  • Conversations with this.
  • Can we starter kit? Possibly. We could create a set of patterns that we use in our process so that any designer would have something to start from that they can use. That's the end goal.

Styleguide Throwdown - Part 2

Let's remember the possibilities.

Some (possibly unreasonable) possibilities

  1. Return to SG1 style (Drupal ingests ONLY JS and CSS; twig templating done in Drupal)
  2. Ditch Pattern lab, do everything in Drupal, export a style guide artifact
  3. Decouple frontend and backend. Use Drupal for backend, use AngularJS or something else for frontend
    • We don't have enough time to move forward with this at the time but it could be a post-launch enhancement.
  4. Stick with SG2

Style Guide 2 Presentation

The big takeaway with this is that we're not throwing away the big gains that we have with SG2, it's a lot better in a number of ways. We're just talking about re-writting the twig for Drupal instead of re-using it. So going forward, we would simplify SG2 in some ways more than SG1.


  1. Agnostic enough - can be consumed by other platforms
  2. Easy to decouple current code - copy and paste
  3. Speed - Meets deadline for AMA One project
  4. Known risks and steps to mitigate them
  5. Enables rapid prototyping with UX team
  6. Mitigates surprises and regressions by utilizing a release strategy that uses only tagged builds
  7. Faster and easier deployment process using Travis instead of Gulp
  8. Visual regression are reduced or eliminated by using backstop with TravisCi


  1. Duplicative markup
  2. Potential regression bugs

Work to be done

Go into the styleguide and see some of the organisms and put it directly into the theme layer. So we would be copy and pasting the twig from one place into the other. The current SG2 process can do what it's doing now. The Drupal templates shouldn't be doing the writing of things.

How will we keep the markup the same in both places? We'll be tagging the releases so that it won't have the risk of the regressions. But we will still be writing it twice.

How much unknown is it going into this? We're going down avenues with so many unknowns. If we go down this road, are there unknowns we're going to uncover? We've been using SG1 six months longer, so the risks and unknowns have already appeared to us. Going over this approach would be less risky. I don't want to get burned by continuing to go down new roads.

What we need to do is duplicate our code from PatternLab and get into Drupal:

  • Do releases via Gulp and not Travis

How long would it take to do all of this? Sprint cycle.

How long will it take you to do the theming? We're already using the SG2 theme and moving forward the theming tickets would just be straight forward Drupal theming. Just write twig templates and insert markup as is necessary. So we would still build in the styleguide and then bring it into Drupal? Yes.

Stick with SG2 (only better)



  • Win for this: we are writing twig in one place only. It's very dry.
  • Visual regressions are fewer and farther between
  • There's organized and structured data in PatternLab
  • Agnostic-ish markup


  • Having to do some double work
  • CacheTags issue

Potential improvments

  • Only include the structured data on the node level. Wire pattern lab and includes and structured data on one level, the node level. This would require more preprocess.

With Pattern Lab we have a dedicated framework to view, prototype, test that we can then tag and version. This becomes a separate artifact. PatternLab is a great tool to prototype in. UX team is now relying on this.


  • Will we have the same problems now of where you're doing the theming you're back and forth? Yes
  • Is it a cleanup of SG2? Yes, sort of.
  • Which one is harder to prevent issues? (issues being visual regressions) In my experience it's been easier to prevent visual regressions in SG2.

Ditch PatternLab altogether

We would just export an artifact styleguide. The styleguide would just be the result of the work that we do in Drupal. This would require a lot of rework. That would work for us, because everything is Drupal.

We would have to move everything back into Drupal and export this for whoever wants it. Then we would work on the plan to de-couple them completely later. It would be best if we could just build a front end for whatever, but we don't have time for that right now.


  • It doesn't enforce our idea of atomic design
  • There is no prototyping, or at least not the way that we've been doing it previously.

De-coupled Drupal


  • Complete separation from front end and back end.
  • One back end that populates any time of front end that you want. So we have a central repository of the content and we just want to pull it together. I think this would be easier to know where the bugs are.


  • You lose all of the native options for the content editors.
  • The content editors can't drag and drop (it's either all the work to make it happen or we lose it completely).
  • No in-text-editing, or at least we would have to re-create it
  • We would have to change the workflow for these things.


  • If we want to move closer to a de-coupled option then I would recommend using the Node version of PatternLab if we aren't trying to re-use the Twig.

We will go SG1 This is to address how we want to handle AMA One.


  • We will be doing visual regression testing in D8
  • We will be changing the way that we do releases
  • We will be copy and pasting all of the twig from the PatternLab into the Drupal
  • We could switch the PatternLab to Node (but that would be down the road)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment