Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

 

Module of the Month: Never go out of style

Making a new style guide for each project can be a real chore, especially if you just want to dive in and get started. In this 'Module of the Month', Simon looks at how we can make this task much simpler.

Read post

From designers to developers, marketers to backenders, project managers to frontenders, and everything in between and everyone I missed. We have all been there, having to demonstrate how the basic site will look, styling, image positioning, tables etc.

On every project you need to set up a style guide page, that contains everything typography-wise for that project, followed by adding all the typography options on a demonstration page. This tedious job usually takes at least an hour to make. An hour you’d probably wanted to spend on something else. 

You’re probably already bored by simply reading that intro.

Kitten yawning image to keep attention

This cat photo is an attempt to keep your attention

What is a style guide

A style guide is a single page, containing all the information about the styles and colours that should be used on the website. From fonts to font sizes, from tables to (un)ordered lists. Images and their positioning, captions, form elements and all the other bits and bobs that put together the basic look of the site you’re building.

This page gives any project manager or tester the ability to easily check if the website itself is still following the style guide and confirm that the content looks the way it should.

It’s a very useful thing to have, that’s for sure. A well maintained and up to date (also known as “living”) style guide, in sync with the actual code, helps building a well documented and structured front-end codebase. The building blocks of the style guide, like the typography, colors, form elements, lists, etc. become more maintainable in the future.

Some people call it a Kitchensink, Branding guide or Design manual.

The module

benmanu/silverstripe-simple-styleguide

My colleague Ben Manu has probably spent too much time on these style guides, as he decided to make this tedious task a bit easier.

This module is a very simple one in terms of implementation. Just install it and you’re done!

composer require benmanu/silverstripe-simple-styleguide:~1.0 

In basic, that’s all there is to it. The module works out of the box and gives you a style guide. Once installed, you can view the style guide in dev mode or administrators only, by going to yourwebsite.local/_styleguide

The default uses a standard Lorem Ipsum text as a placeholder. But as discussed below, you can change the default text. Although, no bad word about Lorem Ipsum… I personally like Samuel L. Lipsum. Admitted, that one is not always that client-friendly, as you’ll probably agree.

The usefulness

Let’s go through some elements. Beginning with the table of contents. As every well respected document, the style guide comes with a table of contents.

Table of contents from a style guide

I did absolutely nothing, to just get this list of quick links to all the items that matter in a style guide. It comes with everything you need. As you can see, the font that should be used is applied from the base Page inclusions and the colour of the links is what it should be for this project straight away.

And I also have an immediate way of going straight to a certain part of the style guide, to compare the actual website to what it should look like.

All the content is automatically populated with Lorem Ipsum text. Basic elements like tables, forms, image positioning, it’s all there.

Including Typography, which also has special characters. In New Zealand, we often have to make sure characters used in Māori language are supported. These are in the Typography by default.

Colours

To get the Colours, there needs a bit of configuration in a YML file. My personal suggestion would be to put this in a styleguide.yml file in your project, but you can of course put it in any yml file you like.

An example yml file would look like this:

SimpleStyleguideController:
 color_swatches:
 - Name: "Midnight Blue"
      Description: ""
      CSSColor: "#002E5E"
     TextColor: "#ffffff"
   - Name: "Red Violet"
     Description: ""
     CSSColor: "#D01382"
     TextColor: "#ffffff"
   - Name: "Deep Cerulean"
     Description: ""
     CSSColor: "#007CAD"
     TextColor: "#ffffff"
   - Name: "Key Lime Pie"
     Description: ""
     CSSColor: "#B9C21D"
     TextColor: "#000000"

Which results in this beautiful set of colours, with the text colour as the text on the colour block, together with its name, and the hex of the colour below.

Screenshot 2018 1 10 Styleguide The Hub1

Colour names are from Name That Color. We use it in our team a lot, because it’s a lot more fun than plain old “pink” “green” “green-ish” and “blue”

The advantage of these colour swatches, is not only the immediate visibility of the colours, but also the ability to check accessibility of the colour combinations, making sure the contrast is good enough for the visually impaired.

Form

The standard style guide generated by the module contains a SilverStripe form with the most used form fields to validate the styling of the forms. This helps styling the generated forms by SilverStripe, as well as the forms generated by the User Defined Forms module.

Flexibility

The module is flexible, having an extension point (updateStyleguideData) to add custom behaviour and allows for overriding of the default template by adding a SimpleStyleguideController template file in your themes folder.

Conclusion

Don’t break your head over that annoying, tedious job of creating a style guide page. Let a module do the work for you!

As per usual, give it a try, contribute and enjoy!

If you want to stay updated on other interesting SilverStripe content, subscribe to our weekly blog digest at the bottom of this page

Cat photo is licensed as CC0 License

About the author
Simon Erkelens

Simon is a developer at SilverStripe. When not at work, he's writing other programs or focusses on one of his modules he wrote or co-wrote. Or writing new things.

As a real backend developer, he's usually staring at a dark screen with code only. Although every now and then, he can be convinced to work on some frontend things or testing.

In real life, he looks nothing like the cow in his avatar, but he does love cows (both alive and medium rare)

Post your comment

Comments

No one has commented on this page yet.

RSS feed for comments on this page | RSS feed for all comments