Make your styleguide a living styleguide!
Don't you know that, too? You or your team is building a site and during this process all implemented parts are styled through templates and CSS. The CSS files (at best you are using a CSS preprocessor like SASS are getting bigger, more sophisticated and even more confusing - not to mention that these files are getting almost unmaintainable and more and more error-prone. Of course you can reduce risks a little by sticking to standards like SMACSS, but you will reach a point where it is almost impossible to keep track of all changes - especially when a team of several members is involved.
By now at the latest, you should have a styleguide that provides an overview of all styled components of the site... But where will you find the time to create one now? And who takes care of it to ensure that all future components will be included? There is a simple solution - the Living Styleguide!
At DrupalCon Amsterdam 2014 there was an interesting session by John Albin Wilkins, which covered this topic. Apart from an introduction about agile development, he explained in detail how team members may automatically create a styleguide during the development process by using the Knyle Style Sheets (KSS) tool or more specifically by its Node.js implementation kss-node. This automated styleguide allows to examine and review every component of the site on its own - even without the context of the actual site itself.
Sounds complicated, but it isn't!
kss-node is easily installed by the help of Node Packaged Modules with a one-line command (`$ npm install -g kss`). Now you only need to place a `styleguide.md` file in the source directory of your style files (the directory containing e.g. CSS, SASS or LESS files), which is used as the entry page for your styleguide and may be filled with any generic information about your project at will.
The following command then generates the styleguide:
$ kss-node "path/to/styles-directory" "destination/of/styleguide-files"
Visit the kss-node project page for a full reference of the `$ kss-node` command.
The styleguide directory now contains all generated styleguide files. But wait... apart from the entry page, which was generated from the `styleguide.md` file, it is completely empty?!
This happens, because we do not provide any real data for the parser yet. But this is also done in a breath: With the help of simple annotations in the comments of your style files, you may provide information about the expected markup and its corresponding styles. It is even possible to provide Modifiers for different states of a component (e.g. `:hover`- and `:active` state of a button). Here is a basic SASS example:
_buttons.scss
// Buttons
//
// Just add your descriptive text about buttons here //
// Styleguide 1
// General styles
//
// Add even more descriptive text...
//
// :hover - State: Hovered
// :active - State: Active
// .btn-medium - Size: Medium
// .btn-large - Size: Large
//
// Markup:
// <!-- Default button: -->
// <button type="submit" class="btn {$modifiers}"> // Label
// <!-- Link button: -->
// <a href="#" class="btn {$modifiers}">
// Label
// </a>
//
// Styleguide 1.1
.btn {
background: #83B81B; border: 2px solid #83B81B; color: #fff; font-family: sans-serif; font-size: 0.75em; padding: 1em; text-decoration: none;
&:hover {
background: #fff;
color: #83B81B;
} &:active {
background: #fff; border-color: #000; color: #000; } &.btn-medium { font-size: 1.25em; } &.btn-large { font-size: 2em; } }
Visit the KSS projct page for a full annotation syntax reference.
Et voilá: After running the `$ kss-node` command explained above again, the styleguide now contains a new Buttons section, which provides previews for all Modifier variants of the button component.
More styleguide examples
And there is even more...
- As Markdown is supported, all annotations may contain any Markdown syntax
- Use `$ kss-node --init "your-template"` to initialize a custom styleguide template, which then may be adjusted to all your special needs. Add the `--template "your-template"` option when running `$ kss-node` to use this template for generating the styleguide
- Generation/updates of a styleguide may be automated with a task manager like Gulp
- ... Everything else is up to you!
It will be interesting to see how this tool will mature in the future and if there will even be a Drupal integration for the automated generation of all the source code snippe
