Smarter design handoff — building an automated assets pipeline from Dropbox to GitHub

With the rising popularity of Design Systems, we now have a plethora of tools that aid the design handoff process. Developers can directly copy applied CSS styles on a component, use red-lining to inspect spacing on a design, or even download assets from tools like Abstract or Zeplin directly.

Truth be told, the design to developer handoff has never been something that is inherently granted by having a Design System, it requires communication and coordination between both parties. There are still a lot of gaps in the process and keeping assets up to date is one area that could be improved. Traditionally, if a designer makes a change to an SVG icon, they would have to inform a developer and transfer that SVG into the developers' hands, who would then upload it onto the code base in the required format. In Design Systems we speak of having a single source of truth, how do we make sure it is up to date with the least manual effort?

One of our designers at ClearScore recently designed a full icon set based on our new typeface, CS Clarity, and he raised the need for an icon pipeline as part of the rollout. My instant thought was, can’t the designers just upload the icons to GitHub directly? Yes, except it is not scalable at all. We have almost 200 icons and each of them has different states like solid, outlined, circle... We also cannot be expected to train every designer to use GitHub and code as the company grows.

The designer-developer assets handoff process

The pipeline

I first looked into out-of-the-box options like Zapier, Microsoft Flow, etc. But none seem to go as far as creating commits and pull requests. Moreover, we need to clean up raw SVGs that designers provide, therefore building our own pipeline seemed like the right idea. We could think of the icon pipeline as an input-process-output pattern:

Input — Our designers use Dropbox daily, the learning curve is low.

Process — Designers will provide raw SVGs with un-merged paths and extra bits. We can clean it up using SVGO on the pipeline.

We use npm to publish individual icons, therefore, we need to format the folder structure and namespace correctly, a corresponding package.json will also have to be added.

Output — A pull request on GitHub on a branch with the SVG changes ready to be approved and merged to master. Once the PR is merged, the SVGs are distributed as npm packages.

Illustration of icon pipeline concept

Dropbox API

The first step of the pipeline is receiving the input. We need to create an OAuth App on Dropbox:

1. Navigate to the App Console on Dropbox and create a new App. Select Dropbox API and whichever type of access you need. For me, I chose full dropbox access as I wanted people to just drop their icons in their usual folders. If you select App folder, your icons will have to live in the App folder that gets created by your OAuth App.

Creating a new Dropbox App

2. Once you’ve created your App, click Generate access token and take a note of it.

3. I used Axios for HTTP requests. I’ve created an instance for Dropbox since it’ll be used quite a few times. Replace the token here with the one you’ve saved in step 2.

Setting up Axios

4. The Dropbox API endpoint /list_folder returns the files and subfolders in a folder. It also returns a cursor which corresponds to the returned state of the folder. In our script, we will specify that if a cursor doesn’t already exist, POST to /list_folder and write the cursor into a text file. If you have nested folders on dropbox, you could also pass the recursive option as true.

Query Dropbox for the first time and saving the returned cursor

5. Another API endpoint /list_folder/continue returns the difference between the supplied cursor and the current state of the folder. To know if there are any changes since the previous query, POST the cursor we saved from preceding runs:

Query Dropbox using the saved cursor to check for changes

6. If there have been any new changes, the response should look something like this:

Example response if assets have changed on Dropbox

The .tag will be file if a file has been modified or added, and deleted if a file has been deleted.

SVGO

SVGO is a Nodejs-based tool for optimising SVG vector graphics files. We have set up our SVGO settings as below, but you could adjust the plugins however you want:

SVGO settings

Updating the local files

The next step is looping through the entries array returned from the Dropbox API. There are three types of actions we could perform on each entry:

a. Modify

When a SVG is modified, all we have to do is download the changed SVG from Dropbox, run it through SVGO and write it locally. The id and name are returned from each entry in Dropbox response, and iconDir would be the path to the directory of the specific icon.

Updating or creating a SVG file

b. Create

When a SVG is added, one extra step needs to be performed to create a new directory as well as a package.json.

To create a package.json, we write over a boilerplate file. An example boilerplate could look like this, in our case we are replacing the ICON_NAME placeholder with the name of the icon.

icon-boilerplate.json

Creating a new directory and package.json for a newly added SVG

After creating the directory and package.json, we run the same function as the modify step, which downloads, optimises and writes the new SVG.

c. Delete

When SVGs are deleted from Dropbox, we also want to remove it in our codebase. We will check the entry object's .tag key to see if an asset has been deleted:

Deleting an SVG

This removes the directory and the contained SVG and package.json.

Git CLI and GitHub

At this point, we have created, modified and deleted a bunch of icons locally. It is time to commit them and open a pull request. We can make use of the Git CLI on our build pipeline to commit the changes and open a branch. You can use exec to run a bash script, and pass in an argument that identifies the branch such as an icon name.

Bash script to commit and push changes to a new branch

Finally, we can open a pull request using the GitHub API. You will need a GitHub OAuth token with write access to the head or the source branch of the repository. The branchName here should match the one that you’ve created using the bash script and listEntries is an array of changed icon names used in generating the pull request’s description.

Opening a pull request on GitHub

This is an example of a pull request generated by the pipeline.

Integrating into the workflow

The final step is to integrate the pipeline into our workflow. There are a few options of doing that: we could set up an alert when assets are changed on Dropbox and decide when we want to sync the icons, or set up a cron job and check for changes regularly. The strategy depends on how often we make changes to our icons and feedback from designers and developers.

Would you implement this? Let me know your thoughts and how you’ve handled the design handoff process.