Eleventy Style Guide Generator with WebC Component Support

Published

Last Updated

6 min reading time


Posted in How-to, Web Dev

Tags : CSS, Design System, Eleventy (11ty), JavaScript, Style Guide, WebC

TL;DRanchor

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, here’s the demo site it generates, and an intro video from the September Eleventy meetup.

For more detail about how to add it to your own Eleventy site, check out the Step by Step guide adding to an existing site follow up post.

Impetusanchor

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 Tokensanchor

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

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 Definitionanchor

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:

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 Variablesanchor

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 Tokensanchor

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.

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.
Some overlapping screenshots of the tokens style guide page to illustrate how it itemizes the tokens visually

Style Guide Generatoranchor

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

Foundationanchor

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 Supportanchor

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 Conventionsanchor

Standalone Documentation Pagesanchor

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 Methodologyanchor

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 Exampleanchor

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 Futureanchor

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.

Resourcesanchor

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

Getting Started with WebCanchor

Need help with an upcoming project?

I'd love to hear more about what you have coming up and how I can help bring it to life! My earliest availability is currently Q1 2025.

Get in Touch