Working with the style guide

Documenting a component

To document a component within Bedrock, create a folder with the component category/content/templates/_components folder.

Then, create a and a .pug file with the component name in said folder. Put your template code in there and the component will show up in the style guide within Bedrock.

Humanized component names

We automatically try to prettify the component name based on the folder structure. You can categorize components with a prefix, for example c-my-component.

Within Bedrock’s configuration you can then define the meaning of a custom prefix:

componentCategories: {
  oc: 'Official components',
  cc: 'Custom components'
}

This prefix defines how the category shows up in your style guide.

Component descriptions

To make the documentation prettier, you can use a markdown (.md) file with the same filename as the .pug file in the folder.

Use YAML front matter to give the component a title and content.

Here is a template:

---
title: My component
---

[Description of my component in markdown]

Documenting typography

To document typography, create a new component and use a template like this.

This example is the one from Material design – you can adapt it to your needs by changing the types of headings that get included.

Note that some of the classes in there are hooks for automatically documenting the font size of components in pixels using Javascript.

Documenting icons (SVG)

You can put SVG files in the content/icons directory to document them.

We also support 1 level of folders here, e.g. content/icons/16 and content/icons/128 . For example when you have small icons and large “illustrative” icons.

Within your pug file, use a loop like this to loop over all your icons in their respective folders:

.c-styleguide-svg-icons
    each category, id in icons.svg
        if id
            h4 #{id}
        else
            h4 base folder
            each icon in category
                +icon(icon.category+'/'+icon.name)
                | #{icon.name}

Documenting icons from a Bedrock generated icon font

Bedrock supports generating an icon font. You can generate an icon font by placing icons in the content/icon-font-source directory.

Make sure icon fonts are enabled. See configuration.

You use a loop like this in the documentation to document the icons:

ul.br-icon-font-list
    each icon in icons.iconFont
        li
            .if(class="if-"+icon)
            | #{icon}

To style the component documentation, we recommend writing a little bit of custom code scoped to the styleguide. You will find example code in our Bedrock bases e.g. the Material design base.

Documenting colors from JSON (recommended)

We used to document colors directly from an SCSS variables file, but are stepping away from this technique.

The new recommendation is to use a data file to document colors. Add a data file, for example colors.js to the content/data folder. Here is some sample content you can use in a gist.

Now render it out as you would normally render data.

each color in contentData.colors
    div(style="background: #"+color.code+"; height: 40px; width: 40px;")
        | #{color.name}
        br
        | ##{color.code}

Documenting colors directly from SCSS variables

Use code like this gist to loop over colors.

We are supposing you have defined a reference to a colors.scss file in your config, that follows a very specific syntax, see this template for an example.

Since we depend on regular expressions to parse the colors, you should use exactly this syntax. Don’t use SCSS variables in this file – only HEX values.