Our Design Playbook
Setting standards within our design systems
At a small agency like ours, we don’t work in the same design language or grid system everyday. We don’t always design in our favorite tools (hi, Figma!) and we don’t always build with our internal development team. We adapt our process to fit the needs of the project and the client—which means we’ve seen a few brand languages, built a couple design systems, and tried a lot of tools.
Late last year, we set out to translate our findings in order to make them more widely available to our team. We’ve always had shared processes and workflows, but never established, company-wide standards for how our design team architects files. We wondered, what’s in the name of a color? Should this be two Sketch files or one? How can we share our insights and gain alignment without creating a stifling, code-of-conduct document? We needed a way to quickly jump into a project knowing we were making the best decisions, pre-validated by our design and development teams. We were seeking a playbook—one that could be democratic and informative, but not an HR handbook.
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 — issmokelighter thansilver? What color isecruanyway?
gray-lightestGray-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-xxlCould we have 4XLs? The ambiguous end makes it hard to memorize.
h1This is clean, but it can often conflict with existing HTML. Our devs like to be more custom.
header-100This 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!
Bye & thanks!
Morgan Gerber is a Senior Designer at thirteen23, creating experiences, software, and products for clients such as Bose, Visa, HP, and Dell. After hours, you can commission her to paint a tiny portrait of your dog or ask her about the best carrot variety in Zone 8.
Find us on Facebook, Twitter, and Instagram or get in touch at thirteen23.com.
