Eleventy Style Guide Generator – Step by Step guide adding to an existing site

I shared the Eleventy Style Guide Generator (source is on GitHub, here’s the demo site it generates, and an intro video from the September Eleventy meetup) a few weeks ago. Because it’s a full Eleventy repo and not a plugin (can’t be until Virtual Templates are supported), I received a few questions about its requirements including:

• Are design tokens required?
• Is the use of WebC required?
• Can I use a CSS preprocessor like SCSS?
• How do I add this to an existing Eleventy site?

This post attempts to answer these questions, I’ll also be updating the repo with more of these details as well.

Are design tokens required?#anchor

No, you don’t need design tokens to use this generator.

If you decide not to use design tokens you can also remove some of the additional dependencies and files including:

• the Tailwind dependency & configuration file at `tailwind.config.js. All it’s doing is converting the JSON sourced design tokens into usable CSS custom properties.
• the two CSS utilities at src/_utilities/css-utils. Similarly, they’re only being used by the Tailwind configuration to generate the custom properties.
• the tokens static design system page at src/design-system/Atoms/tokens.njk. It’s only there to itemize the individual design tokens.

Is the use of WebC required?#anchor

Not technically, but it’s highly encouraged.

WebC brings first-class components to Eleventy, this being a way to itemize components in a style guide it stands to reason that the two are well suited as a pair.

If you choose not to use WebC, or need to ease into supporting it in your existing project, here’s a few considerations.

Naming Collisions#anchor

The generator is assuming that each component under src/_includes/components has a .webc component and an .njk example defined. If your components are also going to be in Nunjucks you’ll need another qualifier added to example files so you can programmatically tell them apart.

Something like .stories.njk (like Storybook) would work fine. Then you’d update src/design-system/components-pages.njk to include that extra qualifier, for example like this

{%- macro c(path, name, params) -%}
  {% include "components/" + path + "/" + name + ".stories.njk" ignore missing %}
{%- endmacro -%}

Layouts#anchor

There are also two WebC layouts that are being used to generate the style guide files at src/_includes/layouts/ds-static.webc and src/_includes/layouts/ds-wrapper.webc.

You could enable WebC just for new pages and templates like these, but it should be fairly straightforward to convert into another template language if you don’t want to enable WebC at all.

Existing components#anchor

There are a handful of components defined in the repo and they’re all WebC based components, so you won’t (easily) be able to make use of them.

You could convert them to another template language but that effort may not be worthwhile depending on your needs.

Can I use a CSS preprocessor like SCSS?#anchor

Sure, you can still use a preprocessor like LESS, SCSS, or Stylus if that fits better in your workflow.

I had decided on using only CSS to reduce the number of dependencies required, that’s all.

How do I add this to an existing Eleventy site?#anchor

I jotting down what I’ve needed to do to add this to my own site, and listed it all here.

This including everything that I had noted above as optional, so I’ve split it up into sections so you can skip the bits you don’t want.

File path references directly relate to the paths in the 11ty-design-system repo starting with src

Essentials Setup#anchor

First, you need to determine where you want the style guide to live, in the repo I’ve set this as /design-system but you can place it anywhere that makes sense for your project.

Copy the following pages to this new folder#anchor

• src/design-system/components-pages.njk – generates the style guide page for each component, with tabs for Demo, HTML, and Context. Loads the demo as an iframe of…
• src/design-system/components-full-pages.njk – this is the isolated component in a blank page. Iframed into the component page above.
  • This is relying on a “base” layout too, if yours is in a different location you’ll need to update layout: layouts/base.webc as well.
• src/design-system/index.md – The style guide homepage, feel free to replace the content here (and even change the template language).
• src/design-system/Atoms – This folder contains files that itemize the design system tokens and most major native HTML elements

Copy the following to your layouts directory#anchor

• src/_includes/layouts/ds-wrapper.webc – The layout of the design system pages, including the sidebar menu.
  • This is relying on a “base” layout too, if yours is in a different location you’ll need to update layout: layouts/base.webc as well.
• src/_includes/layouts/ds-static.webc – The layout for any static content pages you add in addition to the auto-generated ones.

Copy the following into your .eleventy.js config#anchor

/* Shortcodes */
config.addPairedShortcode('brace', function (content, type = 'curly') {
  const [opening, closing] = {
    curly: ['{{', '}}'],
    silent: ['{%-', '-%}']
  }[type];
  return `${opening}${content}${closing}`;
});

config.addPairedShortcode('prettify', (content) => {
  return prettify(content);
});

/* Filters */
config.addFilter('console', function (value) {
  return JSON.stringify(value, null, 2);
});

/* Custom Collections */
// Filter source file names using a glob
config.addCollection('dsAtoms', function (collectionApi) {
  return collectionApi.getFilteredByGlob('**/design-system/Atoms/**/*');
});

Descriptions in the same order as the code above:

• Brace & Prettify shortcodes, for help displaying content in the Code and Context tab panels
• console filter for stringifying the JSON configuration in the Context tab
• dsAtoms custom collection so we can also add the static pages under the Atoms directory to the style guide menu

Copy the foundational CSS & JS#anchor

• src/assets/css/design-system.css – helps with setting up design system specific styles like color swatches. Everything is prefixed with ds- to avoid CSS collisions.
• src/assets/js/vendor/seven-minute-tabs.js – Powers the Demo, HTML, and Context tab structure for the component style guide pages

Copy the following data files#anchor

• src/_data/components.js – generates all the components as a collection, be sure to update the folder paths here too if they’re different in your setup.
• src/_data/global.js – defines the random function used in some templates to cache bust the CSS.
  • If you have a cache busting filter in place you can skip this one and update references to global.random() with that instead.

With these steps I had a functional style guide being generated. You can see my progress at https://stevenwoodson.com/design-system/.

Adding Design Tokens#anchor

Here’s what you need to copy to get design tokens set up:

• tailwind.config.js – This is what powers the generation of all the CSS custom properties
• postcss.config.js – PostCSS triggers the tailwind configuration, it also minifies the CSS
• Build step for the above in your package.json, "css": "npx postcss src/assets/css/*.css --base src --dir dist", for example
• src/_data/designTokens – This is where all the design token JSON files are stored, they’re in the data directory to make it easier to parse that data with Eleventy’s automated data cascade
• src/_utilities/css-utils – Utility classes that the tailwind config needs in order to generate the custom properties and the clamp values that many of them need

The act of utilizing the design tokens is likely another post entirely, but the TL;DR of it is that you’re going to need to comb through your CSS and replace color, spacing, and other tokenized values with those coming from this generator.

Adding WebC Support & Components#anchor

Adding WebC support#anchor

• You’re going to need Eleventy 2.0.0 or newer to be able to utilize WebC. I was on an older 1.x version and was surprised at how easy the upgrade process was. Hoping you have similar luck if you need to upgrade as well.
• Follow the install steps from the official WebC docs, currently it’s not bundled with core so you’ll need to perform an NPM install and add the plugin to your config.

WebC Component Structure#anchor

All components are to be stored under src/_includes/components. One component per folder is the ideal and you can nest folders down to three levels currently.

Here’s the structure of a typical component folder, using the Sidebar component as an example:

• sidebar-l.webc WebC component file – This is where the component itself is defined, in this case the WebC component is a wrapper for a pre-defined true web component so it only loads the CSS and JS.
• sidebar.config.js Configuration file – Defines the component name and any additional context needed to demonstrate what the component can do.
• Sidebar.css Web Component – it’s not required to store component styles here rather than with the rest of the site styles but can be a nice way to keep everything together in one place.
• Sidebar.js Web Component JavaScript – This is where the Web Component is initialized using standard HTMLElement and customElements syntax.
• sidebar.njk style guide example – The Nunjucks template file is where we demonstrate the component with example content.

Check out the Card component for an example of a simpler HTML-only component. This one contains a .webc component, a config, and a Nunjucks template for rendering the examples.

Send me your feedback!#anchor

Did you add this Eleventy Style Guide Generator to your site? I’d love to hear about it! If you’re willing to share your process adding it as well, that could inform future updates and documentation to make it easier for the next person. So please do reach out!