How we architect our pattern library using design APIs
At the most complex levels of CSS development, front-end software is developed by assembling reusable components or design patterns. These are different than the design patterns created by the Gang of Four. Rather, they are agreed-upon user interface building blocks that have been approved by both design and engineering teams. At Grubhub, we create these patterns as bundles of CSS code that can be easily exported and attached to HTML for assembly on external client apps.
Reflecting on the term “API development”, I’ve begun to conceptualize this collection of CSS bundles as Design API development. If we consider a library like jQuery, for example, the usage is exactly the same. An engineer will import the library, look up the available methods, and then use those building blocks to create his or her own software. In the same way with our library, Mochi, we can import bits of the library and quickly spin up a Grubhub-themed web page.
API development has typically been used to describe server-side programming. But as we can see from the quote below, the term is certainly applicable in front-end development, too:
Application program interface (API) is a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact. Additionally, APIs are used when programming graphical user interface (GUI) components. A good API makes it easier to develop a program by providing all the building blocks. A programmer then puts the blocks together. –Vangie Beal
How does our API work?
The Grubhub Design API is super simple, as are most front-end style guides. We expose bundles of CSS styles that you can import into your application for consumption.
Let’s take a closer look:
Suppose I want to rapidly prototype a new page. And to do that effectively, I’ll need to include a heading and a button. First, I’ll import buttons.scss and typography.scss. Then, when I create my own software, I’ll write:
<div>
<h1>Heading</h1>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit</p>
<button class="s-btn s-btn-primary u-stack-x-2">Button</button>
<button class="s-btn s-btn-secondary">Button</button>
</div>I don’t have to think about the code behind the button or the heading. I just know that the desired outcome is going to be correct. It will look like this:
Consider the exported classes as similar to setting a contract for a typical server/client architecture. The classes would not change except for a major revision, and those breaking changes would need to be communicated to all the parties involved.
Terminology for design APIs
There are so many terms floating around these days for the type of work we are doing — Front End Style Guide, Living Style Guide, Pattern Library, Component Library…the list goes on and on, and the distinction between the terms gets pretty muddy. By labelling our CSS classes as Design APIs, the architecture becomes a lot more sensible.
Consider that the API layer is typically the “base” for a lot of the foundational data in client applications. In this regard, our Design APIs fulfill that role by providing the building blocks on which we can develop more software.
The diagram below illustrates how the entire system works:
Note carefully the tightly coupled binding between design and development. We use language to couple these two together. The shared language is what eases the communication friction between teams and helps to reinforce the quasi-“contract” that is involved with other API development.
The design API acts as a base layer for our component libraries. Keeping the API CSS-only allows us to create component libraries in different JavaScript frameworks as a layer on top of the API. We can then bundle and export the component library for use in our flagship applications, for documentation in our Living Style Guide, and for rapid prototyping in CodePen Projects.
When we launched the CodePen Projects tool, we were able to quickly produce rapid prototypes and provide working links to external parties. The uses are endless — and include quick demos for stakeholders, working prototypes that can be user-tested, fleshed-out ideas that designers can hand off to developers.
We also currently use the Design API in many different small-scale applications, including email templates, marketing modules, and even our office phone directory. Having a flat, CSS-only system ensures this adaptability.
The principle of abstraction
Software maintenance consumes between 40–80% of a project’s resources. The burden of maintenance affects both project velocity and team satisfaction. –Dominic Nguyen
One of the most fundamental concepts of computer science is the principle of abstraction. In this specific case, we are abstracting away the minute, pixel-pushing details of design and setting them in our contract with the design team. As a result, developers spend less time maintaining less code, with higher-quality code and UI output. Specifically, in computer science terms, this allows devs to focus solely on the interface, without having to worry about what’s inside the black box. Engineers, in turn, are freed up to work on more compelling and complex problems, while spending less time in the weeds of visual QA.
Final thoughts
As you can see, our Design APIs have an integral role in our product delivery process. Our Design APIs/Pattern Library benefit our designers and devs on the Product team day to day by offering flexibility and choice. By systematizing design, we free up time and mental space that would’ve been spent on detail-oriented work. Our distributed teams can then use this time to innovate, creating product-driven “home runs” that delight our diners and encourage them to order again and again.
Do you want to learn more about opportunities with our team? Visit the Grubhub careers page.
