Documenting patterns

A look at how to document & rationalize your patterns, describing when & how to use each.

Goal

Since one of the important aspects of our pattern library is documentation, we also need to look at how to document each single pattern.

  1. Type it, type it real good

    Remember the purpose of this lesson is to type the code out yourself—build up that muscle memory in your fingers!

1 Documenting pattern groups

Each pattern grouping should have a title & description to help rationalize the purpose and use of the patterns.

We can do this within the config.yml file for each pattern folder.

  1. ecommerce-pattern-library
  2. css
  3. images
  4. js
  5. _patterns
  6. buttons
  7. config.yml Make a new YAML file
  1. Inside the buttons folder make the following empty file: config.yml

Now we’ll type a little bit of code for the pattern grouping.

title: "Buttons"
description: |
  Buttons should be used in situations where a dramatic, obvious action is required. Try not to over use buttons because they should be the primary call-to-action for a screen.

Refresh your pattern library and see the description within the buttons pattern.

  1. Line A

    If you leave title out of this file, Patternbot will generate a title based on the folders name.

2 Documenting single patterns

We should even document each single pattern within the grouping. To describe when & how each pattern should be integrated into the design.

title: "Buttons"
description: |
  Buttons should be used in situations where a dramatic, obvious action is required. Try not to over use buttons because they should be the primary call-to-action for a screen.

patterns:
  basic:
    title: "Basic"
    description: |
      Default to using the basic button. It should always be used in front of light backgrounds.
  ghost:
    title: "Ghost"
    description: |
      The ghost button is specifically for banners, where it will be placed in front of busy images.

Refresh your pattern library to see the changes.

  1. Line E

    All the descriptions for each pattern is found under the patterns key.

  2. Line F

    The key is spelled exactly the same as the HTML file: so basic.html becomes basic: within the config.yml file.

  3. Line G

    If you leave off the title it will be inferred from the HTML file’s name.

  4. Line H

    Be descriptive, explain when and how the specific pattern should be used & included.

3 Configure Patternbot’s display

With some patterns, the way they’re displayed in Patternbot isn’t always ideal. For example, cards can be displayed way too wide.

That flexibility is extremely important, we want our cards to flex to lots of sizes. But sometimes we don’t want them displayed that big inside Patternbot.

Or maybe you need to change the background colour of a specific pattern.

title: "Buttons"
description: |
  Buttons should be used in situations where a dramatic, obvious action is required. Try not to over use buttons because they should be the primary call-to-action for a screen.

patterns:
  basic:
    title: "Basic"
    description: |
      Default to using the basic button. It should always be used in front of light backgrounds.
    width: "12em"
  ghost:
    title: "Ghost"
    description: |
      The ghost button is specifically for banners, where it will be placed in front of busy images.
    background: "--color-primary-light"

Check out the Pattern library cheat sheet to see more options.

Continue to document all the patterns in your library—and all future patterns.

  1. Line J

    Use the width option to affect how wide the pattern displays in Patternbot.

  2. Line O

    Use the background option to affect the background of the whole pattern within Patternbot.