Making your design decisions as clear as possible

There are so many design decisions that go into every single part or your web site or app. It’s often easy to forget all of the little details that you hold in your head or that have come up during a one off conversations with a team member. Creating a document for your design handoffs can be a huge help to your team and yourself.

About a year ago the Formstack design team started creating a design document for every feature or improvement we work on. No matter how big or small, each feature I work on gets a design document. This does exclude issues and bugs. Those are handled in Github issues. Some issues require solutions that will end up in a design document but most often are handled in the Github issue.

After creating these documents for a year now it’s hard to imagine how we would pass on our work without them. It allows us to centeralize all of the information about any given feature in one place. We manage these documents in Confluence but you could use any number of systems. Just having one central place to communicate the problem and solution is super important.

It also functions as a todo list. When the design document is all filled in I know it’s ready for review and hand off. The other huge benefit is have this one document that I can refer our team to. It has all they need to fully understand what we are trying to accomplish or build in one place.

Basic Design Document Contains:

  • Problem statement. This is they what and why of what we are needing to solve.
  • Detailed requirements on each part of the feature. This can also include workflows.
  • Mockups, clickable if needed. (Balsamiq, Invision, HTML/CSS)
  • Screencast walk through
  • Links to other resources. (Trello card, mockups, github)

Even a year in it’s still early and I’m sure this will evolve over time but as of right now here are a few things you’ll find in our design document template:

1. Problem Statement

It’s important that everyone clearly understands what problem we are trying to solve and why it’s a problem. This helps keeps the team focused on solving the right problem. If we notice things starting to drift, we can ask ourselves if we are staying true to the problem statement.

2. Detailed requirements for each part of the project

This starts out as a list of features/changes/improvements that we want to make. I try to be as specific as possible while keeping it as simple as possible. I’m not creating super technical requirements. I want the team to read them and be easy to understand. Often people think requirements need to be really technical with crazy numbering systems but I try to keep it simple and explain what we’re trying to do and why.

3. Clickable mockup or prototype

Even though the mockups aren’t perfect, it’s good to let the team have access to the clickable mockup. Now our developers don’t like to start until they’ve seen a mockup or we’ve already dropped the front end code in for them. We use Invision for this, which has worked out great for us.

4. Screencast with voiceover

Since we’re a remote team I actually use screencasts all the time. It serves as my way to present my work to the team. Even if you aren’t on a remote team it’s a good method to share workflows and interactions. It also allows your team to watch it when they have time and are most focused. They can also watch it over if they missed something.

It’s also helpful as many times my mockups are pretty low fidelity so I know where to click and can really convey the solution as best as possible.

My app of choice for this is QuickCast.

5. Links to documentation and/or conversations

We almost always have documentation or conversations that lead up to the creation of the design doc. This could be a card from Trello, our high level project management tool, a link to a UX heuristic evaluation results from our UX researcher or any number of other places that we might discuss or brainstorm about features. It’s helpful to link to these from here and even reference them in your documentation.

It’s also nice to link to all your mockups in this side bar. It creates a centralized place to find mockups for any given feature.


This is all about improving your teams communication. Creating this centralized place to define a feature and refer back too when needed is very important. It’s something that will surely evolve over time and you’ll find things that are more helpful for your team and workflow. So start here and see where it takes you.