Design Project Documentation: Tips, Resources and Best Practices

Digital projects thrive in the chaos of creativity. But they can only survive with clean documentation and rigid maintenance.

Portrait for EnvatoBy Envato  |  Updated October 1, 2020

Digital projects thrive in the chaos of creativity. But they can only survive with clean documentation and rigid maintenance.

In the past I’ve covered how to use styleguides on the web and how to publish them live for the world. But in this post I’d like to delve into the subject of what constitutes great style documentation.

This can include a style guide but also includes documentation for written copy, branding, and essential UX components that ultimately make up the user experience.

Feel free to skip to the section that interests you most, or simply read on:

Great Docs Speak To Everyone

Documentation should be easy to consume yet detailed enough to follow without any prior knowledge. Great design documentation should care about the miniscule details like pixel widths and RGB/Hex color values.

But it should also portray a broad picture of the overall design. It needs to communicate how the design should look, feel, behave, and ultimately be composed on the screen.

You can use design documentation as both a selling point and a communication tool for your vision. This is incredibly useful when you work in a team but it’s just as useful on your own projects.

You can always come back to design documentation to refresh your memory about the goals & objectives of a certain project. It’s also great for new designers who join a team and need design guidelines to add new widgets or new pages into a site.

Think about Google’s material design project and how far it has come over just a few years. This is a powerful example of design documentation at work.

Material Design Interface

Anyone from around the world can look over these docs and mimic the Google design strategy. It applies to all interfaces from websites to mobile apps.

But this documentation is more than just a set of rules. According to Wikipedia it’s really a design language used to express ideas visually. Great documentation should aim to create a design language.

It should be able to express any idea visually and cover enough depth so that nobody is left guessing how to design a new icon or custom UI element.

If you’re looking for examples check out DesignGuidelines, a new site dedicated to curating online design guides.

DesignGuidelines, a new site dedicated to curating online design guides

But it doesn’t take many examples to pick up the basics. Any great design documentation should be intuitive, easy to read, and simple to understand.

Everyone from the creative team to the higher-level executives should be able to understand the creative direction just from looking over a project’s design documentation.

Starting With Style Tiles

When you’re in the early phases of a creative project you need to get ideas down and see how they fit. Style tiles are the perfect resource for designers to organize a series of colors, patterns, logos, and UI elements together into one place.

Style tiles for designers to organize a series of colors, patterns, logos, and UI elements together into one place

This may be considered a type of design documentation but it’s also a powerful resource in the early stages of a new site(or a site redesign).

Check out this guide explaining the basics of style tiles and how they apply to the web.

There are no specific rules and the ultimate goal is to share an overall vision of the design including typography, colors, patterns, and maybe sample widgets like a navigation menu.

This may seem like extra work but there are plenty of reasons to start with style tiles.

  • Quicker & easier to create from scratch
  • A visual form of rapid prototyping
  • Demonstrates the “big picture” of the design

Also remember that a web project may have different phases of the design. The first phase might be identity & branding followed by the interface.

In this case you might create different style tiles for different phases, then expand the tiles into detailed documentation once you pick one.

For example Foursquare has an entire brand book just for their logo and icon.

Foursquare logo design

This PDF includes design guidelines for the logo, the icon, and some of the badges created for Foursquare users.

Style tiles should be much lighter than a brand book. However the inspiration for a style tile can ultimately funnel into a detailed brand book or UI design document.

Use these to your advantage during the early phase of a creative project. Once you know which design style is a winner you can flesh out more detailed ideas.

And to learn more about style tiles check out some of these related posts.

Deliverable Style Guides

Web projects rely on style guides just as much as any other design project. These guides are the final “polished” documentation for UI designers to study and replicate.

Google’s material design is one example of a free open source design doc. It tells designers how to style buttons, tabs, and other widgets. It also delves into animation effects and how a material layout should “feel” when the user interacts with the page.

Deliverable Style Guides

Before you start a new style guide you should consider what you need to cover.

There are no specific limits but you should consider a variety of topics:

  • Primary/secondary/tertiary colors
  • Typographic styles and font choices
  • Background patterns
  • Button designs
  • Photography
  • Icon styles with examples
  • Forms & input fields
  • Wireframe flows

Remember you want to capture the big picture of the design while also documenting all the little details from button sizes to font styles.

This guide will become the design documentation for whatever site you’re designing. As you craft the design try to break up elements into sections that you can use for a table of contents.

Adobe Clean Light

For example, you might have one section on typography and another on buttons or form inputs. A designer should be able to skim through your documentation and quickly find whatever they need.

In many cases it’ll be better to create design documentation as a PDF along with a webpage. This page can be private for internal use only, or it can be public and shared freely.

Take for example Mozilla’s style guide webpage.

Mozilla's style guide webpage

This certainly isn’t the most detailed style guide but it does cover a lot. You could use this as a basis for starting your own documentation while adding sections as needed.

Keep in mind that mobile is on the rise so you should document any specific details for the responsive layout. Do headers need to be resized? How much padding do you need on buttons?

It may seem annoying to get into this much detail but designers who pick up your documentation will be forever grateful.

Capturing The User Experience

Style guides are basically the de facto solution for design documentation. They can cover an entire interface full of elements, colors, and basic style choices.

But a much newer aspect of design documentation is user experience, and I think this will become even more important as time goes on.

The normal design docs include colors, spacing, fonts and icons. But you also need to consider how the interface behaves and how it should operate.

Do you have any CSS/JS animation? And how are those interface animations created? What sort of easing and timing should be used? What about page flows & interactive elements like forms?

page flows & interactive elements like forms

Don’t be afraid to add far more detail than you might think would be useful. This extra layer of info can be an asset to future designers.

For example, adding a wireframe that displays the user flow between pages can help creative directors explain the “big picture” of the project. Executives can determine if they have all the necessary pages on the site while designers can plan where other pages should go.

If possible you should always provide a top-down view before getting into the nitty-gritty detail. If you can learn to make documentation for everyone you’ll realize the importance of all the big picture stuff.

Val Head is an expert in UI effects and she talks about animation in style guides by stating bluntly:

Animation absolutely belongs in your style guides. It’s the perfect place to document what animation decisions have been made, and to lay a foundation for making cohesive animation design choices in the future.”

Val Head

Val mentions the example of IBM’s documentation which has a separate page for animation.

IBM's documentation which has a separate page for animation

Companies big and small can benefit greatly from adding user experience concepts into design documentation.

Interfaces are built to be touched and clicked. So it could be argued that the experience actually matters more than colors or font choices.

But if you’re able to work with both then pad out your docs and go for detail. There doesn’t seem to be any limit of “too much” information with a style guide.

If it’ll help future designers understand and expand upon an existing design then it probably belongs in the documentation.

Further Resources

The first time you create design documentation it’ll feel awkward. You basically know what to do, but the actual structure can be overwhelming.

I find it’s best to create and finalize the design irst. Once it’s signed off you can take notes on paper(or digitally) listing ideas for documentation chapters and important sections. Break this down further until you have a sturdy outline for the documentation, then start chipping away!

If you’re looking for more live examples check out this site full of style guide samples from real brands. You can also find more on the Web Field Manual webpage.

Design documentation isn’t perfected the first time around. You have to practice to fully understand what your clients need and what you should deliver.

Try practicing with existing websites first just to build up your skillset. From there you’ll learn what works, what doesn’t, and how to craft a completed design doc from scratch.

If you’re looking for more detailed information about creating design documentation then you might enjoy these related blog posts:

Related Articles