How We Built Handoff

Posted 4 months ago by Oleg Tsaplin

Prototyping is not only a stage of the design process, it’s heavily involved in the developer handoff process as well. When a design is ready to go into development, developers often receive pages of spec documents outlining how the design should look, feel and function. This has been a major pain point for many large organisations and design teams, and we felt like it should be addressed.

“Developer handoff should be simple, with all documentation of sources of truth living in the actual prototype itself.”

As Marvel moves forward with its vision of putting the power of design into the hands of everyone, we wanted to make it even easier for developers to start building apps and websites using the designs and prototypes created on our platform.

Handoff started as a simple MVP experiment when digging into the Sketch file format, completed over one weekend. The switch between prototyping and code was so seamless that we quickly realised that it was going to be an essential part of our whole ecosystem, and started planning to add it to our core product.

We took a step back and realised that the foundation of Handoff should be a flexible API that can translate any design file. When we started, Marvel had a Design tool built-in, allowing our community to create millions of wireframes and mockups of website and apps. This came with a simple way to store all of that data – an early version of the Marvel Design API called Easel – but it was not mature enough to be backbone of a product like Handoff.

From this starting point, we created the full Marvel Design API and got started.

Our first chunk of work was to bring the Marvel Design API up to speed and make sure that it supported all of the properties that you could apply to shapes, images, masks and type elements within any design tool. At the basic level, a design document is just that – a collection of shapes, text and images with different colours, shadows and positions.

From our weekend hack day to build an MVP we got pretty familiar with how Sketch formats their design files – we injected a simple Objective-C framework into Sketch which converted the whole file into a piece of JSON. Then, building a very simple Javascript application, we rendered every single element on top of the actual output image, effectively creating what we have today: Marvel Handoff.

The initial version of the Marvel Design API when we started was heavily tied into our design tool – containing only the most basic properties and elements, and slowly being developed by the design tool team solely for that purpose. We immediately saw an opportunity to build it out and make it accessible for other services to integrate to. We compared what we had in our API with the structure of Sketch documents, and got to work introducing support for things like masks, gradients, image fills and more advanced typography properties. This allowed us to open up a larger conversation about design systems, pattern libraries and assets – all of which are now in the roadmap for our Design tool.

Handoff isn’t just one product built on top of the API, but it’s also a beginning of multiple possibilities

Based on our API work and initial MVP, we realised that Handoff is a very complex product which will rely on integration into 4 parts of our ecosystem:

On the Marvel Design API side, we had to make sure that the new format was future proof, feature rich and allowed us to add more properties with ease. Handoff isn’t just one product built on top of the API, but it’s also a beginning of multiple possibilities – it’s a unified design format which we can use to import any design file, whether it’s from Sketch, Photoshop, Adobe XD or Keynote. Our aim is for our users to be able to import their work into Marvel, and continue designing inside our platform with our browser-based Design tool.

Our vision is for anyone from any part of any company: product designers, marketing, sales or support – to be able to jump into Marvel and simply start editing any document, working any wireframes or simply test a marketing concept, all from within Marvel.

The Marvel Design API is at the heart of Marvel Design, powered by Node.js and Elasticsearch – allowing thousands of people to use the wireframes we created for every mobile device, icons available from services like Iconfinder and images from Unsplash to test their ideas and build real screens and wireframes of websites and apps.

Handoff takes all of the designs created in our platform, and expose all of them to developers with simple ‘Download’ links – any piece of content or asset you insert into your design or wireframe becomes selectable, downloadable, easily readable and even already pre-made for you with simple code snippets in CSS, Swift, Android XML and Objective-C formats. Not only that, but with the release of Handoff, we enabled that flexibility for designers using Sketch as well.

Marvel Shapeshifter

Given that we already had a good starting base with our Sketch Plugin, serving hundreds of thousands of image uploads and syncs per day, we began work on a framework called Marvel Shapeshifter. It does just that – shifting shapes from Sketch and putting them into our Marvel Design API format, alongside uploading assets to our Google Cloud.

If you’re not familiar with our Sketch plugin, it allows our users to sync their artboards into their Marvel projects with one click of the ‘Sync’ button – where they can continue working inside our platform, building prototypes and gathering feedback.

This provided us an amazing opportunity to make that ‘Sync’ button even more powerful – once the image upload is complete, Shapeshifter begins working and converts the Sketch file into our format and uploads it to the Marvel Design API (essentially one more step than what we did in the MVP) – this means that every image that gets uploaded to Marvel also has all of the data that makes it that image. Every property and every value behind every button and avatar – all on our platform, ready to be used to make developers lives easier.

Building Shapeshifter was arguably the hardest part of this process as it involved dissecting Sketch files and having a lot of back and forth with our Design Tool and API teams, making sure that all the data is converted and validated correctly. Things like groups and masked elements had to have complicated calculations involved due to the difference in how we structured our Marvel Design API and how Sketch structures their masks elements.

If you’re our Sketch plugin user, it just works out of the box

When we had our first build of Shapeshifter, we had a moment of truth: we were able to open a design file created in Sketch inside our Design Tool, and saw that it was very close to a 1:1 match, apart from certain fonts which were not installed on our side. This made us realise how much potential Marvel had as a design platform.

Thankfully, Shapeshifter is built in a compartmentalised way whereby we can simply take it and import it into something like a Photoshop plugin, for example, and it can work out of the box – it’s a bridge between whatever design environment you’re in, and Marvel’s back-end system which handles file and asset uploads. With thousands of people already using the Sketch plugin for normal screens, the addition of Handoff and developer assets means that our whole ecosystem would start seeing a lot more traffic – especially our main application.

Main Application

Our main application, written on Python and running on the Google Cloud Environment is something that links this whole process together. Every asset and piece of content is uploaded to Google Storage and it’s what keeps the heart of Marvel ticking.

When a designer uploads a screen or marks an element or group as exportable in Sketch in order to ship that to their developer, several smart things happen:

  1. The asset or screen is exported, and uploaded onto our Google Storage
  2. The asset or screen is then given a unique hash
  3. That hash is then stored with the URL to the piece of content within our Marvel Design API.

This essentially means that every time Shapeshifter talks to our content system, we are able to see if an image has been uploaded before, and avoid unnecessary re-uploads and re-generation of assets and content. This simple yet powerful feature meant that we were able to make the Sketch plugin up to 8 times faster.

Assets generated by the Sketch ‘Mark as exportable’ feature also get uploaded to the Google Cloud and handled in this way. The same thing happens when we want to package up groups of assets, for example icons in @1x, @2x and @3x as a ZIP file – that ZIP file is hashed, and if it’s been requested to download before with no changes, the download is instantaneous when you click the ‘Download all’ buttons in the Handoff sidebar.

Front-end and Design

Marvel’s core feature is the share link that you get when you build your prototype. You send that link to your colleagues, clients or stakeholders, and they get everything – comments, designs and interactions – all in one place. This same link can even be used to install mobile prototypes to the homescreen of your mobile device. These links are viewed millions of times per month.

It made perfect sense to add Handoff to it, making the core of Marvel a single link that acts as the source of all communication around your project. Anyone can then view all of the screen’s key information, measurements, colours, variables and comments directly from the prototype, allowing them to start building and bringing the design to life straight away.

A basic prototype consists of a collection of images which make up your project, all we had to do is draw selectable shapes corresponding to every element in your design – effectively building Handoff and a secondary layer on top of what we already had. This meant that it was completely separated from the base prototype view, having no effect on initial load times of the main prototype view – the call to the Marvel Design API is only made after you open Handoff mode which allowed us to introduce Handoff without any knock-on effects for our users.

We simply check if Marvel Design API data is available for the image that you open, and a call is made to download the whole design document on demand, also enabling the Handoff button to enter the mode. If you’re our Sketch plugin user, it just works out of the box.

In this mode, the image is the main focal point. The device is stripped away and the UI focuses in on your design. The immediate thing that you can notice is that every element on your screen then becomes hoverable and selectable. Once you select one element, you can hover another one to get the distances between the two, and go as deep as you want in the structure of the document.

Along with the measurements, the sidebar is the main focus point of Handoff, and the source of many debates among our design team. We went through a few internal iterations before landing on the version we currently have – the design process for this was a difficult once simply because we had to anticipate how it would feel when using a real design file.

At the point when we started working on it, we didn’t have a working version of Shapeshifter so we couldn’t test our designs with real world Sketch designs. What we didn’t anticipate there was the amount of properties that a single element can have – once we had a working build on Shapeshifter, we noticed that everything in the sidebar was a bit too large and the content overflowed with scroll on majority of screens.

Whenever we work on a big project like Handoff, we notice that certain things are missing for our own tools and workflow. It’s always an opportunity to improve and make things more efficient.

Right off the bat, we had to reduce the size of everything yet maintain the simplistic charm that makes Marvel a joy to use. Not being able to work with real data because of technical challenges while designing wasn’t easy, but we’ve now made it a core principle of our Product team – working with real data will speed up development time and reduce any uncertainties and blind spots.

Here are a few other design challenges that we faced:

These were all overcome through careful iteration and real word testing using real Sketch files: we designed each possible panel and property beforehand, and then integrated them one by one into the sidebar, ordering them by importance.

The development itself was sped up a significant amount with the help of our Marvel Styleguide. We already had most components and styles as React components, so building out a new view meant that we didn’t just start from scratch.

Whenever we work on a big project like Handoff, we notice that certain things are missing for our own tools and workflow. It’s always an opportunity to improve and make things more efficient. The Marvel Design API wasn’t the only thing that developed with the release of Handoff, our Marvel Styleguide and internal processes did too.

Overall, Handoff was one of Marvel’s most ambitious projects which had involvement from every single team we have. Everyone contributed in one way or another, and it’s a testament to our company values of being inclusive and building great tools together, for everyone.

Be sure to stay in touch with our product updates and our feature request board. Questions about Handoff? Say hello on Twitter!

Product, design and engineering at Marvel – @olegtsaplin

Related Posts

The McKinsey Design Report in a Nutshell In October 2018, McKinsey & Company challenged our hunch about the business value of design. They carried out “the most extensive and rigorous research undertaken anywhere to study the design actions that leaders can make to unlock business value.” 300 publicly listed companies across three industries (medical technology, consumer goods, and retail banking)… Read More →

How Santander introduced a user-centric mindset through research and collaboration The digital age brought us the inevitable ‘Disruptor’ – companies that have transformed the traditional way industries operate through regular high impact innovation. With the arrival of it’s new Fin-Tech competitors, finance is an industry in particular that has felt significant impact. Banking, Insurance and other financial services have had… Read More →

Last year we launched the Marvel API, a new way to build customised workflows, integrations and apps that utilise the designs, users and data on Marvel. It led to some brilliant integrations like SmartMockups, Maze and Microsoft Teams. We also kicked off Marvel Labs, an internal skunkworks where we experiment with small apps and ideas like Userflows and Dashboard …. Read More →