Back in the old days of the internet, Brad Frost wrote an article, “Atomic Web Design,” in which he gives name to the concept of building webpages from reusable elements. Since then, design systems that start by defining base elements and successively add complexity have become ubiquitous.
I built this site by following the “atomic” philosophy. Recently, though, I’ve found it tricky to make minor updates. My site uses Nunjucks and Less — and I’d built in extensibility in my components so they could be used in any context. However, my hygiene standards slipped with successive updates, resulting in some components tightly coupled to their context. Worse still, I couldn’t remember how to use the various options I’d built into my Nunjucks Macros.
This site desperately needed a spring clean.
My solution: Write stuff down
Documenting stuff is a critical design skill. In my day job, I do this all the freaking time. 90% of what I do is communicating to others. But I’ve never done this with my website.
So, I created documentation for my patterns and components, which I’m nominally calling a design system, named “Kanga” for (hopefully) obvious reasons.
Documenting the building blocks that form this site also allowed me to rationalise my components.
Checkout my design system: Kanga
Building a design system with Nunjcuks and Eleventy
I use Nunjucks as the templating language on this site. There are, of course, other options, but I find template inheritance and macro functionality lend themselves to “atomic” design structures.
Similarly, Nunjucks encourages layouts and includes (aka components) to spit code into separate concerns.
The GOV.UK Design System inspired me when deciding how to document my system’s elements. I like their use of standalone examples. Following this pattern forced me to ensure all my components are context agnostic.
I build a component to show standalone examples in an iframe. The component also extracts the code if it’s one of the supported filetypes (currently Nunjucks and Markdown), strips out any frontmatter and renders it in a details element.