Jostle Style Guide

Design System, Efficiency, Teamwork

Alongside the Design Team at Jostle, I helped create The Jostle Style Guide—a design system that enables us to create, replicate, and assemble consistently.

Jostle Style Guide

Note: July 2017, we presented this to the entire team at Jostle. This piece is an adaptation of an article I cowrote with Grey Vaisius at Jostle, which we posted to our internal Jostle intranet for existing company and new hires to reference.

Why we built a style guide

A style guide contains the rules and pieces of a system collected and codified in a single place. The Jostle Style Guide (Style Guide) originated with Justin Alm, Grey Vaisius, Noel Heaney and was created to meet the need to have a easy way to replicate and assemble consistent design deliverables. The Style Guide has proved to be very useful for designers joining our team, as it empowers new designers to make more impactful decisions faster. It is a living system and we continue to improve its minor details and debate how it should be refined and extended.

Grey Vaisius
Grey Vaisius
Justin Alm
Justin Alm
Noel Heaney
Noel Heaney
Elliot Mah
Elliot Mah

As our design team has grown, our need for shared principles and rules for measuring the success of design has also increased. When I arrived at Jostle, the product was filled with a variety of font-sizes, capitalization treatements, 500 shades of grey, and a seemingly infinite number of spacing units. Given this product landscape and lack of principles or clear cut styles, we found it difficult to evaluate each other’s product design. Nothing was technically right or wrong.

Product before Jostle Style Guide
Product before Jostle Style Guide
Product before Jostle Style Guide

Some screenshots of Jostle’s eclectic product before The Style Guide.

Atomic design

For these reasons, the foundation of The Style Guide is a set of extremely basic building blocks: colours, a defined and flexible typographic hierarchy, spacing units, and a few practical use elements (form elements, dividers, buttons, etc.).

We use a naming convention and methodology inspired by Brad Frosts’ Atomic design. This is an extensible approach to us, allowing us to stop at a small set of building blocks (atoms) or logically expand to modules (molecules) and further into layouts (organisms) if so required.

Atomic approach to a style guide

Having a single point of reference helps us find answers to questions regarding style and enables our team of independent people conceptualize, design, and build products that feel like variations on a cohesive theme. When cohesion or integration issues arise, there is a clear point of reference to trace back to. This point can be modified or extended and all future projects benefit from the expansion.

Our system has become an entity in the organization and identifying and discussing inconsistencies has become easier. The benefits of the Style Guide extend beyond our internal experience of designing and building products. As the principles and rules of our system are applied, the experience people have working with our product has also become more consistent, stable, and enjoyable.

How we use it

Jostle’s Design Team uses the Style Guide to great effect. It allows us to work independently, on an increasingly large number of projects, and still achieve a high level of consistency. For example, figuring out how far 1 element should be from another element requires less problem solving with a limited set of variables to choose from (5 possible choices in the case of the Style Guide 👍). In fact, I’ve discovered over time that our most successful designs for new features use 3 or less spacing units, colours, line-qualities, and type sizes.

Jostle Complexity
The Style Guide helps with increased complexity.

That’s enough concept. You‘re probably wondering, what these atomic elements are.

Atomic elements

Colour

We primarily use 5 colours. These colours are pulled from the Jostle logo. We also have 5 shades of grey.

Jostle Colours

As our brand and identity have evolved, we extended our colours to enable more expression in blog images, online ads, and gated pieces of content. We still consider it best practice to constrain new designs to the primary colour palette and we try to use the extended palette only when needed. Although we initially extended the colours for use on the marketing website, we have found these darker hues to be useful for product design as well. More on that to come.

Extended palette used in our marketing collateral
Extended palette applied to marketing collateral.

We use our of greys to bring focus within a Primary View. The view hierarchy moves from left to right and dark to light. That said, we do run into instances when we have to break our rule of “dark-to-light” to maintain contrast within a view. This was especially true when our customer’s brand is applied to the product. At that point, we do our best to constrain the application of colour but it’s kinda open season.

Greys applied to application to bring hierarchy

Typography

Family
Across our product and marketing materials, we use Open Sans by Steve Matteson. Open Sans is optimized for print, web, and mobile interfaces, and has excellent legibility characteristics in its letterforms. We use the Regular (400), Regular Italic (400), Bold (700), and Bold Italic (700) weights in our UI.

Sizing
Most type within the UI is set at a font size of 14px with a line-height of 1.6. This font size strikes a balance between legibility and efficient use of screen real estate. For longform reading, such as chat Timelines and the body of an Article, Event, or Classified, we use a 16px font size to improve the reading experience. Links are blue and underlined. When you hover over a link, the underline is removed. We use pixels because it translates easiest into our design software. In terms of vertically integrating these sizes into the product, we’d probably advise the use of ems or rems.

Weights
Generally speaking, we use larger or bolder sized type to indicate a new section of content or controls. For example, the font size for a title of a form is styled larger than the font size of an input label. The largest type in our application is 32px and the smallest is 12px. By default, headers are regular weight but can be bold.

Typography

Spacing units

We use larger spacing units to delineate sections of content or controls. Smaller spacing units are used to space elements that make up a section of content or cluster of controls. For example, the padding for the container of a view is often larger than the margins between an input and label. To keep consistent padding and margins on elements throughout our application, we use spacing units divisible by 8 (i.e. 8px, 16px, 24px, 32px, and 40px). This helps us maintain consistent vertical and horizontal rhythm throughout all of the components that make up the UI.

Spacing Units

Borders

We consider it best practice to build hierarchy within a view without borders but if you require another element to delineate a block of content or set of actions, they can be useful. Most of our borders have a border-width of 1px. Our Fat-light border is 5px wide and is used sparingly.

Borders

Below you can see an application of border styles. From left-to-right, through sub-sections within a Primary View, lighter and darker shades of grey are applied to fills and borders to support hierarchy and indicate related groups of content.

Applying borders in the product

Buttons

States
We have 3 classes of buttons: Neutral, Destructive, and Confirm. Each class of button can be disabled. The hover and active states for each class step 1 colour darker in the palette. For focus states, we apply a 2px border using the darker hue in the pallet. All buttons have a border-radius of 4px.

Button states

Relative sizing
The size of buttons and input elements is determined by the font-size, line-height, and padding of text within the button. For most of our buttons we used “font-size: 14px/1.6; font-weight: 700; padding: 8px 16px;”.

Relative button sizing

Inputs

States
All inputs have a solid, 1px, grey02(#ccc) border and their corners are rounded with a border-radius of 4px. We label all of our inputs top-left using a bold 14px font. Placeholder text is expected to direct the user by example and is coloured grey03 (#9ba3a5). Some data requires a character limit so a counter is placed above the top-right corner of the input. The input’s focus state has a blue 2px border. The input’s disabled state has a light-grey background and the CSS property “cursor: not-allowed“.

Inputs and states

Relative sizing
Inputs are also proportionally sized by the font-size and padding within the input. We also use “font-size 14px/1.6; padding 8px 16px;” for inputs.

Inputs

Icons

When I started at Jostle, there were a broad range of icon styles, varying in size, fill, and stroke. The icons had the same problem of randomness that the colours and font-sizing had. They contributed to the feeling of disconnection and weakness throughout the product.

Grey Vaisius lead the initial push on improving our icon set, redrawing the majority of the existing icons in the application. He established the size and general art direction for the set. Over the years, I’ve contributed to the set, adding several icons for new features and tweaking other icons so we maintain consistent optics across the set. We recognize there’s further room for improvement but we’re in a much better place than we were in 2015.

General constraints for drawing icons are:

Jostle icons

No components

You may be wondering, why we stopped describing things at the atomic level. The Design Team discussed the pros and cons of building an “atomic style guide” or fully detailing the components we use throughout the application. After several rounds of debate, we agreed not to take on that task of further detailing UI patterns for the following reasons:

Shared tools

The Style Guide exists as a shared library among our Design Team in Figma. We also built a Jekyll website and deployed it to style.jostle.us. Unfortunately, this site is only accessible via Jostle’s VPN but I’ve got a fork of this project on my personal Github. This online resource is a valuable asset for both our Design and Dev Teams. HTML and CSS makes our design system “real” as it shares the same material as our product. We use git for version control and collaborate on the project over Jostle’s Gitlabs.

Our shared Design Team Figma Library

Figma

Jekyll .scss

Jekyll

Style Guide repo on Jostle’s Gitlabs

Gitlabs

Jekyll website

style.jostle.us

Downsides

Without total vertical integration, tracking changes from the Style Guide to all of the instances where styles are implemented, has made for a less than perfect outcome. There are many ways to try and deal with this problem but everyone is always balancing cost vs benefit on the production pipeline. Since our Style Guide is not totally integrated into the development process, it requires our UI Developers and QA Teams to know and understand font-sizes, spacing units, colours, and rules for form controls. Ironically, abstracting all of that detailed information into more human language is the value proposition of the Style Guide. This shared ‘human’ language hasn’t steeped throughout the organization yet but it’s slowly getting better. We are still trying to solve the problem of lack of adoption throughout the Dev Team. Most likely, this will be solved with a few champions setting a standard of use moving forward and integrating our styles into the dev environment. In the end, we have had positive response. The struggle is making change happen.

Response

In my 15+ years in software development, a designer has never explained to this level what the style of the product should be. For a person that cares about design and consistency (but does not have your expertise) this is really huge. Thanks so much.
Darren John, Test Team Lead at Jostle

Conclusion

Jostle applies a lean development philosophy. The Style Guide hasn’t been created to go back and fix everything that was stylistically flawed. Instead, as we moved forward, all the product we ship is expected to hold true to the system we have designed. Although the full impact of The Style Guide is yet to be realized throughout Jostle’s platform, it has brought immediate benefits to the Design Team. We are able to move forward in a unified voice—communicating a shared vision for the product together.

Feedback?

Don’t hesitate to reach out if you have thoughts or questions!

See more work: