Designer handoff that will please the developers

Introduction

This is an article I wrote while working at Develocraft to share with our client's designers and show my approach to delivering designs.
‍
As a designer, one of the most important aspects of your job is ensuring that your design is properly implemented by the development team.

A smooth handoff process is crucial for this to happen, as it helps to ensure that the final product accurately reflects the design vision. In this article, we'll go over some of the best practices for design handoff and deliverables structure, to help you ensure a seamless transition from design to development.
‍
There is a popular saying between the coders:
"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live."

Be aware that the same psychopath may have to use your deliverables.

Taking care about people who will use the effects of your work makes it much more refined and professional. It is essential to prepare your deliverables in a way which will allow them to “live” without your assistance.

At Develocraft we are frequently improving our client’s design files, as many of them are lacking the proper structure and do not allow efficient development or further design. Main problems we experience are:

Inefficient or no use of the components
No styleguide or arbitrary usage of the styles
Lack of documentation, especially about user flows and design decisions
Bad or inefficient solutions in terms of responsiveness and multiplatform usage
Scattered information or wireframes in the design file
Missing edge cases coverage or missing design elements

We are those “psychopaths'' who are left with “final” designs that are extremely hard to work with. In the majority of such cases, this situation is not caused by our client's intention but by the designers / design studios they’ve worked with.

The design process can take many turns, including large overhauls or minor “pre-launch” changes. Without proper diligence it is easy to incorporate chaos into your main information sources. This chaos might get away unnoticed as the people involved are in constant communication and all of the important information is in their “shared mind”.

Complications arise when there is a need to include new people to the project or some of the initial creators are missing. Unfortunately, the handoff area is often omitted or just just scratched in design courses / materials. Many designers won’t even see the need to go anywhere beyond a wireframe.

Treating your design files as a strong supplement to the documentation or as the documentation itself will greatly benefit different areas of your project / product.

Those areas include:

Design creation and management - with components and styles in place maintaining consistency is fast and easy. Creating and iterating new ideas is also faster and more refined as there is already a great starter set that a designer can use.
Communication with developers - when a designer does empathize with the developer and covers the information layer efficiently there is a high chance that the design implementation will go as planned. It will also reduce the overall level of required meetings to clarify different matters. Misunderstandings extend the development time, the bigger, the more costly it will be.
Project management - if your design files are able to clearly communicate user flows, UI behavior and support task creation/evaluation (by the developers), you contribute to faster and better implementation of your ideas. With the ability to understand the purpose of the design right from the place where it happened, the design files will serve everyone and allow seamless introduction of new people working with it.

Design file

Design file that will make a happy developer

We know that in most cases, your team has limited time to deliver designs and development.

We’ve seen the memes about lacking code documentation and it is certain that you could apply them to the design area.

Having a solid workflow will allow you to create wireframes and prototypes faster, which will grant you additional space to cover the handoff part better.

In this article, by design file we refer to an exported file or an online file that can be accessed via design/handoff tools like e.g. Figma, Adobe XD or Zeplin.

What information should be included in a design file?
Your handoff should allow anybody to move further with the project without your personal assistance. The level of information detail will vary depending on the project team, deadlines and project specifications. There are however things that will make your delivery stand out.

In general the information about a project should be held in a written form that serves as a single “source of truth” (e.g. in Confluence or Notion). Your design file should be a supplement to this type of documentation. Unfortunately it is rare to have such workflow in the majority of projects. It can even go to the extremes of having only the design file and a chat history.

What kind of information should a design file contain?

Styleguide (colors, typography, icons, grids, logos, brand graphic elements)
UI components (e.g. inputs, menu’s, page sections)
Wireframes & prototypes of user flows
Edge case examples and error states (e.g. 404 page)
Animation description (if complex animations are planned)

What will make it even better?

Information architecture diagram
User flow diagrams

During your work you might create a lot of other artifacts and documents, like for example User Personas or Heuristic Analysis.

Those deliverables are accessed by way more people than just the developers and it is better to store them in a more accessible form (e.g. pages in Notion, presentations or documents).

Just keep in mind that nobody will be able to reverse engineer your user interviews or workshops as they were not there, so prepare summaries that allow everyone to understand the effects / findings of your endeavors. Remember also to store/bundle everything in one place/package.

Styleguide 101

Colors

A developer should be able to enter one place, find a full color palette used in the designs and then spend some time creating a code stylesheet. After that there shouldn’t be any hex or rgba values used in the code, but variable names.

As a designer you should prepare it in a way that does not require any additional explanations. Color naming conventions can vary, at Develocraft we find it much more convenient to have different tints and shades follow a numeric order. It is much easier to communicate and comprehend the scale of change from e.g. blue100 to blue300 instead of mistyBlue to crayonBlue.

Our tips:

Create tints and shades for any color you use - don’t leave just one tint of “orange” - treat your color palette as a system, which should be dependable and leave no blind spots
Combine the palette in one place in an easy to copy format - don’t just leave patches of colors - attach name and its value to it. You can also prepare a text layer with the whole palette in text format (color name + value).
NEVER use opacity for your tints and shades - this a huge mistake that many, many designers do - again, your palette should be dependable. It might sound fast and easy just to create colors based on opacity but they will change on different backgrounds. If you use some transparent overlays, it’s okay to have them in such a form. However your main colors should look the same on every background.
Depending on the use case, consider writing down colors in hex or rgba format. In most of the current design tools a developer can preview both, but writing it down will save a lot of time.
Create an accessible palette - there are tools and approaches that will allow you to create a color system that meets WCAG contrast requirements. We for example have a system that allows anyone to understand when something is more or less likely to be readable. For example any color with 100 in name paired with any other color with +5 tone difference (like blue100 background + gray600 text) will meet the contrast criteria. It’s not perfect as WCAG contrast can be misleading but still provides us a solid foundation to create a more accessible UI. Most of the designers skip this part and don’t feel the need to even check contrast as it just “needs to look good” - don’t be such a “designer”

Typography

Similar to colors, typography shouldn’t be just a bunch of text styles but a solid system that is easy to apply and can incorporate changes without breaking the layouts.
Most of the developers have never used any graphic tool and many designers don’t know much about CSS/Style props and the general technical part of font rendering.

Such a situation creates an open space for miscommunication and frustration.
The designer is the very first guardian of the pixel perfect design as well as the person responsible for assuring that the layouts won’t break.

Proper communication about typography will make both sides happy. With just a little knowledge about CSS you can prepare the typography documentation in a much more reliable way.

Sweet mother of height…the line-height

Line-height property defines the space taken by a text in the rendered page. Many designers focus only on the font size, leaving the line-height property on auto. By leaving it unattended they expose the layout to be much more out of control and easier to break.

Line height in typography should be an element of a bigger UI structure that is combined of typography, grids and spacing system. If you are using a 4px or 8px grid be sure that your typography styles will follow it too. Otherwise spaces in your UI will get non intended spacings (eg. 15px instead of 16px) and the harmony will break.

Line height does reserve space in the rendered page/app element. When you change line height in your design tool, you will see that it does not affect the font’s visual size, but now the text layer occupies more space on your wireframe.

By taking care of the line height and adjusting it to the general grid system you will create a reliable layout. Imagine a situation where by any reason the original font can’t load, the device will try to fallback to another font, that font can have a different default line height and boom…everything is out of place now. Custom line-height will also help if you decide to use a system font, which is different from system to system (Android, iOS, Windows, Linux, etc.).

Add line-height value to your typography style description to allow the developer to add it to the style without any additional guessing.

Bold, Extra Bold…font-weight communication

Defining font thickness can be tricky, we are all used to selecting it by names like “Bold”, “Light”, etc. Developers can also use those properties in code but unfortunately not in every case.

For example, when there is an app created in React Native, there is no support for properties other than “normal” or “bold”. A better way to convey the weight property is to use numerical values.

Each font-weight number corresponds to a different name. Font-weight: normal can be also written as Font-weight:400. Using numerical approach does also contribute to the communication, similar to colors, it is easier to imagine the amount of reduction from 900 to 400 instead of Black to Normal.

The size does…vary. Rem vs PX.

Most of the design tools do not allow it to operate in rem sizes. That is not an excuse to not use them, the benefits are worth it!

Rem refers to “root-em” size, which defines the font-size relative to the root element. It can be specified in the CSS (changed) but by default most browsers use 16px as the default size (which can be translated to 1rem).

That is some tech lingo, forget it!

As a designer, you should understand it as it contributes greatly to the accessibility features.

By specifying sizes in pixels you do not allow your elements to be influenced by various browser features. A person with vision disabilities might set a larger font-size in the browser settings (changing the root font-size), with sizes in pixels, your UI would remain unaffected (requiring additional zoom).

Rem’s also make it easier to hold spacings intact and increase their consistency. Remember that it is ok to have some of the UI elements be specified in pixels, don’t sweat the small stuff :)

Icons

One of the fundamental elements of today’s interfaces is still treated poorly. Icons are not just an embellishment, they support typography or even replace it in some cases. This means they should be a part of a larger system and also be treated accordingly.
Let us go through the most common issues we find in our client’s files.

Icons floating in space - no bounding boxes

With so much care put into typography, the sizes and the alignment to a rigid grid you should not forget that this meticulousness should also apply to icons.

Proper icon has not only the shape in it but also a specified “space”. The most common size for the icons is 24px x 24px. As you might notice the shape inside does not occupy all of the available space in that “box”. Bounding boxes are essential to provide consistency and most of the available icon sets are created with them.

However we see a lot of projects where icons do not have them. Either they were badly copied or just designed in that way.

It is painful from a developer perspective, as the sizes are unpredictable and each icon requires additional care in terms of placement. If the developer will not show enough passion for a pixel perfect design - your UI elements can break the visual harmony instead of supporting it. Icons might end up misaligned, influencing spacing and sizes of other elements, destroying your spacing guidelines.

No icon documentation

Whether you use just a few or want to upload the whole icon library to your design file. If it is an external library, not created specifically for the project, always leave the information about the library name and where it can be found.

The project might grow without you in the future so allow others to contribute to the UI consistency by using the same library.

Using raster (.png, .jpeg) icons instead of vectors (.svg)

Just no. Please. Icons should be scalable and look perfectly clear all of the time. You need vectors for that.

Additional icon tips:

You can use different strokes to match font weight - if you use stroke (not fill) type icons, you are able to adjust the stroke size. Bolder fonts tend to take too much attention when paired with thin text. Just remember to use full width sizes as your 1.5 stroke will be rounded up to a full number.
If you are using Figma and icons in your prototype (in e.g. buttons) do not change color properly (as intended in the component), make sure that all of the layers in the icon have the same name (change e.g. “oval” to “path”) and be sure to apply a color to an icon (override the default one) in the component.

Grids

Grid systems and proper RWD designs, despite being taught at every professional UX/UI course, seem scarce in many files which we receive at Develocraft from our clients.

Most common problems include:

Lack of general grid system (4px / 8px or any other) - where every element seems to dance it’s own dance
No or improper column grid - RWD is great but it shows the full potential when it is calculated properly. There are so many grid calculators that allow proper adjustment of the column widths, margins and gutters. The worst thing that can happen is an uneven grid, where columns do not have the same widths (as they should). Unaware designer may align elements accordingly to the columns, which will lead to different element widths, confusing the developers.
Grids as shapes in the wireframe background - where possible a designer should use the design tool’s own grid creation features instead of workarounds. It is ok to provide an example wireframe for the developer if the preview options in the tool do not allow to see the grids. For the wireframes it only makes the design and preview harder because the grid indicators (created in such cases as shapes) interfere with the proper UI elements.

We also recommend creating components with similar heights. Especially if you use a grid system. Many designers have too narrow a focus when creating UI elements. This leads to situations where there are several elements inline (e.g. search input, dropdown and a button) with different heights. Our minds love harmony and don’t like when we make them think.

UI Library

Creating a component library that is easily accessible and contributes to a fast and coherent creation of wireframes is a must. A designer can choose to create their own or use something that is already available (UI set).

Which approach is better? It depends:

When there is significantly small time for the development - you might choose a library that is available in the design file form and as a code repository (e.g. Google Material, Bootstrap or Tailwind). This will allow you to kickstart high fidelity designs and from the developer perspective go straight to the creation of specified views/pages.
When you want control - At the moment when you have to do even the tiniest element differently, which is not supported by even a large UI kit - it becomes useless. That is why we in general try to create a small UI kit for our clients and build it up as the product scales. With this approach we have full control as well as flexibility. Developers also appreciate the fact that they don’t have to go through a bloated library to find specific UI components.

We choose control (own UI library) over kickstart (use premade library) also for the reliability reasons. Unfortunately, even commercially available (and popular) UI component libraries can be full of flaws.

The absolute worst scenario is when a design file library does not 100% match with the code components (e.g. buttons with different sizes). You may choose to “update” it on your own, but this will soon look like drowning in sand. A Front-end developer that will be recreating your designs into code will also get frustrated as it will become impossible to convert your work as you propose.

Big UI kits often are built with a code component focus, which might influence the design file - a developer can have more components or updated versions of what you see in the library in your design tool - making it harder to cooperate efficiently.

There is also a large pool of UI kits that do not have its code equivalent. They might jumpstart the design creation. However, a designer has to analyze such a library and “learn it”. This also can cause inconvenience for the developers, if you use a large UI set with hundreds of components - the developers won’t be able to clearly distinguish between what is used in the designs and what’s not. Coding the whole library of UI elements is the worst that can happen. Your developers might create something that will never be used. Imagine shooting a mosquito with a cannon.

Naming conventions

We have already pointed out how good it is to improve the communication about colors and typography with a proper naming. This is even more important for the UI elements. A developer previewing an element should be able to understand the state of it and relation to other components. Even the simplest naming system is better than a random poetry and influences the proper usage of UI elements.

Naming in the design file should overlap with the one in code. If the developer doesn’t have to “translate” one into another it smooths the communication and the comfort of working.

State coverage

Equally important as the naming system is the level of state coverage. For example if you design a button and just provide a default and hover state for it, the developer might get confused about what to do with the remaining ones.

Some developers will try to create something out of their invention and others will just leave it and rely on e.g. browser default styling. Keep in mind that experience and set of behaviors can change between devices and your UI library should cover it.

For example when designing web apps be sure to provide information / cover states of tapping an element.

Make sure that there is no guessing about your final output. Otherwise you open up space for chaos and misalignment between design and code.

Don’t scatter

This is an absolute pain in the ass when you receive a UI kit, open it in a design tool and there is no option to preview the style guide and components in one place. Colors are in one page, typography is in the other and even the smallest elements like radio buttons have their own page. We get it that it provides additional structure but imagine a blog with dozens of categories and subcategories where in each category there is only one article.

We find it better to have all of the UI elements in one page as this allows a developer to enter it and see how much work there is to do. It is much easier and faster to evaluate the time required to cover all of the UI fundamentals. The developer after finishing the UI elements can then move effortlessly to coding what is in the wireframes.

We’ve seen extremes of UI elements being not only scattered in pages in one design file, but in many pages in various files. Most of the collaborative, online design tools allow having a shared library of components, so a designer can easily import e.g. radio button elements to a wireframe. This does not apply to the developer who wants to for example preview other states of this button. In such cases the developer ends up with several open tabs in the browser or design/handoff app. Keep it stupid simple, it will benefit everyone. The less jumping between pages/files/sites/apps the better.

User flows, edge cases and prototype

At this point, a front-end developer might already start showing signs of emotion, even sympathy. Let’s not forget about the back-end guys and other teammates. Depending on the project, your design file might be the only information about UI and user flows. Providing information about user paths is essential to avoid confusion.

Time and client’s budget is a factor here so there are few levels of delivering this information:

No information - just UI elements and wireframes - this moves the responsibility to the client / project manager, which has to explain everything to developers and any other team members. At Develocraft it is the most common form of delivered design files from our clients. Often we need to use a mix of reverse engineering and extensive calls to understand the logic of some features. The worst thing that can happen is that the client no longer remembers all of the details and in this case it happens quite often.
Prototype only - with current design tools it is so fast and easy to create prototypes. What is shocking to us is that we see this feature more likely being used by clients themselves than the designers. This is also an indication that it is unlikely that the designs were tested with the users. This is the most basic form of showing user flows, yet very powerful. The “Show, not tell” proverb is very radiant here. It is sufficient for very small projects that do not have complex logic in the user flows. You might even add additional descriptions around a particular wireframe or to a prototype step if needed. We combine prototypes with user flow descriptions to let everybody get the knowledge they need and also visualize it.
Description of user flows and logic - that is the most efficient way to cover the required information. It leaves no space for misinterpretation and typically is a result of joint work between designer and the client. Many clients are convinced that what they already have is enough to describe e.g. a functionality logic. A designer should be able to review provided materials. Situations when materials provide sufficient information are very rare. Blind spots result in development delays as developers need to get the information how something should work. Sometimes small “omissions” can lead to drastic results in terms of development time and cost. Unfortunately it can be hard to convince some clients to create flow diagrams and review them, but that does not mean you shouldn’t try.

It is good to have user flow diagrams or at least wireframes linked in a prototype in your design file. Flow visualization can be done in other apps or written down in a document but in many projects, different people, even from different organizations will access a collaborative tool (like Figma) to assess, plan and do their work. The more documents, apps, online wiki’s - the harder it will become to efficiently retrieve information.

There are also projects where anything close to documentation will be your deliverables. Clients can insist on having their project managers, product owners and other management, but this does not always work best for them. Try to provide at least the bare minimum that will allow anyone in the future an easier start when they use your work.

Your experience and workflow optimization will have a huge impact here as it will be saving your time in the project.

Edge cases

Many designers tend to cover just the perfect state of UI components / pages / user flows. If they are lucky, a developer will ask them to cover what’s missing. Otherwise such a situation can result in broken layouts or non intuitive user paths, because something “weird” happened.

It is frustrating for a developer when the handoff does not provide answers, for example how a text input will behave when a user enters a large text there. By skipping this holistic approach to your work you make a developer obliged to do design decisions for you. If this is not intended it will result in lack of trust and cooperation between design as well as building up inconsistencies in the interface.

If your design tool does not allow to show some specific cases or you don’t know how to do it. Describe them (e.g. stretching text input or character limit). Any information is better than none.

Communication

Design is not a step in the product development process but one of the cogs in a machine that requires a perfect alignment with other parts to deliver great work.

A designer should start thinking about handoff at the very start, even when nothing is yet created. If possible schedule a call with the development team and let both sides learn about their needs and expectations.

If you just flush everything that you’ve created right into the dev hands, without even contacting them before, you create nothing more than a ping-pong table. Developer pushes back with comments, you push your vision, ping, pong.

By allowing others to create a shared process you allow a team to be created. You might even be a part of a “dream team", the best devs, management, analytics etc. but various project circumstances can negatively affect the output. Creating a space where everybody knows what the goal is and supports each other will provide the flexibility to counteract negative influences.

Let the developers know how you work at the very beginning, this can include:

Describing the approach to UI elements and component library - it is good to set a rule to use already created components as often as possible. Make devs comfortable with giving you feedback if they spot inconsistencies or when they have suggestions about a particular UI element. For some developers a profound componentization might be also their first approach to create such a library, be understanding and supportive.
Make sure they know how to use the design/handoff tool - don’t assume, ask your team if they know how to navigate and inspect elements of your designs. Make sure that everybody knows the difference between a component and non-component elements and what are the ways to preview their states or how to go to the full style guide. If you use prototypes, signalize it clearly and show how to use them.
Discuss the involvement in the design process and hand-off approach - be open to work closely with developers and signalize it clearly. Describe your role, how you plan to work and what you will deliver. Make sure who is responsible for reviewing the development in terms of consistency with the design and how the process will look like.

Your final goal is to have as less “oh”, “what”, “no way”,”whoops” and “#$@&” as possible during the development of your designs. Those designs can be “in production” phase immediately but often somebody might come back to them a year later and you may not even be in this project/company anymore.
‍
By taking care of other people involved in the project and thinking about the future of your output you show true professionalism. In reality, people in IT are not psychopaths (in general), but everybody can easily distinguish bad work from the good one. Creating an environment where working with you and your deliverables is a pure pleasure will make you remembered. This does not even mean to create ultra pro world class badass deliverables, simply avoiding an internal collapse of anybody that touches your work will be a great start.
‍
At Develocraft we have returning clients that want to come to us because of our delivery in their other projects / products. Your work approach and professional diligence is of the same value as your design skills.

Design Files that will make Devs fall in love with your work