{"id":242889,"date":"2016-06-17T06:54:46","date_gmt":"2016-06-17T13:54:46","guid":{"rendered":"http:\/\/css-tricks.com\/?p=242889"},"modified":"2017-04-10T17:45:17","modified_gmt":"2017-04-11T00:45:17","slug":"style-guide-driven-development-atomic-docs","status":"publish","type":"post","link":"https:\/\/css-tricks.com\/style-guide-driven-development-atomic-docs\/","title":{"rendered":"Style Guide Driven Development with Atomic Docs"},"content":{"rendered":"

The following is a guest post by Nick Berens<\/a>, a senior front-end developer at wisnet.com<\/a>. Nick and his team have been building websites through custom style guides for years. Over those years, Nick has been building and evolving a tool to help with this process. I’ll let Nick explain both the philosophy and the tool.<\/em><\/p>\n

<\/p>\n

I bet you\u2019ve heard about style guides. Perhaps you’ve heard about style guide driven development (SDD)?<\/p>\n

I’m a front end developer at wisnet.com<\/a>, an agency specialising in PHP and WordPress development. This is a brief intro into style guides and our team\u2019s experience with style guide driven development.<\/p>\n

Over last 2 years I have been practicing SDD with a tool I wrote called Atomic Docs<\/a>, a front-end style guide generator and Sass partial manager. I’d like to introduce Atomic Docs and some of it\u2019s features that have made SDD a simple and essential part of our workflow.<\/p>\n

What is a style guide?<\/h3>\n

There are two types of style guides we work with at wisnet. A static design style guide and a more dynamic front end style guide.<\/p>\n

Design style guides<\/h4>\n

Our design style guides are static Photoshop (PSD) files cataloging a project’s global design elements. They document a project\u2019s colors, fonts, headings, button states, link states, lists etc.<\/p>\n

\"\"
Example style guide from Medialoot<\/a><\/figcaption><\/figure>\n

Front-end style guides<\/h4>\n

Our front-end style guide, which is generated by Atomic Docs, provides documentation for the code associated with the front-end components of a project. Think of the documentation site<\/a> for Bootstrap. It provides notes and markup examples for each of its components making it easy to reference, understand and use each component.<\/p>\n

\"\"<\/figure>\n

Living style guides<\/h4>\n

A living style guide is a system that allows the components within the style guide to remain in sync with the components in the site, without having to update the code in both places!<\/p>\n

For large projects, a living style guide is the key for a successful system.<\/p>\n

What is style guide driven development?<\/h3>\n

To help illustrate, I\u2019ll briefly outline our process at wisnet.<\/p>\n

It starts with design<\/h4>\n

At wisnet, our style guide process begins with our designers. Every project they hand off comes with two deliverables. A traditional PSD comp of the full page layouts as well as a design style guide documenting the project’s global styles. <\/p>\n

On to the front end<\/h4>\n

Once complete, the PSD comp and design style guide are handed off to a front end developer. The first thing I do is open up Atomic Docs and start documenting the global design elements as defined in the design style guide. <\/p>\n

After adding the global design elements, I open up the PSD comp which has the full design. Since I use Brad Frost\u2019s Atomic Design<\/a> principles, this is when I start analyzing the design and deciding what design elements will come together to compose the design\u2019s Atoms, Molecules, Organisms, Templates and Pages. Organizing and managing components in this fashion is where Atomic Docs is really helpful. <\/p>\n

Once all of the components are built, categorized and documented in Atomic Docs, it is simply a matter using the components like lego blocks to build out the pages and views.<\/p>\n

The back end<\/h4>\n

If the project is an application, I will hand off the static views along with the Atomic Docs style guide. With the style guide as a reference, it is easy for the backend developers to make adjustments to the front end as needed without having to interrupt their workflow by handing it back to a front end dev.<\/p>\n

As you might suspect, the development process is never quite<\/em> this linear (there can still be lots of back and forth between teams), but the use of style guides provides a common design language which enforces design and code consistency throughout the lifespan of a project.<\/p>\n

What are the advantages of SDD?<\/h3>\n

By building components outside of any context, you have code that’s modular and free to move around your site or application<\/h4>\n

We\u2019re not designing pages, we\u2019re designing systems of components.<\/p><\/blockquote>\n

Stephen Hay\u2019s quote is at the heart of SDD.<\/p>\n

We\u2019re no longer building a button to be red when it\u2019s in the context of a sidebar. We\u2019re now just building a red button that\u2019s going to be red whether it\u2019s in a sidebar, footer or header.<\/p>\n

When you build without context, the side effect is a front-end codebase that\u2019s far more scalable, modular, and maintainable.<\/p>\n

Making the components more approachable for less front-end savvy backend developers and designers<\/h4>\n

Style guides have encouraged our designers and junior developers to build pages and views quickly without having a deep understanding of HTML\/CSS\/JS. And since each component is isolated, it makes it easier to understand the code that created it.<\/p>\n

Every project I finish has a bootstrap-like documentation showing the relevant HTML\/CSS associated with each component<\/h4>\n

No matter how big or small, every project our team completes has full documentation of its front end design system. This makes every project far more maintainable. It is especially useful for the organizations we\u2019ve worked with that have internal development teams. It has made it a lot easier for these groups to make changes and scale their projects and has been valuable.<\/p>\n

Enforcing brand integrity<\/h4>\n

Since the style guide contains the project\u2019s color and font definitions along with logos and other graphic assets, it can be viewed as the design source of truth. <\/p>\n

About Atomic Docs<\/h3>\n
\"\"<\/a><\/figure>\n

Atomic Docs<\/a> has two primary features. <\/p>\n

SCSS partial manager<\/h4>\n

Being able to break up my CSS into small partial files is one of my favorite Sass features. Managing all of these partial files is not.<\/p>\n

Here\u2019s a screenshot of a molecules category and root `molecules.scss` file.<\/p>\n

\"\"<\/figure>\n

Creating this structure is wonderful<\/strong> for organization and overall developer sanity. But as the project grows, creating and managing the partial files becomes a pain point in my workflow. <\/p>\n

Atomic Docs provides a GUI for handling the creation and management of these partial files along with writing the @import my-component<\/code> string to the corresponding root `.scss` file. Through this interface you can also rename files, move them to different categories, and delete them.<\/p>\n

\"\"<\/figure>\n

You might be thinking that I\u2019m super lazy and creating partial files isn\u2019t really that big of a deal, but it\u2019s truly my favorite part of Atomic Docs. <\/p>\n

The (generated) style guide<\/h4>\n

Perhaps the biggest advantage to using Atomic Docs is how easy it is to get up and running with the style guide. <\/p>\n