cloudfour/eleventy-patterns

(WIP) A boilerplate template used to quickly generate pattern libraries and prototyping environments

Eleventy Patterns

(WIP) A pattern library and prototyping environment, built with Eleventy and Gulp. It uses Handlebars for templating, Sass for CSS processing, and Rollup for javascript transpilation and bundling.

You're not meant to include this as a module. Instead, use this as a template repository and then tweak it to fit your needs. This makes it easier to directly edit the configuration without this project acting as a middleman between you and your config files.

This project includes some custom CLI commands to help you quickly iterate and scaffold out new patterns and prototypes.

Getting Started

Once you've copied this project, run the following commands to get up and running:

Installation

1. npm ci — Install necessary dependencies.
2. npm start — Compile the project, start a server, and watch for updates.
3. Review the pattern and prototype examples to get a feel for the site structure and scaffolding.
4. npm run removeExamples — Delete the example pattern and prototype. Use caution if you've made changes of your own! This will remove and modify files.
5. npm run new prototype — Create your first prototype! This command will scaffold out all the files necessary for a new prototype
6. npm run new pattern — Create your first pattern! This command will scaffold out all the files necessary for a new pattern

eleventy-patterns's Issues

Support for more helper types

I tried adding some helpers and I was a little confused initially.

We currently have everything in helpers/filter, but all of these are added using eleventyConfig.addHandlebarsHelper. I didn't expect this to be the case!

This makes it difficult to add universal filters and shortcodes. It'd be really cool to be able to add those sorts of things with some prototyping tools baked in that would work regardless of the project's template engine.

Ideally, this directory would be separated based on all the helpers Eleventy supports, so you could do something like this:

helpers
├── filters
├── handlebars-helpers
├── liquid-tags
└── shortcodes

Create a demo repo of how to consume this pattern library

The pattern library should be consumable via NPM. Scott wrote an article about how to do this. (Thanks @spaceninja !)

It would be great if we could set up a demo of how to do this for a couple reasons:

1. Work out any kinks or bugs in that process. (@tylersticka pointed out #17 )
2. Show future users how this works with a demo.

Transition away from Handlebars for style guide templates?

We've discussed adding support for other templating languages for patterns (#22), but this issue is specifically about what we're using for this project's layouts, templates, etc.

I've noticed over the course of some recent projects and making modifications to this one that Handlebars has a number of shortcomings:

• It doesn't support async helpers or functions. More and more libraries are writing asynchronous features by default these days, so that limits what helpers we can expose to the style guide.
• It doesn't support relative paths in includes.
• It doesn't have a unique filter syntax, resulting in messy {{nested (shortcodes (of (doom)))}}
• It doesn't support conditionals that are more complex than truthy/falsy checks.
• Its loop syntax can be confusing since it assigns the current value to . or @this (whereas most other template engines cast the current element to a property name like JavaScript does).
• While it supports extensible blocks in partials (@gerardo-rodriguez wrote a great article on this), its syntax for doing so is not very discoverable.
• It is not fully supported in certain Eleventy Frontmatter properties (such as pagination).

Looking at Eleventy's built-in template languages, I can't help but gaze enviously at the list of supported Nunjucks features… 👀

Especially interested in @Paul-Hebert's opinion as the originator of this repo!

Bump Eleventy Version

To this new release: https://github.com/11ty/eleventy/releases/tag/v0.10.0

Add offline/PWA support

It would be nice for pattern libraries to work as PWAs if someone's offline or on a plane. This would be a nice enhancement, though it's likely low priority.

Enforce at least some code style

I don't know which styles are too opinionated for a project boilerplate, but I'd love to at least have enforcement of tabs and stuff via editorconfig if possible?

But I'd also be open to eslint and stylelint configs.

reset.scss leaks EP-specific styles to the rest of the pattern library

When building out the Eleventy Patterns scaffolding I wanted some basic reset styles:

* {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

I added these in reset.scss but since they target * the styles can end up affecting pattern examples. We'll need to rethink our approach here so that styles written for the scaffolding don't impact the end user's patterns

(Either that or we decide some resets are necessary and put up a disclaimer about it)

Organize `package.json` dependencies

Currently it appears that all dependencies are being installed as devDependencies. This may make consumption of patterns from this repository difficult, as detailed in @spaceninja's article:

Anything required for your build to succeed should be listed as a dependency. Anything that’s not (such as linting) can be a devDependency.

Enforce linting rules on commits with Husky or Github actions

The project has linting, but it would be nice to enforce this when users try to commit or push.

@calebeby recommended using a Github action over Husky:

Husky bugs me because it really slows down when I want to commit. On decathlon when we were using husky it often took 8-10 seconds to run the checks when I was trying to commit. We switched to GitHub Actions. Then the checks can run concurrently with PR review, and they enforce that everything works even with the latest dependencies. Also it is nice to be able to commit WIP work even if linting is failing

Improve style guide UI

We've discussed some improvements to the UI theme and @dromo77 did some explorations. I'd love to see this thinking continued so this can evolve from a user/reader perspective in the same way that it's evolved from a dev/maintainer perspective.

Add inline SVG helper/shortcode

It would be great to have an easy way to inline SVGs in templates. @tylersticka , I know you've been working on a module to handle this. When that's ready to go I'd love to add that here.

Code sample indentation is off

This is a common problem in our projects:

Add `icons` folder and helper/shortcode

Once #34 is done it would be awesome to scaffold out support for an icons folder. You could then drop SVGs into this folder and a few things could happen:

1. They would display on a new Icons page in the pattern library
2. They could be easily embedded as a short code.

Add standardized breakpoints

Recent changes use a common breakpoint to style elements at specific screen size. However, this breakpoint isn't documented anywhere. It would be great to create standardized breakpoints using either custom properties or Sass variables.

Re-organize and scrutinize helpers

The current set of Handlebars helpers needs some re-organization and cleanup since resolving #4. Some examples:

• consoleLog is probably not necessary since {{ log }} exists
• markdown uses a different Markdown library than Eleventy, resulting in potential inconsistencies between the output of Markdown depending on where it is compiled.
• Most (possibly all) of the helpers would work as universal filters or shortcodes in Eleventy, which would make them easier to use in more projects.

Simplify/unify "new" tasks

The npx gulp newPrototype and npx gulp newPattern tasks are awesome!

I wonder if it would be possible to simplify that syntax at all to make them a little easier to remember?

This may not be possible/feasible, but in a perfect world...

• npm run new: Asks what new thing you want to make.
• npm run new pattern
• npm run new prototype

Just a thought, happy for others to disagree!

Add sizing

The project would benefit from some standardized sizing so that spacing can be applied more uniformly as we continue to improve the UI. We may want to use a modular scale for this.

Placeholder data or helpers

In our Handlebars helpers, there are two helpers we've used for FPO or dummy content:

• dummyImgSrc
• random (but Eleventy warns that this is a performance hog)

We've also used other techniques for this:

• A file with typographic samples
• Various image placeholder services

It'd be neat to ship this boilerplate with some sort of FPO content strategy for rapid prototyping. That might be as simple as a placeholder.json data file with headings and paragraphs in it, or maybe there's an alternative approach to our previous helpers that could provide some universal capabilities like that.

Add Skip Link

The navigation can become very long in pattern libraries. We should add "Skip to Content" links for screen reader and keyboard users.

Multiple code previews

It would be great to be able to view multiple code samples where appropriate.

Some use cases:

• The pattern is shared on the server and may be included via simplified template code (rather than plain HTML).
• The pattern is a JavaScript component or has accompanying JavaScript.
• The pattern depends on a complex data structure best represented via an accompanying bit of sample JSON.

Fine-tune rollup configuration

I quickly set up rollup for JS transpilation but our config should likely be fine tuned.

Are we abusing Eleventy's "Layouts"

We're using Eleventy layouts to keep our code DRY, but we're using them for things that feel more like partials than layouts in some cases. Should we refactor this to be clearer?

Add PostCSS to CSS stack

In my Feeling Sassy Again article, I mentioned how I thought that Sass was best for proprietary/compiled features while PostCSS was best at browser compatibility and automated/robot stuff.

I think in my ideal world, the CSS stack for this would be something like this...

• We include a browserslist file.
• PostCSS is configured to run Preset Env and Autoprefixer, both of which will change their behavior based on browserslist.
• Files ending in .css are processed by just PostCSS.
• Files ending in .scss are processed by Sass, then by PostCSS.

This will give us:

• The ability to automatically polyfill CSS features based on a project's target browsers.
• The ability to opt in to proprietary Sass stuff when we want to, ignore it if/when we don't need it.

That said, the latter point isn't super important to me. If supporting Sass-less compilation means that importing gets confusing, then that may not be a reasonable trade-off.

Project data

It'd be neat to have a boilerplate src/_data/project.json file (or similar). Maybe it extends the package.json info (or provides access to it), but can allow configuration of page titles and other info like that?

Allow iFraming of pattern previews

Sometimes patterns need to be iFramed to work correctly (they may be fixed position, or rely on breakpoints, for example.)

We should add an option in pattern frontmatter to iFrame specific patterns. We should use something like iframe-resizer to make sure these are sized correctly.

Add support for other templating languages

Right now all of our patterns and prototypes are written in handlebars. To make this more flexible we should support other templating languages, like Liquid.

Add focus styles

The work being done to improve the UI includes the addition of styles for buttons, accordions and other interactive elements. It would be great to style the focus state for these elements.

Namespace EP content zones so we can apply styles to links, etc.

One of the big challenges of this boilerplate is any styling we apply has to be namespaced so it doesn't leak into an end user's patterns and styles.

For the most part we do this with lots of classes starting with EP_. For example, we have EP_nav for our nav styles. This works well for HTML we're writing, but not so well for markdown.

Markdown is processed and output without any special classes so it's difficult for us to apply styles to these content sections. We should wrap content sections in an EP class so we can style elements within them. For example we could have an EP_prose class and then write CSS like this:

.EP_prose a {
  /* link styles */
}

.EP_prose ul, 
.EP_prose ol {
  /* list styles */
}

Odd Rollup Error

When saving javascript files this error happens frequently:

[13:47:07] Starting 'js'...
[13:47:07] 'js' errored after 13 ms
[13:47:07] Error in plugin "gulp-better-rollup"
Message:
    Could not load /Users/paulhebert/repos/Eleventy-Patterns/src/scripts/_46__46__47_patterns_47__42__42__47__42__46_js (imported by /Users/paulhebert/repos/Eleventy-Patterns/src/scripts/toolkit.js): ENOENT: no such file or directory, open '/Users/paulhebert/repos/Eleventy-Patterns/src/scripts/_46__46__47_patterns_47__42__42__47__42__46_js'
Details:
    errno: -2
    code: PLUGIN_ERROR
    syscall: open
    path: /Users/paulhebert/repos/Eleventy-Patterns/src/scripts/_46__46__47_patterns_47__42__42__47__42__46_js
    pluginCode: ENOENT
    hook: load
    domainEmitter: [object Object]
    domain: [object Object]
    domainThrown: false

Oddly, resaving the file a second time usually resolves it.

It appears this is related to the glob importing we're using to import pattern JS:

// eslint-disable-next-line no-unused-vars
import * as patterns from '../patterns/**/*.js';