Eleventy Style Guide Generator with WebC Component Support

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 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 and here’s the demo site 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?

Need a quick intro to design tokens and how they relate to design systems? Check out this “What Are Design Tokens?” Smashing Magazine podcast episode with Jina Anne.

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 for the sizes and spacing tokens. Here’s the breakdown:

• The Type Calculator defines the sizes.json tokens
• The Space Calculator defines the spacing.json tokens

I also added a colors.json and 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 and Style Dictionary but for this I turned to the sage advice of Andy Bell via 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 folder and used in the 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 and a screenshot of it in action below.

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 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 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.

To see some WebC component examples, check out the Sidebar and Stack composition components courtesy of Every Layout, and the Card component utilizing some style inspiration from SmolCSS.

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 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 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 for example) and I have others (Card for example) that have styles in the assets folder (card.css in this case) instead.

I did this because I wanted to adhere to the 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 and the style guide for it is here.

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.
• 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 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.

Resources

Design Systems, Fluid Typography, Styling Methodologies oh my!

• Fluid type, space, and grid calculations via Utopia
• CSS methodology based on Cube CSS
• Eleventy Design System by Trys Mudford & the companion explanatory blog post.
• Some of the base components and styles are based on SmolCSS and Every Layout

Getting Started with WebC

• Eleventy WebC Components main documentation
• Crash Course in Eleventy’s new WebC Plugin video
• Interactive Progressively-enhanced Web Components with WebC video
• Introduction to WebC & Understanding WebC Features and Concepts from 11ty Rocks
• 11ty & WebC by W. Evan Sheehan