How to Spec Designs for Success

Written by Brian Smith

Advanced design tools like Figma, Invision, and Sketch allow designers to build clickable, high-fidelity prototypes that demonstrate many of a product’s expected behaviors. Certain behaviors, however, cannot easily be demonstrated with these tools and require additional documentation for successful implementation. It is difficult to communicate complex animations or, for example, the desired response when a server is loading slowly. Quality documentation allows designers to provide developers with the information that modern design tools struggle to convey.

Getting Started


Collaborative, live documentation keeps everyone on the same page throughout the development cycle. Passing around PDFs every time a change needs to be made is cumbersome and can lead to miscommunication. (Note: Although live documentation provides a single source of truth, developers will need to be notified of any changes made after development has begun.)


We generally document design specs in Jira, but have successfully leveraged Google Docs and Confluence in the past. Below is our process for creating the documentation in Jira.


Creating a Spec Issue with Jira


Create a new issue with a descriptive title, e.g.

  • “Property Index”

  • “Add business hours to the Space Detail”

Avoid long phrases with extraneous words. The title should simply reference the component, action or view.


Writing the Spec


All spec details should live in the issue description, including images and other attachments. Below are details we generally include:


User Story

User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. They typically follow a simple template:

  • “As a [type of user] I want [some goal] so that [some reason].”

  • “As an Administrator I want to be able to create User Accounts so that I can grant users access to the system.”

  • “As an app user I want to be able to submit polls with premium features and be charged for them through Apple Pay and Google Pay so that I can poll the community.”


Acceptance Criteria

Acceptance criteria are notes on the conditions a feature needs to meet to be considered complete. This criteria can vary in complexity depending on the project, but often includes information on UI, interactions, animations, data, and exclusions.


UI

  • “The UI matches the mockup (see link)”

  • “First time users will see an empty state illustration and text”

Interactions

  • “Clicking edit transforms the view to an edit view”

  • “When clicking Save the user sees a toast notification”

  • “If the user clicks Cancel the view reverts back to read only with no toast notification”

  • “Navigation is disabled for logged out users”

Animations

  • “The page loads from top down”

  • “A skeleton loader should be used on the cards”

  • “When saving, show a spinner on the save button”

  • “If the page takes 2000ms+ to load, show an indeterminate linear loader”

Data

  • “Content comes from the Project Name API”

Exclusions

  • “The ability to collapse cards should not be implemented until the next release”


Mockups

Mockups are critical to convey the intended implementation to developers and clients. Include a link to all related views in the description. If the spec issue references six views, for example, the description should include six links.


  • List View (Read Only)

  • Save Menu

  • List View (Edit Mode)

  • List View (Saved)

  • Confirmation Toast

  • Error Toast


Demos

If a workflow is particularly complex, record a demo using a screen recorder and incorporate the video into the issue. In the future, this can be referenced by any developer who joins the team.


Assets

Providing the correct assets to the development team is critical to achieving the expected implementation. Include links to where the assets should be pulled from or attach them directly to the issue.


Relevant Hyperlinks to Code Repositories

If your design leverages any existing code repositories, such as Material Bread, include a link so the development team doesn’t waste time rebuilding functionality that already exists.


Approval

Every spec issue needs to be approved by the client before development can begin. This approval needs to be documented on the issue.

Have a Call


After the client has approved your completed spec issue, set up a call with the development team to review it. Update the issue with any changes that are required as a result of the call. If possible, record the call and include a link in the description.

Follow Up


Check in regularly with the development team to answer additional questions or clear up confusion. There is a 100% chance you missed something in your specs or didn’t explain something clearly enough. That’s OK!

Success


Building software is complicated. Creating thorough documentation will help ensure you won’t be pulling your hair out in six months when the app you so thoughtfully designed goes into beta testing and doesn’t match your expectations. The success of the team as a whole hinges on proper design documentation.


---
At FullStack Labs, we are consistently asked for ways to speed up time-to-market and improve project maintainability. We pride ourselves on our ability to push the capabilities of these cutting-edge libraries. Interested in learning more about speeding up development time on your next form project, or improving an existing codebase with forms? Contact us.

Let’s Talk!

We’d love to learn more about your project. Contact us below for a free consultation with our CEO.
Projects start at $25,000.

FullStack Labs
This field is required
This field is required
Type of project
Reason for contact:
How did you hear about us? This field is required