Pattern Lab goes Django

Thibaud Colas
Thibaud Colas

Senior Front End Developer and Wagtail Consultant 11 Dec 2020 3 min read

If you’re into UI component reuse, you may have heard of Atomic Design and Pattern Lab. We’re big fans, but Pattern Lab runs on PHP/Node, while we decided long ago to leave the PHP world behind, and concentrate on Django.

We took Pattern Lab with us, and built django-pattern-library – a.k.a. Pattern Lab goes Django.

Pattern libraries at Torchbox

At Torchbox, pattern libraries are a way to separate concerns between front-end and back-end development. We’ve been using our Django pattern library package for a couple of years to:

  • Clarify responsibilities and separate concerns, both in code, and as members of a development team between front-end and back-end development.
  • As needed, enable front-end developers to work on pages and block templates before any back-end development happens.
  • Encourage code reuse and components composition – defining independent UI components, reusable without markup copy-paste, and reusable on other projects like any Django app.

Does this sound useful to you? Go and have a look at our introductory presentation from Wagtail Space US 2020, Reusable UI components – A journey from React to Wagtail:

Slides: Wagtail Space US 2020 - Reusable UI components – A journey from React to Wagtail

Our first big release

Pattern Lab has been around for a while, and so has our own django-pattern-library, but we only open-sourced it a few months ago. Sadly it wasn’t as well documented or flexible as we would have liked it to be. This is starting to change with our most recent release. Here are the headline features:

View the full CHANGELOG. Along those shiny features, we also released two massive improvements to the project: a new documentation website, with lots more content – guides, recipes, and reference info. And also a new demo site, so you can see for yourself how the project works (although note the public demo is exported as a static site).

Template structures

Starting in v0.3.0, you may structure your project’s templates in however many folders you want. This feels like such an obvious need in hindsight, but the pattern library having only been an internal Torchbox project for a while, it didn’t really need to accommodate that many different structures!

This is now possible thanks to the new SECTIONS setting, with the previous predefined structure kept as the default for backwards compatibility. It also comes with a lot of black magic to decide which templates are partials and should be rendered in a base template, and which can be rendered as-is.


This new management command might not be relevant for all projects but it’s worth highlighting use cases this is intended to support:

  • Quick project-wide check of whether there are any templates that fail to render (for example due to out-of-date mocks), that can easily run as automated tests in continuous integration.
  • Static exports of the pattern library, for those cases where you want a simple way to share patterns publicly or host them alongside documentation, rather than alongside your site.
  • Automated tests of UI components, particularly in continuous integration, where it might be problematic for you to get a Django server up and running depending on the project’s dependencies.

Combined with tools like Pa11y and pa11y-ci, this makes it much simpler to run site-wide automated accessibility tests for all of your project’s templates, making the most of the pattern library’s tightly controlled mock data. We’re currently experimenting with this in our project’s Gitlab CI pipelines:

Screenshot of pa11y-ci output in GitLab CI showing reported issues on pattern library templates

There are still rough edges (for example the command will abort the whole test suite if only a single template fails to render - oops!), but we hope you’ll find uses for this nonetheless.

What’s next

Hopefully more of the above – new features, more stability, better documentation. We’re particulary keen on finding ways to mock templates with factories rather than plain data structures, and combining our Django rendering features with Storybook’s developer experience.

Thibaud Colas
Thibaud Colas

Senior Front End Developer and Wagtail Consultant 11 Dec 2020 3 min read

Get in touch to talk about your project

  • 1


    We like to meet. Early on. It’s the best way to work out whether we are a fit.

  • 2

    De-risk your project

    We can remove the barriers to getting your project going. Ask us how we do this.

  • 3

    Your brief

    If you’ve got a brief, we’d love to see it. If you haven’t, talk to us before you write it, we can help.