How and why we built the Marvel Styleguide

After I joined Marvel in August last year, the first project I worked on was our new styleguide. At that time, Marvel was doing a lot of things well. The brand was fun, the UI was simple, colors were bright and animations were snappy. There was a lot to love. But as Marvel continues to grow, both as a product and a company, one challenge we are faced with is learning how to refine Marvel’s identity and apply it cohesively to each of our products in such a way that everyone on the team has a similar understanding of how Marvel should look, feel and function.

We needed Marvel Styleguide to act as a central hub where we could house a live inventory of UI components, design patterns, brand assets, code snippets, developer guidelines and anything else associated with Marvel’s identity.

Before we started, we sat down to figure out which problems we were trying to solve and what we wanted to achieve. We set ourselves five specific goals:

#1 Create a cohesive design language

Marvel’s brand identity has always been on point. One of the keys to Marvel’s success is its friendly, fun and inviting brand. But for all its playfulness, one important factor was lacking; consistency.

Our first task was to take a full inventory of all of the styles that made up Marvel. Not just UI components, but every single color, font size, shadow....everything. As we combed through the product in detail, what we found was not too surprising. Minor inconsistencies began to crop up all over the place.

• Identical components were implemented inconsistently.
• Colors were not balanced properly.
• Transition durations were set seemingly at random.
• There were almost 100 unique font sizes.
• We counted 18 slightly different shades of the same gray.
• Lots of CSS was either duplicated or unused.

Overall, too many things seemed random. Not enough things seemed intended. There was no sense of order, no sign of a design system at play.

So after we had taken an inventory of all the styles used, we gave each one a name and a purpose. Every color was given a meaning. Every shadow was assigned a particular task. Every font size adhered to a predefined scale. Any style that didn't have a distinct purpose was removed. Once we settled on a set of core styles, we stripped away everything else, then defined a set of single-purpose CSS classes, one for each style.

Then we began the rage-inducing task of rebuilding each of our UI components, one at a time, from the ground up.

#2 Build a platform-agnostic system

The design inconsistencies I mentioned above carried over into the codebase too. Identical UI components were duplicated in code. Colors were defined multiple times. All of this duplication had a negative impact on performance.

So, when rebuilding the UI components, it was important that we kept everything cohesive. We needed to make sure to only use the styles we had predefined. To do that, we used Sass extend function to build out the components by reusing the single-purpose CSS classes.

This approach provided a number of benefits. It allowed us to keep all the styles consistent across the entire app. It enabled us to get CSS duplication down to zero, since each style is declared once and once only.

However, just rebuilding the front-end in a more DRY (Don't repeat yourself) way wasn't going to solve all of our problems. The biggest problem with the old method, was that styles were typically encapsulated in page sections rather than reusable components. There were more child selectors than I'm comfortable dealing with and namespace classes were not uncommon. At that point, Marvel was growing pretty quickly and the team was expanding. We had iOS and Android apps to consider. There was also the new Canvas iOS app to contend with. Different teams not only had different design problems, but different programming languages were being used too. The old front-end approach would result in uncontrollable bloat if we didn't find a better solution. We needed to come up with a way to keep our design language consistent across all our different platforms and devices, without duplicating code.

So, we decided to move our styleguide to its own separate repository. We packaged it up as an NPM module which trickles down to each of our products. Going forward, any future updates to the styleguide will be submitted directly to the styleguide repository, documented, then updated across the Marvel platform.

#3 Improve cross-team communication

One of the most interruptive problems I’ve experienced at pretty much every tech company I’ve worked with is poor internal communication, particularly between designers and developers.

The typical workflow I've observed in a lot of tech companies involves a lot of unnecessary back and forth between teams. So much time is wasted on things like setting animation parameters, arguing over box shadow values, documenting colors and other trivial tasks.

Now that Marvel utilises a global styleguide, we no longer need to maintain high-quality assets. We no longer need to produce hi-fidelity mocks. A designer can simply whack together a UI using whatever colors, fonts, assets or software they have readily available. Accuracy is not important because the developer will override everything in the mock, choosing the closest match from the styleguide in each case. In some cases, all that’s needed is a spec sheet written in a Google Doc.

By abstracting away the visual layer, developers can churn out UIs with minimal design input. In some cases, the design team doesn’t even need to be involved. This really starts to blur the line between designers and developers, taking the focus away from visuals and placing it where it belongs, on content, copywriting and user flows.

#4 Encourage change

Most good designers I know share a common urge to put things right. This can be frustrating when you join a company that has already established a brand identity. As with most brand identities, there’s usually a lot of room for improvement but you can sometimes feel like you don’t have a voice. Often times, this comes down to inexperienced, over-zealous designers not understanding the full complexity of a product. But it’s not uncommon for companies to inadvertently discourage change.

I’ve worked on projects where I didn’t feel invested because product ownership was limited to a select few people. I’ve seen good suggestions from new designers get shelved because whoever had been assigned ownership was busy on something else. Tweaking designs is often discouraged because nobody is really sure which areas of the codebase might be accidentally affected by the update. When products are not designed systematically, different segments are often siloed and unconnected -- making them inaccessible to most of the team.

Having a global styleguide which is abstracted away from our core product, provides an accessible avenue for anyone at Marvel to voice their opinion. We want to encourage everyone at Marvel to contribute to our product regardless of their skillset. If you’re comfortable with code, you can jump in and make your changes, then submit a pull request and start a discussion (fight). If you don’t work with code, you can open an issue, upload some mocks/docs, then get a debate going.

One useful artefact of this approach is that we automatically start compiling a rich history of pull requests, issues, debates, mockups and documents that we can reference later. As teams scale, a lot of time can be wasted as new employees attempt to work on ideas which have already been explored. By encouraging all design work to be submitted through the same avenues, we keep the whole team updated on where the product has been and in which direction it’s headed.

#5 Encourage solid reasoning

One of the most attractive aspects of design is the sense of freedom it offers. To a designer, there’s something exciting about a blank canvas -- ultimate creative freedom. But the reality is, when it comes to design systems, creativity and freedom are just not that important. Noodling about in Sketch might appeal to a designer's creative needs but it’s not at all conducive to a performant, cohesive web product.

Design is just problem solving within a set of constraints. In the grand scheme of things, it rarely has anything to do with graphics.

One problem with most current design tools is that they're too decoupled from the actual live product you're working on. When you have an infinite array of possible values to choose from for any given style property, it's too easy to get lost in creativity and lose focus. To quote Adam Morse, one of the best designers I know, "Design is just problem solving within a set of constraints. In the grand scheme of things it rarely has to do with graphics." When you strip away the visual layer, what you're left with is the core design, the inner workings of a product.

Working from a styleguide does just that. It forces you to stop thinking about form and focus on function. To a lot of designers, the git-based workflow I outlined above might feel like an unnecessary hurdle. It may feel like it's forcing you down a specific funnel and restricting your freedom. But actually, this approach doesn’t curtail your freedom at all. It just forces you to think about what you’re doing and why you’re doing it. It forces you to communicate your reasoning to your team members. It opens your work up to criticism and exposes flaws in your designs. It helps you understand the full impact of your design suggestions and encourages you to consider all edge cases.

Trust me, when you know that the slightest tweak will bubble across your entire suite of products, you think twice before you bump up dat font by a few pixels. And that's a good thing. You learn to think in terms of systems instead of pages. You learn to work iteratively. You learn to communicate better with your team. You learn to turn instinct into reasoning.

So what’s next?

Right now, our styleguide is very much in flux. As we continue to refine Marvel's brand identity, we will continue to update our styleguide. So a project of this nature will always be a work in progress. It's early days though, so we have a lot of exciting updates planned soon:

• Our icons are cobbled together from various icon sets that we have tweaked to fit. As a result, they lack consistency. So we're planning to design our own custom set to reflect Marvel's look and feel more accurately.
• We're in the process of rewriting our entire front-end in React. So to coincide with that, we're also going to start rewriting the entire styleguide in React. Among other things, this will help cut down on a lot of the CSS class repetition in our views by abstracting them into the component layer.
• At the moment, our mobile apps are built on other programming languages like Swift. We're toying with the idea of moving to React Native, which would allow to use a shared codebase. It would also open up the door for a native OSX version of Marvel Canvas, using React Native Desktop - if we wanted to go down that path.
• The core of our styleguide is built on top of BantamCSS - a CSS framework I created (...look how that worked out) a while back. Right now the framework is integrated directly into our codebase, along with other third party tools like Nicolas Gallagher's Normalise.css. We're planning to split the styleguide up into smaller parts and pull these frameworks in via NPM, so we can take advantage of future updates.
• After we have split the styleguide up into a more organised fashion, we're going to open-source it. Marvel Styleguide will be free to use for anyone interested. We will also continue to support the OSS it's built on.

Want to join the design and engineering team? Check out our jobs page.