How to guarantee team alignment using Zeplin commits

Design handoff is the moment where all the little pixels are shared with the Engineering team to make them come alive. This is an ongoing process that should be respected as much as the final result. We use Zeplin to help us with this.

During and after the handoff process is done, there are many common situations that can lead the design team to update a certain design: May it be a missing asset, a last-minute change, a component fix, a consistency update. The list goes on.

This is usually very minor stuff unless a big change happens mid-way, which is somewhat rare. We always strive to have everything with the utmost quality, and that’s why even the smallest inconsistency should be fixed, even if super obvious.

Designer: Have you seen the updated designs?
Developer: Wait.. updated designs? When? Please don’t tell me they changed.

A pretty classic situation, right?

⏭ Fast-forward to now

Let’s be honest. Without proper specification, it can be hard for developers to keep track of every design update — some changes can be missed, especially if the updates are very minor that only an eagle eye can notice. And here comes into play Zeplin’s versioning feature.

With Pixelmatters growing steadily, it became clear that what was working for a team of 10–20 people wasn’t as seamless as it should once we became 40. Everyone had different needs when it came to understanding the status of the design:

  1. The Engineering team needed to quickly identify what changes were made in order to make sure it didn’t impact the current sprint and what was being currently implemented;
  2. The QA team needed to understand which changes to look for in a given screen in order to test them appropriately (if new);
  3. The Marketing team needed to understand the details of a specific screen to identify what’s new and what were the most recent updates, allowing them to make sure our portfolio was filled with new and approved designs and not any legacy.

🤝 Meet our Zeplin Commit Guidelines!

Well, how does one guarantee full alignment among all teams? With clear (but not too granular) specification, following a series of guidelines to guarantee consistency across the board.

To do that, the Design department created a document that outlines the best practices when doing it. It’s called… (surprise, surprise) Zeplin Commit Guidelines.

Let’s dive through it, shall we?

First, start with the 🧠 mindset. This sets the tone and helps each designer question why a certain commit is being written.

🧠 What’s the mindset?

It’s important that each designer questions themselves about:

  1. What has changed in the Design?
  2. Why were these changes made?
  3. What should Engineering and QA look for?
  4. How to give visibility to the Marketing team to these changes?

Then, we move over to explaining the different parts that compose a commit message — Its 📒 anatomy.

📒 The anatomy of a commit message

Each commit message should be composed of 3 different parts:
[Impact] [Action] [Description]

What are the different types of [Impact]?

What are the different types of [Action]?


When a new page is added to Zeplin, we just add an indication using “New Page” in the description. This helps the Marketing team understand if a page from a certain project is new rather quickly.

What is a clear Commit [Description]?

Whenever writing a commit description, there are 3 things to have into account: It should be concise, clear, and immediately identifiable.

These are good examples of commit messages:

An almost seamless adaption

As with any other new process, it’s fairly normal to have a slight curve of adaption throughout the team. Fortunately, this was something that was quickly incorporated within a couple of weeks and is now part of our technical onboarding process of any designer.

Follow Pixelmatters on Twitter, Facebook, LinkedIn, and Instagram.

Luís Monteiro
Design Director

Because, every pixel matters.

Let's talk