One of the things that I’ve been experimenting with in my workflow is Style Guide Driven Development (I’ve seen it abbreviated as SDD or SGDD.) It’s the idea that you develop the user interface separately, within a style guide, first.
Style Guides on the Design Side
Let’s talk about style guides. On the design side of things, style guides are nothing new, especially if you’re working on branding or with other designers. In either case, you want to maintain a level of consistency. A style guide will tell you what fonts, colors, and image treatments to use.
It may also include information about how to use the logo and specific instances for using each version of the logo (horizontal, vertical, icon only, tagline, etc.)
Style Guides on the Coding Side
On the coding side of things, style guides will contain information about different elements used throughout the site: how headlines should look, how photos should be treated, how blog cards appear. You get the idea.
They’ve become popular because people can simply download Bootstrap’s stylesheets and scripts, copy and paste their HTML, and everything works. — well, in a perfect world, everything works. 😉
With those things in mind, what is the best value that we can bring our clients? Dave Rupert wrote a post in 2013 (an oldie — in Internet years, but a goodie), entitled Responsive Deliverables. Dave talks about focusing on “Modules, not pages.”
Working on isolated components make the iteration process faster.
Dave says, “Tiny bootstraps, for every client.”
How do you do that? It sounds like a lot more work.
Bear with me.
Enter Living Style Guides
A living style guide is a document that updates as you make changes to the codebase. Since it’s constantly changing and evolving, it’s considered “living.”
As long as you’re able to include the process within your existing workflow, it’s not much more work than what you’re already doing. I’ve also found that the projects that I’ve applied a living style guide to, it’s challenged me to rethink how I plan my code. As a result, I’m working smarter and my code is more efficient.
Setting up a Living Style Guide
I liked this option because it was very easy to set up. The interface is beautiful and makes it easy to navigate your code. In fact, the documentation on their site even has a section for getting Atomic Docs to work with WordPress.
NOTE:The WordPress section of their documentation explains where to put the Atomic docs files and how to access them within the browser. It also tells you to include a snippet within the atomic-head.php file to get WordPress functionality outside of your WordPress theme. —I could never get that part to work.
To install Atomic Docs:
- Download the files from Atomic Docs’ GitHub repo.
- Copy and paste all the files into your theme directory. There are a few files that may overlap with your WordPress theme (index.php, README.md, and LICENSE.txt), in which case, keep your WordPress files instead of the Atomic Docs files. In fact, you don’t need any of the 3 for Atomic Docs to work.
- Add your site’s stylesheet and any TypeKit or Google Fonts embed code to the atomic-head.php file.
- Assuming you’re developing your site locally, you can load the site within the browser at something like this: http://your_site_url.dev/wp-content/themes/my_theme/atomic-core
Using Atomic Docs is pretty straightforward. Everything happens within the browser. You can add and delete categories by clicking on the link in the left panel.
You can also add components by expanding categories (folders) and clicking on the Add Component link.
Pattern Lab is more stripped down in design. — But, that’s the point. The focus should be on what you’re building, not the frame you’re working within.
To install Pattern Lab:
- Go to their site. Click on the download link and find the version you want. There are several options in PHP and Node. I use Gulp on my sites, so I grabbed that version.
- Copy and paste the files into a directory within your theme directory. I would recommend calling it pattern_lab, but it can be whatever you’d like.
- Open up styleguide/html/styleguide.html and add your site’s CSS and any TypeKit or Google Font embeds to the page’s
- Open your pattern_lab folder within the Terminal and run
gulp patternlab:serveThat will compile your code and automatically open Pattern Lab within a browser. The nice thing about this command is that it will automatically run BrowserSync so any changes you make to the code will be immediately reflected in the browser.
In addition to
gulp pattarnlab:serve you can also run:
gulp patternlab:helpwhich will tell you all the commands you have available within gulp for Pattern Lab.
gulp patternlab:buildwhich will generate your site. Unlike
gulp patternlab:serve, it will not watch for changes and will not launch a browser.
To make any modifications to your style guide, open the source/_patterns folder. Here, you’ll find directories for all the sections for your code to live.
If you drill down, you’ll find files with a .mustache extension and .md extension. The .mustache files simply include the HTML of code patterns on your site. The .md files include any documentation you want to include.
Just remember, any code you write will need to be compiled with Gulp.
Pattern Lab or Atomic Docs?
You pick! You don’t need both. Just pick one. They both have pros and cons, most of which probably revolve around personal preference.
- Has a great user interface that makes it easy to move around your code
- Has more flexibility with how your code is structured, allowing you to organize your styles however you want
- Has built in tools for checking the responsiveness of your code.
- Using the mustache syntax, it’s easy to include portions of one template in another.