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.
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.
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.
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
Post your comment
Comments
No one has commented on this page yet.
RSS feed for comments on this page | RSS feed for all comments