Our design playbook

Laying the groundwork

We began with our project retrospectives, combing through the heartaches and wins associated with our past tools and processes. We gathered every designer and developer for a rundown on our findings: components were becoming difficult to find, type styles weren’t descriptive enough, color palettes were too descriptive, and so on. Together, we investigated other systems, looking to IBM Carbon, Audi, Google Material, and others to better understand their organization structure, possible naming conventions, and documentation styles.

We split into cross-disciplinary teams to reimagine an existing library’s structure, talking through areas where we could give and take. For example, we wanted to continue using forward slashes (/) in our text style names because of folder structures, and development really needed SVG icons to be exported with flattened layers to avoid superfluous code.

Each team cut, pasted, and presented their ideal file organization so we could vote on implementations of everything from file naming to how we define states across components, small and large. These collaborative decisions would go on to inform our newest standards for our larger design systems. What follows is a sampling of our findings.

‍

‍

‍

Color

A few months back, we were designing a white-label product when an early (way back in moodboards) decision crept into development. We had initially named color swatches using descriptive terms, like smoke and midnight, but we failed to create the more generic naming convention needed in a white-label product. At this point, it was everywhere and we would need to course correct. But what was the right way to rename each swatch?

Initially, our design team gravitated toward smoke because it painted a picture—it was descriptive. Though naming colors can be ~fun~ and there are plenty of tools and times when this may be appropriate, common names can present a larger issue for those with visual impairments and for systems that need to operate more agnostically. Our goal was to find a succinct convention that was descriptive enough to hold its own, but wouldn’t change more than a couple lines of code if the HEX itself changed.

‍

Explorations

dark-red
What if they rebrand? Does this hold when we translate to dark mode? How does this help our colorblind developer?

#f3f3f3
It’s short, but it’s too specific. What if the client wants a bluer-gray down the line?

smoke
It’s like the first option, but even more arbitrary — is smoke lighter than silver? What color is ecru anyway?

gray-lightest
Gray-lighterererer. This is getting closer, but where does it end?!

primary-500
This gives us enough information, is still flexible, and it shouldn’t ever dig us in too much of a hole.

‍

Our recommendation

‍Start by using a category like primary, secondary, tertiary, accent, base, or ui, followed by a qualifier that indicates brightness, from lightest 100 to darkest 900. By leaving room for categorical customization, we found that the team felt empowered to make the palette work for their project’s needs, while being easily understood by new project mates and the greater team. This methodology would also allow us to easily insert or remove colors in the future. Note: you don't (and probably shouldn't) need every color in the scale.

‍

‍

Taking it a step further

Our team prefers everything to meet W3C AA (4.5:1) accessibility if we can. When looking to incorporate accessibility best practices, we were inspired by IBM Carbon’s color theory and a few others. We were all jazzed about this standard: colors 500 and less should remain accessible on black, and colors over 600 should remain accessible on white. This makes it easier to apply and validate swatch decisions within both design and development tools. But remember, you shouldn't rely on color alone to communicate important information.

‍

Other color reads

• A nice review of color name variables
• InVision’s naming conventions
• Semantic color systems: YNAB uses a similar method, but takes a step further to spell it out for their larger design team

‍

‍

Typography

We had similar goals for our type styles. For us, it’s best to remain as agnostic as possible, ensuring that at any time someone can change the font or the size and not impact more than a few lines of code, while still being human readable. We also wanted to keep it brief and memorable.

‍

Explorations

header-xxl
Could we have 4XLs? The ambiguous end makes it hard to memorize.

h1
This is clean, but it can often conflict with existing HTML. Our devs like to be more custom.

header-100
This aligns with our color conventions and is extendable, human-readable, and descriptive.

‍

Our recommendation

For our style names, we landed on using familiar language for our categories: header, paragraph, body, link, button, or caption, while relying on a numerical system for our qualifier, from smallest 100 to largest 900. We initially had this inverted due to ingrained h1-h6 hierarchies, but we found that consistency with CSS font-weights and our color palette was more effective.

‍

‍

Library files

After a few months of building out components under the guise of Abstract, we found our Sketch files to be overburdened, beachballing at the thought of moving a button just one pixel. We also knew that our filing structure would bend under the weight of a design team larger than ours. To set us and our partners up for success in the future, we wanted to define how we construct and name our files within a larger design system.

We audited elements often found in a design language and began defining relevant pairings and establishing hierarchy. Our preferred base structure for a design system included individual files for symbols, foundational styles, and components. These files are detailed below, but ultimately allow us to work with a top-down approach, taking the weight off our files, allowing for less corruption and interference, while simultaneously supporting updates offline.

‍

Recommendation

UIKit_001-Symbols

• Global symbols
• Icons

‍

UIKit_002-Foundation

• Overview: introduction, external asset document, and version history
• Color & typography
• Grid & spacing
• Layer styles

‍

UIKit_003-Components

• Micros: small, global components used across the system like inputs, selectors, actions, and utilities
• Pattern-specific pages: repeatable patterns, often made of multiple micros, such as navigation, cards, tables, lists

‍

‍

‍

Launching the playbook

Early this year, we began onboarding our company into the playbook. So far there has been a lot of excitement, a slew of feature requests, and we’re seeing some of these concepts slowly work their way into new projects. Though we set out to create standards that could be versatile and lasting, it’s also our job to continually push and test the limits. If our playbook isn’t constantly evolving, nor are we.

If you’ve had any successes or findings in this space—we’re all ears!

‍