Over the years, the web has evolved from simple websites to hosting an increasing amount of rich web applications. Designers and developers have learned from this shift to think less about designing pages and more about designing systems. From frameworks, CSS pre-processors, and automation tools to living style guides and UI libraries, we are creating an increasing amount of tools, workflows, and processes to make designing, developing, and deploying web applications easier.

“It used to be that designers made an object and walked away. Today the emphasis must shift to designing the entire life cycle.”

—Paul Saffo

Style Guides

One of my favorite tools of any project I work on is the style guide. My first style guide was a guide I helped create for a web design project I was a part of during my internship at Oden Marketing & Design. I had not heard of style guides until then, and I was intrigued. I liked the idea of having to think about a design in pieces, and then also think about it as a whole. We documented the brand identity, type, and color standards, as well as the layout grids and CSS syntax.

However, the entire process proved to be quite tedious and overwhelming. It was in a PDF format, which I quickly learned is a pain to keep maintained.

Online Style Guides

Fast-forward to 2007, I was working on a style guide for the Apple Online Store. This style guide was built on WordPress, which I figured would be way easier than reflowing a PDF document. HTML flows on its own, so it definitely helped in that regard. It also made things more collaborative since anyone could sign in to add to the guide and help keep it updated. I spent a ton of time building it out to be well-documented and I tinkered a lot with print style sheets, because I believed that people might actually want to print it out.

Something I found very helpful during this project was to have your ideal CSS architecture and organization documented before you do any refactoring. This gives you a goal to work toward. At the time I worked there, the Apple Online Store was the most complex CSS Architecture I’d encountered. You had the very well-known consumer-focused US store. Then you had all the variations on that store for different regions of the world and various countries and languages. Then you also had all the stores focused on education or business-to-business. This is a lot to try to refactor and have in your head. Documenting your idealized architecture, and working out how variations, translations, and overrides will work into the structure, will give you a sense of direction as you iteratively refactor and document.

I was so excited about this project that it led me to write Writing an Interface Style Guide (A List Apart, 2008) based on how I approached things back then. In this article, the key points discussed were:

“Current and Useful” — that’s the most important thing to take away. However, over time I realized that no one ever really took the time to update this style guide built in WordPress except me, so it became a task that grew to be less helpful and at times only got in the way. Lessons learned…

Living Style Guides

Before I started my job at Engine Yard, I had never used or seen their application, AppCloud. So when I started my new job there, I needed to learn how the app worked and looked and how things were organized. The first task I took on was to refactor the CSS (which was using Sass) and create a style guide.

I was brand-spanking new to Sass. I was pretty cocky at the time and figured I write CSS pretty well, so I wasn’t thrilled about this initially. However, after using it in about two weeks I realized I’d become so used to it that I found myself accidentally writing Sass when just writing vanilla CSS for other sites. Being able to use things like variables, mixins, and functions made writing and refactoring CSS for a large-scale application much more maintainable. I realized I was falling in love with Sass and now I can’t stop talking about it!

For the style guide, I built it inside the app itself, so it used the same front-end code base it described. It was an area of the application that only we had access to internally (the company had decided not to release the style guide to the public). There I displayed our icon set, our various typography settings, our color palette, and various UI elements like buttons and form elements.

This led to my “zomg!” moment. I realized that Sass + Style Guides = Awesome. I no longer needed to update color swatches when colors changed because it used the same variables — so swatches would already change automatically. It became a sandbox for new components and elements. I’d design in the browser from within the style guide itself, and document it in place. This I found would kill 2 birds with 1 stone (create the new object and already have it documented in the style guide). Then there’s no waiting until later (which never happens). It also became a quality assurance test; if it was broken in the style guide, it’s most likely broken in the app since it’s all the same code. Anytime I refactor something, I check the style guide to make sure everything’s still working & looking the way they’re supposed to.

I wrote a post for Engine Yard’s blog about the process and began speaking about it at conferences (an attendee at my talk at Madison Ruby 2011 even referred to this as “Style Guide-Driven Development”)!

I soon was excited to find out that I wasn’t the only one that had this “zomg!” moment — so many people are also creating beautiful Living Style Guides and putting them online. Some of my favorites:

There are also a ton of tools out there now to make this process easier and maintainable. You can even read a few other articles on A List Apart about them, such as Creating Style Guides and Getting Started with Pattern Libraries.

A common question I’ve received at conferences is, “How do you find time to work on a style guide?” — which is a very valid question. I’ve worked with many projects in which the style guide was an after thought, or something saved for later. I think the more automated you get and the more integrated into your workflow the style guide becomes, the more useful it will be — and it can actually be quite fun.

Automation is the key word here. There have been quite a few tools I’ve seen released over the last few years that automate the style guide documentation process. Some require you to hand number your comments to go into hand-numbered sections and some simply output CSS comments (usually written in Markdown in your CSS files) in the order it is compiled. These are all pretty great. And tools like Grunt or Gulp can take things even further.

Even Better Living Style Guides

A couple years ago at SassConf, we launched the new redesign of the Sass website. One of our objectives was to open source the web site so that anyone could contribute. As I was building out the beginnings of the Style Guide, I was concerned about maintainability. If someone designed something that required a new color, would they remember to update the style guide to reflect that? I wanted to keep things as DRY as possible.

For design properties, such as type sizes, typefaces, or colors, you have to have markup in the style guide to display an example. You also have CSS to style that example. And if you’re using a CSS preprocessor (Sass, of course, in our case), you also need variables for that design property. That’s at least three places you need to write it. I didn’t want to assume that collaborators would always know to do all that. So how do we automate this?

The website was built on Middleman, which is a static site generator built on Ruby, and it gives you a lot of the tools typical in a Ruby on Rails app. So you get Sass, Haml, Markdown, Ruby gems, and you even get a way of tapping into data via JSON or YAML.

I decided to store my name & value pairs for my design attributes in YAML files. My style guide web pages then simply looped over this one central location of colors, typefaces, sizes, etc. This meant when a new color is added, the swatch is automatically drawn with the name and the value. For my styles, I got sneaky and added an .erb extension to my .scss files. This meant it’d still compile as Sass, but now I could actually use Ruby, too.

So now, using the same technique of looping through to create markup, I now looped through my data to create my variables as well as the CSS required to style the examples. This allowed us to have a single source of truth. You can check out the code in the website repository to see how this was done.

Living Design Systems

When I worked at Do.com (back when it was a start up by Salesforce, and not the company that it is now), I was working on a style guide for the marketing website as well as the web app. Since both lived in the same Ruby on Rails codebase, this got me thinking about shared components. We even documented code syntax preferences (single line, multi-line, tabs vs. spaces, etc.) to make sure everyone was on the same page. Currently, there are efforts such as EditorConfig to help try to make this easier.

While working on this style guide, I really got into a modular mindset. Organize your UI libraries in small elements, then work your way out toward larger components, and then layouts. This will help keep things documented once (you can refer to the smaller or related pieces).

It’s also very important to show all objects’ associated types, variants, and states. If you aren’t explicit in the way an object’s hover states, touch states, open or closed states, etc., then chances are they will be overlooked and not built.

On the web side of things, things were pretty rad. However, I also needed to document our design for the iOS and Android app. This is where things were not so rad. I had a convoluted workflow of saving out multiple images (design comps and redline specs) to a Dropbox folder, and linking to those images from the mobile apps’ GitHub repository wikis. This led to sad times.

I can tell you one of the biggest lessons I learned from this experience is don’t try to document everything at once. If you try to get everything all in one go, you’ll likely get overwhelmed and may even abandon the effort altogether. Instead, document things going forward, iteratively, as you create or refactor things. I’ve found that working in iterations, you’ll be more thorough and have better clarity, because you’re more focused and not trying to cover too many things all at once.

Something that became incredibly important for us was to add tools for rapid development. We had CSS gradient overlays we used to display baseline and vertical grids that only appeared toggled in development. We also had iframes set at various sizes to help us with rapid responsive debugging. You would pass in a page of the app into the URL and all the iframes would change what page they displayed — and it’s even cooler if paired with an auto-refreshing mechanism, like LiveReload.

After my experience at Do.com, I moved over to join the Salesforce1 Design Systems team, which is a core Salesforce UX team focused on creating patterns, design systems, and tools to help keep the various products and features aligned across a very large-scale enterprise company. Honestly, I joined this team because I saw their product style guide and fell in love with it.

We use an automated system similar to StyleDocco in that it outputs components in the style guide based on markup written as comments in the Sass files. Our style guide also serves as a foundation for our prototypes that we build in the browser. During prototyping, we’re able to pass in new attributes such as a label for a button.

Similar to Do.com, we also have to consider native iOS and Android. I asked Sönke Rohde, the super talented UX Engineer I work with, if we could do something similar to what was done for the Sass website, but extend it to native mobile. I was amazed that he basically built the first version of it in about a day, and now we’re actually using it across the company. This open source tool is called Theo, which uses JSON to store design properties as name, value, category, and a usage comment in one central location, and it then generates variables for Sass, LESS, and Stylus. It also generates the Aura tokens (Salesforce’s own open source web framework we use internally for our production web application). And it even outputs the JSON and XML needed specifically for theming native ios and Android.

We built this system to be agnostic so that designers and developers can choose what works best for them (Sass, LESS, Stylus, Angular, React, etc). This enables us to have a design system that is timeless with today’s shifting landscape in technology. And by staying agnostic, when we update Theo, we have minimal impact to the designer or developer’s workflow.

We now have a true Single Source of Truth for our theme tokens which can be used by a wide variety of platform and devices. We also have an internal repository of assets (like icons and fonts) that we keep updated in one place. The style guide pulls from this to display all the icons in our style guide.

All of this is leading to better collaboration across our many teams, and better alignment. Because the work we are doing has expanded beyond the web and beyond a simple style guide, Sönke coined the phrase Living Design System to better describe what we’re creating — I think it has a good ring to it, so I’m going with it. Sönke wrote about it in more detail in his article.

I would really like to know what you’re doing on your team if you have better ideas or similar experiences. So please share so we can all learn! Remember, keep your documentation current and useful!

“Be regular and orderly in your life so that you may be violent and original in your work.”

—Gustave Flaubert

License: All rights reserved