Twig Tricks for Design Systems

Here at Basalt we often find ourselves working with Twig to create templates for design systems. Twig is a powerful and proven templating language for PHP-based content management systems (CMS's) such as Grav (a straightforward flat file CMS we use to power basalt.io) and Drupal (a standard CMS among our large enterprise clients). Handling data within templates, including Twig templates, is a common hurdle to implementing an effective design system. Here are some tips and tricks we've learned for handling data with Twig:

Remapping Variables

Design systems are meant to reduce inefficiencies in the development process. With that in mind, as we build our Twig templates, we should attempt to eliminate duplications. For example, let's consider the following three components:

Team Member Bio

Event Announcement

Blog Teaser

Initially these three components seem to be completely different; however, further inspection may show that they have nearly identical data structures.

Title (Team Member name, event name, blog title)

Sub-title (Team Member role, event date, blog author)

Image (Team Member photo, event flyer, blog picture)

Body (Team member bio, event description, blog summary)

Rather than make three separate components with situation-specific variables, we can make one flexible component to handle all three (or more!) use cases. Let's call this general use component a "media block".

The template is flexible enough to handle all three scenarios, which means building it out is easy and lacks redundancy. Now we can create templates for our use cases that map our specific data fields to the generic data fields.

If you're thinking "this feels too rigid" and "everything will look the same" I encourage you to temporarily focus less on the CSS and more on the data structure. The event announcements and team member bios shouldn't look the same on the front-end, but from a data structure viewpoint: they absolutely can.

How do we end up with unique UI for varying use cases? CSS based on component variations. Read on to learn how we manage class names to generate variations of a component.

Managing class names for variations of a component

Use Twig to set classes based off of component data. Rather than forcing developers to remember (or hunt down) class names and BEM modifiers, build them directly into the template. Upon instantiation, devs can run down the list of props for any given component and know that the correct classes will appear, resulting in properly styled rendering.

For example, instead of doing this upon instantiation:

which would mean having this in your template:

Do this in your template:

and this upon instantiation:

This example would compile to:

With the class variables set up in the template you can reduce errors by introducing required fields, or limiting choices to specified enums. From here, your CSS takes over and renders each type of media block (event, bio, or blog teaser) as you've defined it visually.

Design systems are all about the most effective and efficient approach to solving recurring problems. The proper use of a templating language like Twig can make or break the experience of working with any given design system. I hope the tips I've outlined here help you get the most out of this great technology, save you time, decrease code redundancies, and make your application more flexible.

Do you have any tips for handling data in Twig? I'd love to hear them!