Kick things off by running npm create pattern-lab.

At the next prompt, pick an install location, if you are working on a Drupal theme you should place PatternLab in its own directory off the root of the theme.

At the next prompt select edition-node (handlebars engine) this is confusing since we ultimately want to use the php-twig engine, but we can get there with the node version. All other version are deprecated, don't start a new project with anything else.

Next you will need to make a choice between a starterkit or a blank slate. Choose starterkit-twig-demo if you want something that works out of the box. Keep in mind that you will likely have to delete and modify a bunch of files down the road. This is a good option if it is your first time using PatternLab. It serves as a great example for how to structure and setup patterns. The twig starter kit is good if you are working within Drupal. If no Drupal, then you can choose what is best for the flavor of project you are working on.

If you want to get started straight away with a custom instance, then choose None (Start a blank project). Skip the next section if you are doing a blank project.

Starting with starterkit-twig-demo

As of this writing there is a mistake in the starterkit package.json file. It is adding the handlebars engine as a dependency instead of the twig engine. To add it run npm install @pattern-lab/engine-twig-php if its already in package.json, you can just ignore this.

Another thing that needs adjusting is in the patternlab-config.json file. Open it up and find the patternExtension property and change the value from “hbs” to “twig”.

After it is finished installing, run npm run pl:serve to spin up the style guide locally. It should open the style guide in your browser once it completes. Here you can see a fully built example of a style guide. If you wish to use this foundation then you are all done and can start modifying and removing the existing patterns and templates. You can skip the next section for starting with a blank project.

Starting with a blank project

Assuming that this will be a twig based project, the first thing you will want to do is add the twig engine as a dependency. Run npm install @pattern-lab/engine-twig-php to add it.

Next you will want to pop open the patternlab-config.json file. Here is where you will define your patterns and the directories they resolve to.

First thing to change is the output in the style guide to be in twig, find the patternExtension property and change the value from “hbs” to “twig”.

Next you will need to add the namespace definitions for twig to the engines object. This can be different from project to project but here is an example of a basic setup:

"twig": {
  "namespaces": [
    {
      "id": "atoms",
      "recursive": true,
      "paths": [
        "source/_patterns/00-atoms"
      ]
    },
    {
      "id": "molecules",
      "recursive": true,
      "paths": [
        "source/_patterns/01-molecules"
      ]
    },
    {
      "id": "organisms",
      "recursive": true,
      "paths": [
        "source/_patterns/02-organisms"
      ]
    },
    {
      "id": "templates",
      "recursive": true,
      "paths": [
        "source/_patterns/03-templates"
      ]
    },
    {
      "id": "pages",
      "recursive": true,
      "paths": [
        "source/_patterns/04-pages"
      ]
    }
  ]
}

This will define the location of the different pattern types in the source directory. Make sure to create these directories next. You can add a .gitkeep file to each as a placeholder if you don’t have any patterns to create yet. You will want the .gitkeep file for your repo because PatternLab will error out while building if the directory doesn’t exist and git won’t track an empty directory.

Next create at least one pattern. A good start is to add something basic in atoms like an example of the color palette to be used.

Once that is in place you can run npm run pl:serve to get PatternLab to build and serve the style guide locally.

Editing and adding patterns

Pretty much every file that you will want to edit will be in the source directory. Every project is different and may have patterns setup slightly different. If it is an existing project, a quick scan of the patterns directory in source will tell you the basic structure.

CSS and JS

CSS

There is nothing PatternLab specific about how CSS/SASS is handled. If this is part of a Drupal theme, you can have SASS compiled outside of PatternLab. You will need to define the path to the compiled CSS file in patternlab-config.json. It is the css value in the paths->source object. The value is the path to the css directory relative to the patternlab-config.json file.

Again, every project is different but it is good organizational practice to add sass partials for each pattern along side the twig file. If you do this, you will need to make sure that your sass compiler knows to search through the patterns directory for sass partials.

JS

Similar to CSS you will want to add the path to a directory containing the JS you would like to load with the style guide. For javascript you will want to edit the js value in the paths->source object. The value is the path to the js directory relative to the patternlab-config.json file.

There are a bunch of ways to handle this, above is just one example. You can also decide to handle JS and CSS at the component level within PatternLab and add those as libraries within your Drupal theme. There are many ways to do this, pick one that you comfortably understand or ask in the #engineering-frontend slack channel if you would like help.

Data

The PatternLab style guide operates outside of your CMS or app so to show data in your patterns, you will need to supply some dummy data. A good approach is to create a data file in the same directory that the pattern is. This is similar to the approach mentioned above for sass partials. The data needs to be a json file with the same base name as your pattern. The file will contain a json object with the datapoints you defined in the pattern, with dummy values.

Drupal

So if setting all of that up wasn’t bad enough, now you need to somehow make this all work with Drupal. The basic idea here is that you will create a new template or template override that includes a PatternLab pattern with data passed to it. Most of the complexity is in understanding the data structure available to the template and sending it over in a structure that the pattern is expecting. This sometimes requires preprocessing at different levels to make data available or to make the data structure more simplistic.

You should remain conscious of the kind of Drupal constructs that you are handing off to PatternLab. For example if you are rendering a block with a pattern from PatternLab, you will also want to include the Drupal attributes available to the template that is being overwritten as well as the prefix and suffix. Some of these things contain the frontend editing context tools for blocks as well as different class names and attributes that other modules key off of for functionality. You can get more info and help with this from the #engineering-drupal and #engineering-frontend slack channels.

Tip:

Define your patterns as component-libraries in the theme info file to make including them in templates a little easier. Example:

component-libraries:
  atoms:
    paths:
      - [path to PatternLab relative to info file]/source/_patterns/atoms
  molecules:
    paths:
      - [path to PatternLab relative to info file]/source/_patterns/molecules
  organisms:
    paths:
      - [path to PatternLab relative to info file]/source/_patterns/organisms
  templates:
    paths:
      - [path to PatternLab relative to info file]/source/_patterns/templates
  pages:
    paths:
      - [path to PatternLab relative to info file]/source/_patterns/pages

This will allow you to do the following in a template: include '@molecules/01-card/card.twig’. This is handy when the theme's templates are all nested at different directory levels.

That is your basic crash course in PatternLab, if you find something incorrect or wish to contribute to these docs, PRs are more than welcome.