Eleventy Style Guide Generator with WebC Component Support
Tags: eleventy, designsystem, webcomponents
Published: 2023-08-04 10:20:54

---
title: Eleventy Style Guide Generator with WebC Component Support
published: true
date: 2023-08-04 10:20:17 UTC
tags: eleventy, designsystem, webcomponents
canonical_url: https://stevenwoodson.com/blog/eleventy-style-guide-generator-with-webc-component-support
---

 ![](https://content.walnutcreekcreative.com/stevewoodson/wp-content/uploads/sites/3/2023/08/Eleventy-Style-Guide-Generator-with-WebC-Components.png)
## TL;DR

I created an Eleventy style guide generator, features include:

- Automatically itemized JSON-formatted **design tokens** like colors, fonts, and fluid scale and sizing.
- Automatically itemized **components and their variations** based on a simple configuration file format
- Eleventy **[WebC Component](https://www.11ty.dev/docs/languages/webc/) support** and examples
- Supports **standalone documentation pages** , perfect for displaying foundational HTML elements and explaining design system details in a more curated way.

[Source is on GitHub](https://github.com/stevenwoodson/11ty-design-system) and [here’s the demo site](https://stevenwoodson.github.io/11ty-design-system/) it generates.

## Impetus

I recently had the opportunity to create a new fairly simple Eleventy site and found myself wanting to also document some of the visual language and components therein.

I didn’t want to go overboard and install something like Storybook for this because – while I love Storybook – it can be _a lot_ and this site definitely didn’t need all that.

So, in true developer fashion, rather than manually create a few static style guide pages and move on, I decided to make a design system generator!

I love the **simplicity and speed of 11ty** , and I love the organization of a good **self documenting design system** , so I combined the excellent work of several really smart people to pull these two together in a way that acts as a pretty nice starting point for a fluid, responsive, and blazing fast 11ty powered website.

Read on if you’re interested in the pieces that make up the whole, including the inspiration behind them.

## Design Tokens

What better place to start than the at the smallest building blocks of a design system, right?

<aside>
<p>Need a quick intro to design tokens and how they relate to design systems? <a href="https://www.smashingmagazine.com/2019/11/smashing-podcast-episode-3/" rel="nofollow">Check out this “What Are Design Tokens?” Smashing Magazine podcast episode with Jina Anne</a>.</p>
</aside>

Design tokens are vital to the overall look and feel and are (ideally) used everywhere to promote consistency with spacing, fonts, colors, etc.

All tokens are stored in the `/src/_data/designTokens/` directory, I did this purposefully because having the JSON in the Eleventy Data folder gives me these values to manipulate and use for free. Making the visual itemizing noted below really simple.

### Token Definition

Here’s the structure I used for the token files themselves, they all came with a title, description, and an array of items. I also optionally added a meta object to store additional info, for example the sizes and spacing ones link to the Utopia calculator where it was generated.

```
{
  "title": "Name for these Tokens",
  "description": "Longform description of what these tokens define.",
  "meta": {},
  "items": []
}
```

I used the excellent tools James and Trys created called [Utopia](https://utopia.fyi/) for the sizes and spacing tokens. Here’s the breakdown:

- The [Type Calculator](https://utopia.fyi/type/calculator) defines the [sizes.json](https://github.com/stevenwoodson/11ty-design-system/blob/main/src/_data/designTokens/sizes.json) tokens
- The [Space Calculator](https://utopia.fyi/space/calculator) defines the [spacing.json](https://github.com/stevenwoodson/11ty-design-system/blob/main/src/_data/designTokens/spacing.json) tokens

I also added a [colors.json](https://github.com/stevenwoodson/11ty-design-system/blob/main/src/_data/designTokens/colors.json) and [fonts.json](https://github.com/stevenwoodson/11ty-design-system/blob/main/src/_data/designTokens/fonts.json) token JSON file to itemize those for consistency as well.

I now have a solid foundation for fluid typography and spacing, and consistent fonts and colors, so the applications I build will look wonderful regardless of the available space and will be consistent from page to page with minimal effort.

### Converting to CSS Variables

Now that I have my tokens beautifully organized, I also needed a way to convert them into usable CSS variables.

There are some great well established tools out there that do this, such as [Theo](https://github.com/salesforce-ux/theo) and [Style Dictionary](https://amzn.github.io/style-dictionary/#/) but for this I turned to the sage advice of Andy Bell via [buildexcellentwebsit.es](https://buildexcellentwebsit.es/) and used Tailwind to run through the token JSON files and generate the CSS variables I can use in my styling.

I went this route because it seemed to fit how I like to organize things, already had concepts inherent to Utopia (including `clamp`), and was already working in an Eleventy site.

These are defined in the [/\_utilities/css-utils](https://github.com/stevenwoodson/11ty-design-system/tree/main/src/_utilities/css-utils) folder and used in the [tailwind.config.js](https://github.com/stevenwoodson/11ty-design-system/blob/main/tailwind.config.js) configuration.

Here’s a truncated example of what it generates:

```
:root {
    --color-bg: #fff;
    --color-bg-alt: #fffaeb;
    ...
    --space-2xs: clamp(0.5rem,0.46rem + 0.19vw,0.625rem);
    --space-xs: clamp(0.75rem,0.69rem + 0.29vw,0.9375rem);
    ...
    --space-xs-s: clamp(0.75rem,0.59rem + 0.78vw,1.25rem);
    --space-s-m: clamp(1rem,0.53rem + 2.33vw,2.5rem);
    ...
    --size-step-n2: clamp(0.6875rem,0.65rem + 0.19vw,0.8125rem);
    ...
    --font-base: Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif;
    --font-serif: Georgia,sans-serif;
    --font-code: Lucida Console,Monaco,monospace;
}
```

### Visually Itemizing the Tokens

Being so vitally important to a successful product, I wanted a seamless and automated way to itemize these tokens for easy visual reference.

I’m still shocked at how easy this part ended up being once I decided to store the design tokens in the Eleventy data directory.

Because that data was automatically surfaced to page templates, all I needed to do here was to create an 11ty Nunjucks-based page that loops through the design token values and applies the tokens to some placeholder elements. You can see how this comes together at [/src/design-system/Atoms/tokens.njk](https://github.com/stevenwoodson/11ty-design-system/blob/main/src/design-system/Atoms/tokens.njk) and a screenshot of it in action below.

[![Three screenshots of the same page horizontally overlapping to illustrate some of the page contents more easily. You can go to this page using the link on this image.](https://content.walnutcreekcreative.com/stevewoodson/wp-content/uploads/sites/3/2023/08/Screen-Shot-2023-08-03-at-11.47.09-AM-1024x456.png)](https://stevenwoodson.github.io/11ty-design-system/design-system/Atoms/tokens/)
_Some overlapping screenshots of the tokens style guide page to illustrate how it itemizes the tokens visually_

## Style Guide Generator

With design tokens defined, accessible via CSS, and visually itemized in a page. I thought “wouldn’t it be great to have individual components automatically itemized in a similar way?”.

### Foundation

After some searching for existing solutions I found [this Eleventy Design System gem](https://github.com/trys/eleventy-design-system/) by Trys Mudford. It’s truly a wonderful foundation for exactly what I was hoping to achieve with this project.

While integrating that into what I was building, I noticed a few things that I wanted to expand upon to make it more versatile. Here’s the highlights of what I added:

- Moved to a subfolder so it can be in the same codebase as the rest of the site
- Ability to define components in subfolders of the `_includes/components` directory
- WebC components support and examples

### WebC Support

It just so happened that I was reading more about [WebC](https://www.11ty.dev/docs/languages/webc/) while iterating on this idea. WebC is a new 11ty file extension that brings first-class components to Eleventy. An obvious addition to a style guide generator that itemizes components!

I will caution that WebC is still fairly new, there’s some things that work great with other file extensions that just don’t yet for WebC. I’ve itemized some of these [as TODO items in the readme](https://github.com/stevenwoodson/11ty-design-system/tree/main#todo).

To see some WebC component examples, check out the [Sidebar](https://github.com/stevenwoodson/11ty-design-system/tree/main/src/_includes/components/_Compositions/sidebar) and [Stack](https://github.com/stevenwoodson/11ty-design-system/tree/main/src/_includes/components/_Compositions/stack) composition components courtesy of [Every Layout](https://every-layout.dev/), and the [Card](https://github.com/stevenwoodson/11ty-design-system/tree/main/src/_includes/components/card) component utilizing some style inspiration from [SmolCSS](https://smolcss.dev/).

## Other Conventions

### Standalone Documentation Pages

Rather than having to create a “component” for foundational HTML elements and long form documentation within the style guide, I’ve built it so that you can define standard pages in the style guide as you would any other page.

It will automatically merge these static pages with the generated ones for components too!

For some examples of static pages, check out the [src/design-system/Atoms](https://github.com/stevenwoodson/11ty-design-system/tree/main/src/design-system/Atoms) folder. That’s where I’ve added block, form, inline, and preformatted HTML tags to quickly be able to preview how changes to the design tokens and styles affect these critical native tags.

### Styling Methodology

I’ve quickly become a big fan of [CubeCSS](https://cube.fyi/) and have tried to adhere to those guidelines as best I can here. If you haven’t read about it yet I highly recommend you check that site out and give it a try.

Admittedly, in some cases it gets a little weird but I have my reasons! For example, I have web component styles sitting in the same folder as the web component itself ([Sidebar](https://github.com/stevenwoodson/11ty-design-system/tree/main/src/_includes/components/_Compositions/sidebar) for example) and I have others ([Card](https://github.com/stevenwoodson/11ty-design-system/tree/main/src/_includes/components/card) for example) that have styles in the assets folder ([card.css](https://github.com/stevenwoodson/11ty-design-system/blob/main/src/assets/css/blocks/card.css) in this case) instead.

I did this because I wanted to adhere to the [HTML-only Components](https://www.11ty.dev/docs/languages/webc/#html-only-components) rule where it renders native HTML and ignores the host component tag. Adding and referencing the styles in the component definition would have turned the Card example into a true web component instead.

## Live Site Example

I’ve actually been sitting on this for a little while, before releasing something for general use I wanted to make sure to put it through a real site build process first. Happy to share the first such site has just been pushed live for the best (and most patient) client a guy could ask for – my dad!

His site at [dannywoodson.org](https://dannywoodson.org/) and [the style guide for it is here](https://dannywoodson.org/design-system/).

Pretty neat to be able to compare the demo site with this live site and see the similarities, but also the differences!

## Plans for the Future

I think there’s a lot of potential here, a couple of the bigger things I’d love to do with this are:

- Continue to add foundational web components that can be reused across any kind of tech stack. Im considering adding some more baseline WebC components to this project as well, especially those found in [Tugboat](https://github.com/11ty/tugboat/tree/main/_components).
- I’d ideally like this to be an Eleventy plugin that can be installed on an Eleventy site, rather than a full Eleventy site in itself. As far as I can tell there’s not a way to do so until [Virtual Templates](https://github.com/11ty/eleventy/issues/1612) are made available.

Have any ideas? Are you going to give it a try?

I’d love to hear from you, reach out on the socials or start up [an issue on GitHub](https://github.com/stevenwoodson/11ty-design-system/issues/new).

## Resources

### Design Systems, Fluid Typography, Styling Methodologies oh my!

- Fluid type, space, and grid calculations via [Utopia](https://utopia.fyi/)
- CSS methodology based on [Cube CSS](https://cube.fyi/)
- [Eleventy Design System](https://github.com/trys/eleventy-design-system/) by Trys Mudford & the companion explanatory [blog post](https://www.trysmudford.com/blog/eleventy-design-system/).
- Some of the base components and styles are based on [SmolCSS](https://smolcss.dev/) and [Every Layout](https://every-layout.dev/)

### Getting Started with WebC

- Eleventy [WebC Components](https://www.11ty.dev/docs/languages/webc/) main documentation
- [Crash Course in Eleventy’s new WebC Plugin](https://www.youtube.com/watch?v=X-Bpjrkz-V8) video
- [Interactive Progressively-enhanced Web Components with WebC](https://www.youtube.com/watch?v=p0wDUK0Z5Nw) video
- [Introduction to WebC](https://11ty.rocks/posts/introduction-webc/) & [Understanding WebC Features and Concepts](https://11ty.rocks/posts/understanding-webc-features-and-concepts/) from 11ty Rocks
- [11ty & WebC](https://11ty.webc.fun/) by W. Evan Sheehan