Menu
Menu Sheet Overlay
Search
Search Sheet

Design Documentation

In this section learn how design documentation can further your communication to engineers.

Clearly communicate

It is important to clearly communicate your design vision and specifications to the development team in order to avoid any confusion or uncertainty. We suggest that you create a prototype, as well as a design handoff document in order to communicate intentions.

Inconsistency in the high fidelity mockups can lead to unnecessary complexity in creating custom CSS. It is best to reference the styleguide and variable documentation versus measuring specific spacing or font sizes.

Each team and organization will have their own process and procedures relating to the design handoff. We recommend the following best practices during handoff:

Design Systems

To help your developers translate your design to code, create an iron-clad design system. Ask yourself:

Maintaining a system will make it much easier for your developers to code your designs, and maintain in the long-term.

The layout on the right uses this system:
The base unit of spacing is 4px, meaning all spacing units would be multiples of four.
Extra small space 4px
Small space 8px
Medium space 12px
Large space 16px
Extra large space 24px
Design System

Creating a Design System

The best systems are derived from a minimal set of rules, which encourages consistency and visual rhythm. A lot of the systems work we’ve done is around layout and micro-layout. A layout describes the arrangement of components (discrete pieces of the user interface). Micro-layout describes the arrangement of elements within components.

Here’s how you’d get started creating a design system:

1. Choose a default font size

This should be the body text size and be large enough to read on small screens at the typical viewing distance. We recommend choosing 16px for this value. This is because Google's Lighthouse audit takes font legibility into account, and broad use of fonts that are below 16px in size will result in an SEO penalty. We generally consider 14px and less to be too small for body text as most people don’t have perfect eyesight, and anything below this value is difficult to read at an average reading distance. (For more information, read Typography In Ten Minutes.)

2. Choose a default line-height and leading increment

The default line-height should be derived from the font-size and the typical line length (measure) of the text.

On phones (mostly in portrait), the measure is short, and doesn’t require quite as much leading as long line-lengths as on desktop.

A line-height value for desktop of 1.4–1.5 is a good starting point. For most of our designs, we’ve used something between 1.25 and 1.4. Usually, for a size with 16px font size, we’ll use a 20px line-height (but your own typesetting may vary depending on the font used).

The leading increment determines your other possible line-height options. It should be the smallest sensible factor of the line-height; you should usually go with 4px (20 Ă· 5 = 4). That way it allows more flexibility in setting incremental leading, and is an even factor of the unit as well.

Line-height
Leading increment

3. Choose a basic layout unit that is a multiple of the leading increment

Usually you can use 8px. The layout unit is used to define a grid over the viewport that acts as scaffolding. Components should align to the grid, or, if necessary, halfway between grid lines. In our stylesheet scaffold, the layout unit is simply called "unit."

Unit values

More Decisions to Make

Many other decisions can now flow from these initial three:

Typographic scale

Creating a Styleguide

The styleguide records the logic behind your design system and any notes and you may want to communicate to developers. Start your styleguide before you start your mockups and adjust it as you go to ensure accuracy.

An example styleguide Example: https://invis.io/DC7MPAHAV

If you create your styleguide sections on artboards that the same width as your mockups, you can add them to the internal InVision project! That way it’s easy for developers to find and ask for clarification (with comments).

This is the basic overview of the design system that will be used for the project. This will help in setting up the project and making sure that the design is consistent throughout. Styleguides should include content relating to:

Design Mockups & Assets

Provide links to the design mockups and supporting assets you have created as you progress through sprint work. Links might include:

Writing General Design Notes

Design notes should detail a walk-through of all interactions, elements, and components. General design notes should start by documenting all the global elements and components referencing specific asset names and variables so that the development team can easily cross reference as needed.

Example

Header design documentation example.
Documentation for a global header design element.

Once the general global documentation is complete further documentation should match the sprint deliverables for the project.

Third-Party Tools

The following are a couple tools that we’ve used here in the past at Mobify. These are completely optional, but you may find that using these tools can save on a lot of back and forth communication between designers and developers.

InVision Inspect

InVision Inspect is a web-based design inspector that integrates with InVision. We strongly recommend providing designs using InVision Inspect. It provides many of the features of Zeplin, whilst being fully integrated into your InVision prototypes. Using InVision Inspect is as simple as uploading a .sketch file, or syncing your .sketch file with InVision Sync, or pushing up individual artboards with CraftSync. Read more about InVision Inspect.

InVision Inspect
A screenshot from InVision Inspect

Zeplin

Zeplin is a design specification app that provides both a native and web view. Zeplin is meant to bridge the gap between developers and designers by providing a detailed inspector that reveals design details that include (but are not limited to), colour values, spacing values, icon asset export, typographic specifications and more.

A screenshot from the macOS Zeplin app
A screenshot from the macOS Zeplin app

We don’t use Zeplin at Mobify exclusively, but this can be a handy resource when in mixed OS working environments. For example, if designers in your organization work in Sketch for macOS, but developers work on Windows, cross-platform Zeplin would resolve the issue of sharing .sketch files with Windows users. (Sketch is available only on macOS.) Read more about Zeplin.

Sketch Measure

Sketch Measure is a free plugin that provides many of the features of InVision Inspect, including colour values, spacing values, icon asset export, typographic specifications and even Sketch defined comments. Note that if you export design specifications using Sketch Measure, you’ll need to webhost the outputted HTML markup and associated assets for easier sharing. Read more about Sketch Measure.