Use the New Automated Style Guide

This article relates to the Kilimanjaro release and newer.

If you cast your mind back nearly a year, you may remember that I posted some information on the benefits of style guides and how to build them. In the meantime there has been progress on this within the SuiteCommerce development team and as part of the Kilimanjaro release we included tools that automate this process.

To reiterate, a style guide is a series of pages that allow to create a cheatsheet of all the important variables, styles, and building blocks of your site. They can be quite small things, such as what colors and font sizes to use, to what we call atoms and molecules that include things like buttons and forms. It is an approach espoused by Brad Frost.

The idea is that it helps developers maintain a consistent style throughout the whole site, speed up development, build up best practices, and minimize the learning curve.

For example, if you want to style a new form on your site, what do you do? Well you could inspect an existing form, and pick apart the styles and classes and then try and recreate them for your new form. Or, with a style guide, create a standardized way of doing forms, create standard classes and styles, and then provide instructions on how to use them. The answer is, of course, the latter.

So what's changed over the past year? Well, there are a quite few things actually:

  • KSS notation — a way of marking up Sass and CSS files so that they are both machine and human readable
  • SC5 generated style guide — this Gulp tasks takes the KSS-marked up code, starts up a simple HTTP server and then creates a simple website for you to see automatically generated documentation
  • Auto-refresh — the server listens for changes to your Sass files and reloads the open style guide in your browser to show your changes

I think the best way to summarize this is that it's now easier to get started but it may take some rigor and discipline on your side if you want to keep it up.

Get Started

So, this functionality is included with Kilimanjaro and if you've updated your bundle then you've already got it. To start, you simply need to run gulp local styleguide.

When the task finishes, you'll have your local version of your site up and running but you'll also have a second local server running, which you can access by going to http://localhost:3000/. When it loads, it'll look like this:

It's quite simple: the landing page contains some introductory text, much like what I've just written, and there's a menu along the top that links to the various sections: styles, atoms and molecules.

If you're just a consumer of the style guide, then you can see how the information included in each section will be useful. A prime example is the colors section, where you can see each color separated as sub-sections and each one has:

  • The purpose (eg primary color)
  • Where it is defined (_colors.scss)
  • The variable name(s) ($sc-color-primary)
  • Usage advice
  • An example of the rendered color

If you look at the other sections then you'll see how the content of these parts changes a little (eg showing markup examples) but the form stays fundamentally the same.

Let's take a look at how these are built.

Basic Syntax

As mentioned previously, we're using the Knyle Style Sheets syntax to mark up our Sass files so that they can be read by humans and machines. To assure the latter, you have to follow a form that goes something like this:

// (Title)
//
// (Description)
//
// Markup:
// (Markup)
// (reference)
(Sass definition)

So, to reuse the primary color example, this translates to:

// Primary Color
//
// $sc-color-primary - The Primary Color is used for primary actions and highlighted information.
//
// Markup:
// <div class="styleguide-color-primary">sc-color-primary</div>
//
// Styleguide 1.1.2
$sc-color-primary: #e23200;

If you compare this to what is rendered on the style guide, then you'll see how it works and how they relate the numbered list above.

Note that every contiguous line requires an opening // to be included: a line without it will indiciate a new sub-section. In normal CSS files you can wrap sections in */ ... /* syntax, but not Sass files.

Perhaps the only ambiguous thing is what I call the reference section (but what KSS call the 'styleguide' section), so let's have a quick chat about that.

References

In order to get the hierarchical structure, the generator reads the final part of each section looking for the string styleguide followed by a number. Simple integers (1, 2, 3, etc) become the main sections. Deeper levels can be created by adding appending a point followed by another integer — this can be extended deeper and deeper to create more sub-sections.

If you look at the top of each main section, you can see where each one comes from. For example, the main Style section starts in _main-variables.scss.

Sections and sub-sections can be added to from any Sass file as long the file meets these three requirements:

  1. It must follow the correct syntax and structure (above)
  2. It must have a unique reference; for example, this means that you cannot have two entries marked as Styleguide 1.1.3
  3. It must be within the BaseSassStyles folder

If two of your references are the same then it will result in an error in your CLI:

This error also appears at the top of the live style guide, should you already have it running.

As for the BaseSassStyles thing, I will get to that in a moment.

styleguide.json

When the generation process has finished, the output is one big JSON file called styleguide.json. You can look at this on your file system, but a simple solution is just to visit it in your web browser: http://localhost:3000/styleguide.json.

If you don't already have it, I recommend a browser plugin called JSONView which prettifies the JSON, making it much more readable as it breaks it across multiple lines, adds syntax highlighting, and the ability to expand and collapse objects.

If you look at the JSON, you'll see the sections object which contains required to build the style guide. Here's the one for the primary color:

You'll see that each section is ordered and that there are values to indicate each's reference and also their parent reference (if applicable).

Adding to an Existing File

OK, let's take a quick look at the process for adding our own documentation to the style guide.

It's good practice to never edit the source files that come in the SCA bundle and to have your customizations in a separate folder. When you want to make changes to the base Sass files, the recommended approach is to use an override to replace an existing file. This process stops the old file from being included in the build and the includes the one you're creating. Thus, your new file will not only have to contain the customizations that you're making but also all the style declarations in the old file that you want to keep. Therefore, a good a place to start is with a copy of the original file.

Prepare the Module with an Override

If your site is themed already then you can skip this step — you can add the customizations I'm going to describe in the next section to one of your existing overrides.

Create a module called CustomStyles@1.0.0 with the following structure:

  • Sass
  • ns.package.json

In ns.package.json put:

{
  "gulp":
  {
    "sass": ["Sass/**/*.scss"]
  },
  "overrides": {
    "suitecommerce/BaseSassStyles@3.0.0/Sass/variables/_colors.scss": "Sass/_custom-colors.scss"
  }
}

This is the override, so now we need to create Sass > _custom-colors.scss to contain our modifications and then copy the contents of _colors.scss into it. So, this is now identical to the old file (and will thus perform the same job) and it also forms the basis of our future customizations.

Add in a New Declaration

OK, so at this point you're either editing one of your own override files or using the one we just set up.

So, what should our customization be? Let us assume that we need a new color variable for our new feature. Let us also assume that, coincidentally, it is to be one of my favorite color hex codes.

At the bottom of the file, add in:

// beeeef
//
// Adds some beeeef
//
// $sc-color-beeeef - Mainly used for moo
//
// Markup:
// <div class="styleguide-color-beeeef">sc-color-beeeef</div>
//
// Styleguide 1.1.9
$sc-color-beeeef: #beeeef;

Stop and start the local style guide task. When it's up, visit the page and you should see something like this:

It works but it doesn't look like the rest of the color sections does it? The reason for this is because we have some styling that affects only the style guide itself, which you can find in gulp > library > sc5-styleguide > lib > app > css-suitecommerce. If we want to style it to look like the others then we'll need to modify these files.

In css-suitecommerce > _styleguide.scss, add in:

.styleguide-color-beeeef {
    @extend .styleguide-color;
    background-color: $sc-color-beeeef;
}

You'll see at the top we have defined the class we're extending and that it's responsible for creating those neat-looking boxes that display the colors.

These files aren't watched for changes like the SuiteCommerce files are so we'll need to stop and restart the task. Once you've done, do a hard reload (to clear the cache) and you should see it all nice and styled:

Naturally, this also means that the variable is ready to use in our styles if we wanted to.

Adding a New File

As I mentioned previously, one of the requirements is that the style guide only generates from Sass files found within the BaseSassStyles directory. You will find this defined in gulp > tasks > styleguide.js.

What this means is that if you would like to add a new section or sub-section then you will need to do one of two things:

  1. Override a file that already lives in BaseSassStyles
  2. Add a file to BaseSassStyles

We kinda did the first already, so let's skip that for a moment.

As for the second one, well, I would advise against it: after all, one of our golden rules is that you never modify source files and I guess that should include source folders too. If you do, the risk is that when it comes to migrating to new releases, you'll accidentally leave code behind. It also means that you fragment the source files: your templates, JavaScript and SuiteScript will be in one place and your Sass in an entirely different place. So what does one do?

OK, for this scenario, let's assume I want to create two things: a new section for my customizations, and a sub-section for my new nonsense widget.

Well, I've created my files: I've got _custom-customizations.scss which is acting like a landing page for the section:

// Customizations
//
// Here we document all the customizations that we have made specifically for this site.
//
// Styleguide 4

And I've got _custom-nonsense.scss, which is where my module's Sass lives:

// Nonsense Widget
//
// The nonsense widget enables users to jaberwock their malarkey.
//
// It provides three actions:
// - stultiloquence
// - razzmatazz
// - galimatias
//
// We use three different kinds of buttons to distinguish between the importance of each action.
//
// Markup:
// <div class="nonsense-container">
//   <h3 class="nonsense-title">Nonsense</h3>
//   <p class="nonsense-grid-float">
//     Nonsense A <span class="nonsense-grid-right"><button class="button-primary button-medium">Stultiloquence</button></span>
//   </p>
//   <p class="nonsense-grid-float">
//     Nonsense B <span class="nonsense-grid-right"><button class="button-secondary button-medium">Razzmatazz</button></span>
//   </p>
//   <p class="nonsense-grid-float">
//     Nonsense C <span class="nonsense-grid-right"><button class="button-tertiary button-medium">Galimatias</button></span>
//   </p>
// </div>
//
// Styleguide 4.1

.nonsense-title {
    background: $sc-color-theme-background;
    text-align: center;
    padding: $sc-padding-lv4 0 $sc-padding-lv4 0;
    margin-bottom: $sc-margin-lv4;
}

.nonsense-container {
    margin-bottom: $sc-margin-lv4;
    border: 1px solid $sc-color-theme-border-light;
    box-shadow: 0 3px 0 $sc-color-theme-background;
    -moz-box-shadow: 0 3px 0 $sc-color-theme-background;
    -webkit-box-shadow: 0 3px 0 $sc-color-theme-background;
}

.nonsense-grid-right {
    float: right;
    padding-right: $sc-padding-lv3;
}

.nonsense-grid-float {
    @extend .row;
    clear: both;
    margin: 0;
    margin-bottom: $sc-margin-lv2;
    padding-left: $sc-padding-lv3;
}

.nonsense-button-container {
    text-align: center;
    background: $sc-color-theme-background;
    padding: $sc-padding-lv4 0;
}

Now, if I put these two files into my BaseSassStyles directory and then restart my local style guide, then it'll show up in the menu.

Now, as I said, I don't think this is a good idea as it will separate your Sass from the rest of your source code, which could have knock-on implications. Furthermore, if you don't set up sub-directories in your BaseSassStyles directory then you run the risk of cluttering it up too.

So how do we get around this? Well, why is it a requirement that the Gulp task only looks for files within the BaseSassStyles folder anyway? The answer is that it's only that way because that's the way we designed it. The cool thing, however, is that we can change this.

A second option would be to edit the Gulp task that determines which Sass files are to be included in the style guide. Now, again, this method involves one of the source files that comes with the application so my default position is to argue against it. However, I feel it is safe to override this advice if you feel it is worth it.

The risks associated with this are much smaller than the other option and offers these benefits:

  1. Modifications to the task file are much easier to migrate
  2. All Sass will continue living with the rest of its modules files

If you've been following along, you'll first need to put back the custom files we created. Move them from the BaseSassStyles directory back into CustomStyles > Sass directory.

Next, head into gulp > tasks > styleguide.js and you'll see that we set a variable called sassGlobs, which we're defining as any Sass file found within the BaseSassStyles directory. Happily, we can modify this so that it includes our custom Sass files.

Replace the line with the following:

// Modified to include an additional custom directory
var sassGlobs =
([
  'LocalDistribution/sass/BaseSassStyles/**/*.scss'
, 'LocalDistribution/sass/CustomStyles/**/*.scss'
]);

If you stop and restart the local style guide server, you'll see that it recompiles and runs again with our custom entries included. Great! Going forward, you can add further entries to this array to include them in your style guide.

Personally, I quite like this method and it simply means that each time you want to include a new entry to the style guide, you can just add it to the array. Our current entries are set up to grab any Sass file in the those directories, but you can, of course, specify individual files if you want.

Writing a Good Entry

As advice, keep in mind that it is not necessary to include in your style guide every single customization that you make to your site.

If we remind ourselves of the original purpose of the guide: it is document the styles, atoms and molecules of the site, or, in other words, the reusable building blocks.

We don't, therefore, include things like "the product detail page" or "the store locator" because these are like large organisms. Thus, if you create some custom functionality, before adding it consider whether it is necessary to document it at all.

If you do decide to document something then you should consider the main sub-sections we discussed at the start and how to best complete them. While I can't teach you to do good documentation in one blog post, the key to success in this microcosm is to think about how other developers are going to use this style or functionality.

Say, for example, let's say you've created a new color, what do you do? Describe the color. Don't just say what it's for — say why it was chosen, what's important about this color in particular. Another example could be some sort of special form. What does form capture? Why? When should someone use it? When shouldn't someone use it?

After designing something, it can be hard to step back and go over all of the steps that led up to it. Documenting design decisions can be important later, not only when it comes to others implementing what you've made but also when it comes to upgrading and migrating it. Sure, this might be overkill for something as simple as color or a button, but keep it in mind.

Advanced Features

This functionality is provided by third-parties and they've written it in such a way that it provides quite a bit of flexibility. If you're interested, I would recommend taking a look at their sites:

So, yes, keep in mind that there are two separate technologies in use here. However, there's a couple of neat features within SC5 that you may want to take advantage of.

Wrappers

When marking up your code to include in the style guide, there may come a time when you need to include some ancillary code to the element your documenting. For example, if you're talking about how to a special list item element, then this'll obviously need to include markup either for an unordered or ordered list. While you could include those in the markup itself, you could simply use a wrapper and have that clean separation.

This could look like:

// markup:
// <li class="myitemclass">
//   <a class="myitemlass-link">Thingybob</a>
// </li>
//
// sg-wrapper:
// <nav class="mynavclass">
//   <ul class="myulistclass">
//     <sg-wrapper-content/>
//   </ul>
// </nav>

This will output the list item in the correct styling without overtly including it in the markup. This is good in situations where you want to make clear that the thing you're discussing is the only thing included in the markup (ie so the user doesn't unnecessarily include the additional code in their code).

Commenting Out

You may have realised that if everything in the style guide is marked up with code comments, then how do you put a code comment without it appearing in the style guide?

It's simple: anything you want to not include in the compilation process, you wrap it specific tags.

// styleguide:ignore:start
Ignored styles
// styleguide:ignore:end

This can be useful not only temporarily excluding styles but also if you want to include some detailed comments that are a bit meta.

Final Thoughts

The style guide functionality enables to keep track of what styles are used on your site and how they're intended to be used. More than that, though, as it also includes bigger items of functionality such as atoms and molecules, comprising things like buttons and forms.

By documenting these styles you can cut down on the number of headaches you and your team will experience when it comes to designing and maintaining your website. For example, if someone is building something that requires a form then you know they can use the markup provided to not only speed up the development time but also ensure that it replicates the style used throughout site, thus ensuring consistency.

The introduction of KSS has meant that our stylesheets are now bigger than before as they contain a lot of markup. Admittedly, this does make scanning files a lot more difficult. However, the trade-off is worth it, in my opinion, as it means that we now have this lovely style guide.

You may also wonder about the effect that this has on performance. The answer is none. When the code compiles for deployment, all of the KSS notation is stripped out of the final CSS files and so it never becomes an issue.

Remember, the style guide is there to help you and your team. You don't have to use it, but we think that it includes a lot of useful information; furthermore, it relies heavily on visualization, so you can see how things look. Change and customize it as you wish.