How GitLab Pages made our Sketch design handoffs easier and faster

Nov 7, 2019 · 9 min read
Pedro Moreira da Silva GitLab profile

One of the designer’s responsibilities is handing off the design to developers so that it gets implemented as intended. We have design specs to make this process smoother, but these have their own set of challenges. How can we speed up and ensure an effortless transition from designer to developer, so that people can focus on what they do best? Here’s how we’re doing it with a combination of Sketch Measure and GitLab Pages.

Along the development, it’s natural that developers have questions and the designer should be there to answer them. A lot of these questions can be answered by the design specs, which mainly include detailed instructions about visual aspects, but can also have functional aspects. This guidance is a crucial part of handing off a design for implementation. Without it, the developer has to deal with a lot of guessing and manual work, which is not the ideal workflow.

Our workflow at GitLab

For more than three years we have been using a specific workflow, made of open source tools, to power our Sketch design handoffs. This workflow is how we handoff designs to build not only our product but also the Pajamas Design System. In a nutshell, here's how that workflow usually happens:

  1. Use the Sketch Measure plugin to generate specs from the designs we have created in Sketch (our user interface design software of choice).
  2. Commit design spec files to our GitLab Design project on, using Git.
  3. Once the files arrive on, GitLab's continuous integration (CI) engine starts and triggers the GitLab Pages feature.
  4. GitLab Pages then publishes an online index page with all of the design specs.
  5. Designers can now easily share a URL with the design specs, that is always up-to-date and that anyone can access.

Using this design handoff workflow we’ve been able to improve efficiency and communication between designers and developers. Having these tools in place and continously going with this workflow is one of our first steps towards practicing DesignOps: “principles and processes to assist designers in becoming more productive and collaborative.” Arguably more about tooling and automation, this workflow also blends three other important pillars that make high-performance design teams: process, standardization, and collaboration.

Creating design specs

The first step in our design handoff workflow is getting our design specs, using Sketch Measure. Sketch Measure is a free, open source plugin for Sketch that automatically generates specs from your Sketch designs. With one click, it outputs an HTML page that allows anyone to inspect all the design details, including CSS styles. This HTML page can be viewed online or offline, in all of the major browsers – check out a demo.

You can even add implementation notes to your design, so developers don’t have to look in different places for the information they need.

Example of an HTML page with the specs generated by Sketch Measure Example of an HTML page with the specs generated by Sketch Measure.

Just by using this plugin, we’re already saving money and time:

Other tools also generate design specs from Sketch files, but we settled on Sketch Measure because it’s free, open source, and allows us to save and version control the design specs in GitLab. If you’re interested in alternatives to Sketch Measure, see Marketch (a plugin similar to Sketch Measure), Abstract, Avocode, InVision Inspect, Markly, Marvel, or Zeplin. In June 2019, Sketch announced that they’re “bringing an Inspector to Cloud, so you can grab code, view specs and download production ready assets, without having to open the Mac app,” so a Sketch-native solution may be coming soon.

Sharing design specs with GitLab Pages

Now that we have the design specs, the second step is getting the specs into the developer’s hands. Wouldn’t it be great if you could just access a URL that’s always up-to-date?

Enter GitLab Pages. It’s a feature that creates static websites for your GitLab projects, groups, or user account. You can use it for free on or your own GitLab instance. It supports any static website generator, but in our case, we just need it to host our simple HTML file with the design specs.

In our UX department, we use the Git repository of the GitLab Design project to store and host not only the design specs but also editable Sketch files. Every time someone adds or changes design specs in the GitLab design repository, the GitLab Pages feature updates the project’s website automatically.

The automatic updates is possible thanks to a simple YML file in the repository that gives instructions to our continuous integration (CI) feature, the engine that powers GitLab Pages. In essence, that file tells CI to run GitLab Pages each time something is pushed into our default branch. If you’re interested in how it works, we’ve added comments to the file that try to explain it as simply as possible: .gitlab-ci.yml

The final result is an index page with links to the different design specs that are generated, as seen in the image below (feel free to explore). Since making this work for design specs, we’ve also added support for Framer prototypes and plain HTML pages.

Screenshot of the GitLab Design index page

By setting up GitLab Pages with GitLab CI, just push your specs to GitLab and the rest is magic. The specs are available to anyone through a URL and are easy to share anywhere.

For us, this means more savings!

Here are other cool things you can do with GitLab to make design handoffs even better:

Mention issues in commit messages for transparency

By mentioning the GitLab issue in the commit message, a note is created in the issue to let everyone know that the specs are available or have been updated (live example). This also makes it easy for people looking at the issue to contribute and fork the design (especially important if someone on the team is out-of-office), by following the link to the commit. This crosslinking feature not only supports issues but also epics and merge requests.

Example of an issue note linking to the referencing commit

To automatically mention issues in commit messages, we’ve created a prepare-commit-msg Git hook. Once the Git hook is installed in your local repository, every time you commit, the hook will add the issues, epics, and merge requests IDs found on the staged files (and their folders) to the commit message body. For example, if a file or folder you’re committing contains gitlab#1337-… in its name, the commit message body will be appended with gitlab#1337, which references the project handle for GitLab and its issue #1337.

Look at previous versions of specs

If you want, GitLab’s CI can save all versions of the design specs, using job artifacts. This means you can go back in time and see what a previous version looked like inside of GitLab, without having to clone, revert, or download anything. Everything can be saved and viewed online. For example, here’s a previous version of our design specs index page, from September 2019, when Kyle updated some Sketch files and their specs (CI pipeline).

Also, because Git is used for version control, you can browse the whole history of changes made. No change is ever lost.

Future improvements

We hope this automated way of doing design handoffs pushes our UX department to continue exploring the role of DesignOps at GitLab, not only inside the company but also in the product itself.

Specifically about design specs, here are some things we are looking into:

Because GitLab’s CI is so awesome and flexible, we are even thinking about using it to automatically update our SVG icons every time we update them in our Sketch UI Kit (gitlab-svgs#1).

As we mentioned earlier, we don’t use this design handoff workflow exclusively for design specs. It’s the way our designers communicate any kind of deliverable with our developers. The deliverables can also be Framer prototypes or plain HTML pages. We hope that by sharing design handoff workflow we can help you and your team also work better and faster!

Thanks to Dimitrie Hoekstra for the initial setup that allowed this workflow and Alessio Caiazza, Marin Jankovski, Rémy Coutable, and Juan J. Ramirez for the continued technical support and keeping this repository’s superpowers awesome.

If you have any questions or suggestions, feel free to post a comment on the community forum, tweet at us, or create an issue in the GitLab Design project.

Cover image by Fleur Treurniet on Unsplash.

“How designers at GitLab use their own tool to speed up Sketch design handoffs” – Pedro Moreira da Silva

Click to tweet

Edit this page View source