The Art of Avoiding War
How to effectively communicate design patterns to developers
Written by Jimmy Dyer and Josh Kimmell
War, divorce, bad user experience…
Poor communication can be blamed for all three. In software development, ineffective communication between teams often leads to a tragic outcome: incomplete and unusable user interfaces.
Communication between designers and developers on a team is critical to the success of a project. In a world where the user experience is arguably more important than architecture and features, each disparate contributor must strive to work with others as one team to deliver a delightful experience for a common user. Setting expectations and being transparent with team members is a large part of that. Unfortunately, these expectations are sometimes incorrectly set. Designers expect developers to deliver their pixel-perfect mockups in code. Developers expect designers to deliver responsive and accessible screens that consider all the logic that goes into developing the experience.
In order to set these expectations, there are communication solutions, like Agile, that exist to tackle whole-team alignment. Unfortunately, Agile alone falls short for many cross-functional teams designing software, especially those that haven’t adopted strict Agile methodologies or utilize a hybrid version.
Designers and developers need a way to understand the designed experiences and deliver the desired user value.
Meet developers where they live
Most development teams have a consistent place to access documentation for their internal processes. The goal is to have a single source of truth for the design patterns, one place that developers can go to easily access design assets from the tools they use every day. Our team at IBM uses Github, but in other cases, it could be products like Jira or some other development resource. This removes barriers to entry by utilizing a tool that developers already use and creates a structure that they are familiar with in their day-to-day jobs.
Within our team process, all development stories are required to link to the assets delivered by the design team. This includes making sure all delivered designs are up to date, including content, layout, components, and user flows. Any previously delivered designs are archived so team members can review past decisions, if necessary. In order for designers to effectively communicate the desired outcomes to developers, there are certain pieces of content that should be included when delivering patterns.
“I used [the pattern repo] as a reference whenever I needed to look something up and the structure of it was very consumable, […] I didn’t need much time to find the thing I was looking for.”
– Stefan Walter, Front End Developer, IBM Security“The documentation on the UI designs and UX patterns is very thorough and a great reference while I’m working to implement the design patterns. I believe that it makes all design decisions public and consistent, which I appreciate.”
– Diego Hernandez, Front End Developer, IBM Security
Deliver based on user needs
A common mantra among product design teams is “we are not our users.” Something that brings developers and designers together as software professionals at IBM is that everything we deliver must address the needs of our users. In order to do that, designers and/or researchers often conduct generative user research to understand those needs before starting to explore solutions. It’s okay to make assumptions when starting out, as long as you validate those assumptions with real users before delivering the experiences. What steps do they currently take to complete a task? What are their pain points along the way? What would an ideal experience be?
Until we fully understand and document the user needs, it’s difficult to present a solution that has value to the user. Documenting user needs helps to set the stage for why decisions were made. We do this by listing the user needs to be addressed with our solution at the beginning of the documentation. This frames the developer’s work around the needs of the user and gives them context for what they are building.
Additionally, we break the layout into answers to questions the user would ask. This helps developers better understand why certain decisions were made in designing the experiences.
Share artifacts
Part of meeting developers where they live is speaking their language when sharing artifacts. This language mainly consists of common UI components. When designers document delivered experiences, they should identify the available components and any new components needed to deliver the full experience. Leveraging components from an existing library means no duplication of effort for the developers and helps to ensure that the delivered experience meets designers’ expectations.
Developers also need to see where designers live, starting by accessing the latest design source files and if needed, redlines. Some front-end developers on our team have access to our design software, Sketch, so they can grab assets like images, icons, hex values, etc. When the developers don’t have access to the design software, designers should provide artifacts marked up with design specs. For Sketch users, there are plug-ins, such as Sketch Measure that eliminate the need to manually mark up design files. It allows a designer to export artifacts directly from Sketch, enabling the developer to inspect padding between objects, typography, color, and CSS values straight from a web browser.
“The exports with all the measurements of margins, paddings, font-sizes/classes, … also are essential.”
– Stefan Walter, Front End Developer, IBM Security“All of the artifacts are very helpful especially Sketch files and GIFs.”
– Diego Hernandez, Front End Developer, IBM Security
Share guidelines
Without documented guidelines, developers find it difficult to deliver a seamless user experience. They simply don’t have the context required to do so. They ask questions like: “What happens when I click this?” “How should it transition?” “What do you think about the placement here?”
To answer these questions before they come up, designers should give as much context as possible by creating guidelines for user experience, layout, states of design, and interactions.
User experience guidelines should include the high-level flows and models of the user journey from point A to point B and all of the different paths a user can take in order to meet their needs.
Layout guidelines should include examples of the full layout with your design in context. If flows are delivered, then the layout will also correspond to each screen in the user’s flow.
State variations should also be included in the delivered design. For example, if you’re delivering a button component, then it should include all states of this component (e.g default, hover, focus, and more).
Interaction guidelines should include examples of the different transitions derived from the states of the design. They should also list actions the user takes and how the interface responds to those actions. This could include a full animated prototype of the user flow.
Creating guidelines is an effective way for designers to avoid sending “pretty pictures” of interfaces and image assets to developers without context, which often results in more meetings to explain design decisions and, ultimately, discord between contributors. Guidelines should clearly communicate to developers the context of those assets and define the outcomes for the user.
“Just by browsing that repo you’d get a good grasp of the overall concept, lots of visuals of how the single pieces fit in the whole concept.”
– Stefan Walter, Front End Developer, IBM Security“With the Patterns documentation, it serves as an additional navigation tool, in the sense that it allows an engineer to find a visual landmark, […] and see what’s been delivered. This provides us with stronger clues of where to look in the source code.”
– Randy Tolentino, Front End Developer, IBM Security
Documenting design patterns allows designers and developers to avoid war by making designs consumable, promoting collaboration, and ultimately building empathy for each other and our users.
“[…] what I appreciate most about the Patterns work is that it shows a tremendous amount of effort by the designers to meet engineering in the middle. It’s as if the design team is saying, ‘we’ll try our best to give you every spec you need, in order for you to do your best at building out a component or an experience.’ This intention, to me, is the most valuable takeaway.”
– Randy Tolentino, Front End Developer, IBM Security
Feedback is welcome and appreciated. Special thanks to Esteban Pérez-Hemminger and Carly Price for editing and moral support, and thanks to all the developers for working with us to deliver our patterns to our users.
Josh Kimmell and Jimmy Dyer design amazing experiences for Security at IBM, based in Austin, TX. The above article is personal and does not represent IBM’s positions, strategies, or opinions.
