• Gutter width @min viewport
• Gutter width @max viewport
• Column width @max viewport
• Number of columns

Combining these four values creates a fluid grid:

Under the visualisation, there’s a CSS generator. On the first iteration, it included the line:

.u-grid {
  grid-template-columns: repeat(var(--grid-columns), 1fr);
}

That might seem reasonable given the user has just asked for X columns. But something didn’t feel at all right about that line.

When I said earlier that those four values created a fluid grid, that wasn’t entirely true. What we’ve created is a fluid container that can be used as a grid with fluid gutters. The columns inform the size of the container. But what you choose to do with that container is entirely up to you. A grid is a complex and nuanced beast that is so context & content dependent, that making assumptions within a tool like this is fruitless.

I’ve always avoided boot-windy grid systems. They’re heavy and designed for the ‘average’ website, never truly catering for the intricacies of your design. They provide all the classes in the world to push/pull columns at whatever breakpoints they deem ‘correct’, but without knowing what lives inside your rectangles, they are ultimately blunt tools.

The 12 column illusion

The grid is a designer’s tool. It assists in getting things to be the right size, and as Lex reminded those at FFConf, in balance. But the 12 column grid itself is an illusion, or at best a fading artefact of the emergent design.

We’ve settled on 12 columns, not because we necessarily need 1-3-7-1 layouts, but because it divides neatly and in multiple ways. It’s flexible. What we’re really looking for is halves, thirds and quarters to be rendered in context of the available space.

It all comes down to: fractions and the spaces between.

Utopia is concerned about the latter, about how your fractions slot together, and whether they feel in harmony with the overarching design. It’s why, by default, our grid calculator visualises gutters, not columns. Get the gutters right, and the rest will follow. Or as Alan Moore quotes:

‘I start with the space between the lines.’

Required further reading

If you’ve got this far, do read the entirety of gridless.design. Donnie D’Amato has done a remarkable job in articulating the flaws in the grid systems we’ve come to accept. Brad Frost has also recently written on the subject, specifically from a design systems' perspective. It’s well worth your time.

James designed the beautiful new component, which acts as a ‘website within a website’. It could’ve been a <video> file. This would’ve been easy to add to the site, but not at all interactive. Alternatively, an <iframe> pointing at a page with the demo, with controls to resize the iframe itself would’ve worked, but with one distinct disadvantage specific to this implementation. This component also needed to provide the homepage <h1>, and putting it in an iframe would’ve removed the content from the page.

So I attacked this as a standalone component on the page. Markup-wise, it was all pretty standard stuff. The interesting bit is in how the type/space scales interact with the form controls and pretend to be rendered on small/large screens.

Most sites are designed at a minimum of ~320px, but this needed to be smaller. So I created a scale on Utopia running from 210px to 686px:

:root {
  --fluid-min-width: 210;
  --fluid-max-width: 686;

  --fluid-screen: 100vw;
  --fluid-bp: calc(
    (var(--fluid-screen) - var(--fluid-min-width) / 16 * 1rem) /
      (var(--fluid-max-width) - var(--fluid-min-width))
  );
}

@media screen and (min-width: 686px) {
  :root {
    --fluid-screen: calc(var(--fluid-max-width) * 1px);
  }
}

Instead of applying those values to the :root element, where the whole website would be affected, I changed the selector to .demo, so it cascades inside this component. Thanks to the CSS Lock Refactor, --fluid-screen is a variable we can control; usually set to 100vw before capping all the type/space units with a single media query.

But for this component, we remove the --fluid-screen: 100vw line, and the whole media query, so we can control it via an <input type="range" />. In Vue, it looks a bit like this:

<template>
  <div class="demo" :style="{
    '--fluid-screen': `${screen}px`
  }">
    ...
    <input type="range" v-model="screen" min="210" max="686" />
  </div>
</template>

<script>
export default {
  data() {
    return {
      screen: 686
    }
  }
}
</script>

<style>
  .demo {
    --fluid-min-width: 210;
    --fluid-max-width: 686;
    --fluid-bp: calc(
      (var(--fluid-screen) - var(--fluid-min-width) / 16 * 1rem) /
        (var(--fluid-max-width) - var(--fluid-min-width))
    );

    --step-0: ...
    /* ... all the type & space units */

    width: var(--fluid-screen);
  }
</style>

Now we can paint on the type/space units onto the markup as we would on any other website. When the user interacts with the input and sets it to somewhere in the middle, say 448, the browser renders the demo as if it was 448px, even if your viewport is 1440px or 320px, and all the space/type reacts accordingly! I love it so much ❤️

If you’d like to read more about this approach, check out my previous blog post on space aware components. This is all stuff that will become trivial when container queries arrive, but for now this works pretty well.

But I now understand that someone else might hear that there’s a native HTML element—like button or select—that comes with built-in behaviours around interaction and accessibility, and think “Uh-oh! What if there unexpected side-effects of these built-in behaviours that might bite me on the ass?

But I wonder if there’s a simpler explanation.

The one common feature between every codebase I’ve encountered on that doesn’t use buttons well, is a bad CSS reset. Developers try to use a button, and find that it still looks like a native browser button, so they grab a plain old, blank canvas div, and build from there.

Adding a good CSS reset to an established codebase is tricky; the side effects of changing very global element styles can be unknown and far-reaching. But if you can get your buttons looking as plain as a div from the start of a project, there’s very little reason not to use the proper element.

I tend to reset my buttons to look like any other text element, then layer on styling with classes. But by having the blank canvas to begin with, you won’t be fighting against yourself when additional button variants come along.

button {
  -webkit-appearance: none;
  border-radius: 0;
  text-align: inherit;
  background: none;
  box-shadow: none;
  padding: 0;
  cursor: pointer;
  border: none;
  color: inherit;
  font: inherit;
}

This decision gave us freedom to pick the most flexible stack for the design system, not forcing our hand to choose an off-the-shelf platform with specific language/framework support. Furthermore, we wanted a system that was beyond a component library; a true design system that could be used to articulate and accommodate brand, content and wider design standards.

Eleventy was the obvious candidate. Generating “pages from data” was the most compelling feature, and add to that the flexibility in templating and the rapid build times, there really was no other stack that came close.

Taking inspiration from Fractal; a project born from design systems projects at Clearleft, I wanted to build this system around component “context”. Context is a fancy word for the data that gets passed to a component to render it, and it allows you to render a component, and any number of variants by providing different data.

Mixed with the encapsulated macro pattern, we can demonstrate these components with ease, and with a consistent interface.

Demo design system

I’ve created a demonstration design system to articulate how this can work in practice. Feel free to fork the repository and tweak to your heart’s content.

Screenshots from the system

How it works

There are three key files in this design system (the links below go to the files in the repository on GitHub):

1. _includes/components/**/*.config.js
2. _data/components.js
3. components-full-pages.njk

Key file 1: _includes/components/**/*.config.js

A config file is what flags each component to the design system. Here’s an example configuration for the quote component rendered in the screenshots above:

module.exports = {
  title: 'Quote',
  context: {
    body: '<p>Maecenas sed diam eget risus varius blandit...</p>',
    citation: 'Trys Mudford, Design Engineer'
  },
  preview: 'wrapper'
}

The title field is used in the sidebar menu. The context object is the data that’s passed into the component at the time of rendering. The preview field references the file that should be used to render the component. Most components are rendered in a full-width wrapper, but it can be useful to pop the component into a more realistically limited-width, or multi-column wrapper.

Now we’ve got this data format, it’s trivial to create variants of it. Here’s the button configuration:

module.exports = {
  title: 'Button',
  context: {
    label: 'Hello',
  },
  variants: [
    {
      title: 'Different label',
      context: {
        label: 'Hello, world'
      }
    },
    {
      title: 'Blue background',
      context: {
        colour: 'blue'
      }
    },
  ]
}

You’ll see the variants field format is a repeat of the parent component, but in an array, with only the differences in data from the parent passed in. In this case, either a different label, or a colour parameter. These pieces of data are then available within the component params variable to adapt to accordingly.

{# button.njk #}
{%- set classNames = "c-button" -%}

{%- if params.colour -%}
  {% set classNames = classNames + " c-button--" + params.colour %}
{% endif -%}

<button type="{{ params.type or 'button' }}" class="{{ classNames }}">
  {{ params.label }}
</button>

Key file 2: _data/components.js

JavaScript files in the _data folder are called at build time by Eleventy, to provide global data to templates. Usually, this would be used for API calls, gathering content before generating the website. But we can perform other asynchronous actions in this space, namely, reading from the file system:

module.exports = async function() {
  // Pull in all the config files
  const modules = await requireGlob('../_includes/**/*.config.js', {
    reducer,
    bustCache: true
  });

  // Convert the components into our required format
  const componentGroups = modules.components
    .map(convertComponent)
    .filter(Boolean);
  
  // Return the components and the menu
  return {
    components: componentGroups.flat(),
    menu: prepareMenu(componentGroups)
  };
}

The function convertComponent moulds the data from *.config.js into a usable format:

function convertComponent(component) {
  // Extract variants from component and remove them
  let { variants = [] } = component;
  delete component.variants;

  // Back out if the component isn't valid
  if (!component || !component.title) return null;

  // Set sensible defaults for previews & slugs
  component.preview = component.preview || 'default';
  const parentSlug = component.slug || slugify(component.title.toLowerCase());
  
  // Loop the variants, returning a merged combo of component, then variant
  variants = variants.map(variant => {
    const variantSlug = slugify(variant.title.toLowerCase());
    const preview = !!variant.preview ? variant.preview || 'default' : component.preview || 'default';

    return {
      ...component,
      ...variant,
      context: {
        ...component.context,
        ...variant.context
      },
      variant: true,
      preview,
      originalTitle: variant.title,
      title: `${component.title} - ${variant.title}`,
      slug: `${parentSlug}-${variantSlug}`
    }
  });
    
  // Return the main component and any variants
  return [
    {
      slug: parentSlug,
      ...component,
    },
    ...variants
  ]
}

So what we’ve done here is gather up all the config files, and serve them as one massive global array for Eleventy to work with.

Key file 3: components-full-pages.njk

This ingenious little template from Eleventy loops around the data we’ve exposed in components.components (sorry, poor choice of variable naming there), and creates a page for every component and variant! It renders the component using the {{ c() }} macro, passing in the context, and it pops it within a preview wrapper.

---
pagination:
    data: components.components
    size: 1
    alias: component
permalink: "components/full/{{ component.slug }}/"
title: 'Components'
renderData:
  title: "{{ component.title }}"
---

{% extends "layout.njk" %}

{% block inner %}
  {% set comp %}
    {{ c(component.name, component.context) }}
  {% endset %}
  {% include "design-system/previews/preview-" + component.preview + ".njk" %}
{% endblock %}

And that’s it! Here’s what it looks like:

Designing the design system

Hang on; you might be thinking, that looks pretty different to the earlier screenshots? Well yes, but that’s for good reason. See, instead of rendering the component directly within a page in the design system, we render it on its own, and then include it via an <iframe>. This renders the component at the window size of the iframe, not at the size of the whole page. It’s a subtle difference, but when you’re working with viewport units or fluid type & space, it’s an important distinction.

The solution is another -pages.njk file. It starts off in the same way as the previous template, reading in the components.components data and rendering a page for each component/variant. For each page, we then output some tabs for the various views we want for the component.

{# components-pages.njk #}
---
pagination:
    data: components.components
    size: 1
    alias: component
permalink: "components/{{ component.slug }}/"
title: "Components"
sidebar: components
renderData:
  title: "{{ component.title }}"
---

{% extends "./_includes/design-system/library.njk" %}

{% from "design-system/component.njk" import code, context %}

{% block content %}
  <seven-minute-tabs class="ds-stretch">
    <ol role="tablist" class="ds-tabs" aria-label="What does this tab chooser do?">
      <li><a class="ds-link" href="#example-tab" role="tab">Demo</a></li>
      <li><a class="ds-link" href="#code-tab" role="tab">.html</a></li>
      <li><a class="ds-link" href="#context-tab" role="tab">.njk & context</a></li>
      <li><a class="ds-link" href="/components/full/{{ component.slug }}">Full Screen ↗</a></li>
    </ol>

    <div id="example-tab" role="tabpanel" class="ds-stretch">
      <div class="ds-frame ds-stretch">
        <iframe class="ds-stretch" src="/components/full/{{ component.slug }}" sandbox="allow-same-origin allow-scripts allow-forms allow-modals" style="" marginwidth="0" marginheight="0" frameborder="0" vspace="0" hspace="0" scrolling="yes"></iframe>
      </div>
    </div>

    <div id="code-tab" role="tabpanel" class="ds-code ds-stretch">
      {{ code(component.name, component.context) }}
    </div>

    <div id="context-tab" role="tabpanel" class="ds-code ds-stretch">
      {{ context(component.name, component.context) }}
    </div>
  </seven-minute-tabs>
{% endblock %}

In this case, I’ve got a tab for the visual demo of the component (housing the aforementioned <iframe>), a view of the generated HTML, a print-out of the context in use for the variant, and an option to see the component full screen. But this is only the start, we can render markdown documentation, prop tables, version numbers, stability labels, links to Figma, or whatever else takes your fancy.

The beauty of the *.config.js format, is you can pop in whatever data you fancy, and it’ll be available in this template. If your team has other requirements, you can easily adapt!

Styling the system

The final part of this example is a sprinkling of CSS to give the design system some form, and a sidebar to render the list of components, and any other associated pages of documentation. In the past, I’ve written about the systemised foundations, how to release the design system on NPM, and the decisions behind the CSS methodology, along with brand guidelines, tone of voice guides and anything else required to make this the home of digital design within a company.

You can get really meta, and use the components within the design system, to design the design system! If you’ve already designed buttons & tabs for your website, why generate another load of them for the system, right?!

If you have any questions on how this all works, or if you’d be interested in how I’d extend the system further, please pop me a tweet.

James and I were invited to speak at UX Ghent for their frontend themed evening. We spoke about the origins of Utopia, and how you can begin to use it in your projects.