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.

‍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?

📒 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]?

• ⏫ Major: It comprises newly added components, behaviors, sections, features, or any other structural changes.

• ⏬ Minor: Cover any visual polishing, asset changes, and/or fixes, plus any alignment or spacing related updates.

What are the different types of [Action]?

• ⚡️ Updated: For anything that already existed on the design but suffered a minor or major change (considering the impact);

• 🗑 Removed: Any element that was previously present on the design, but was removed;

• ✅ Fixed: Any fixes to assets, element positioning, visual artifacts, or other.

• ➕ Added: Includes any new sections, components, behaviors, or other.

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]?

• [Minor] Fixed top alignment of section “Name” as it was misaligned with the bottom section;

• [Major] Removed second section after the “Hero” as it won’t be live until May 2020;

• [Major] Added new pagination component to handle multiple results.

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.