I’m proud to share our internal tool for designing and developing consistent experiences across our products: SendGrid’s official style guide. The project has been in the works for over a year now and we’ve had contributions from many team members across various teams.

When we first set out to create our style guide, I had no idea how much work it was going to be. I thought we could just design our little hearts away on new buttons, colors, type, and various other UI components and then we’d push it live into SendGrid’s products.

I couldn’t have been more wrong when it came to my expectation of how long this thing would take.

In theory, it seemed like a fairly simple task. In reality, the design team was asking a lot from our engineers and also our product managers. Not only would these changes need to be designed, our team would need to prioritize them within their existing backlogs before they were built.

Each component introduces its own set of complexities as well. Swapping out a color is a fairly straightforward change, but when I’m asking to change our table styles and the markup and classes that control them–well that’s a big undertaking.

What is a style guide?

Before I go into how we got here and the things we’ve learned along the way, I want to quickly talk about the basics. A style guide (or pattern library) is a set of reusable user interface components that help create and build a consistent experience across a product or application.

These components consist of many familiar elements such as buttons, text fields, tables, tooltips, grids, color palettes, typographic styles, icons, and more. It’s important to drive this consistency throughout your product because as we’ve learned, user’s impressions are formed quickly.

Lindgaard observed that website impressions were reliably formed within 50 milliseconds, were reliably consistent between people, and were held consistent over time. And as usability.gov points out, we see that design plays a big role when it comes to perceptions of trust, and lack of trust can impact sales.

A style guide also helps you by:

  • Creating a consistent experience across a customer’s journey and helps increase trust in your brand and reduce confusion
  • Increasing efficiency for your design and engineering teams
  • Being a reference for all new design
  • Providing a visual and code reference for engineers and quality assurance
  • Providing a resource when multiple teams are working on a user interface
  • Being a single source of truth
  • Allowing styles to be refreshed or tested in the future with consistent patterns in place

How we got here

When I started working at SendGrid, I quickly realized that we didn’t have an explicit set of rules to follow when working on new designs. Rules like how much space (padding or margin) a headline should have beneath it. Or, the hex color of gray we used for borders on various components (cards, dividers, or tables).

You do your best to follow patterns set out by previous designers, but it’s difficult to remain consistent without guidelines.

Designers may have different personal preferences on whitespace and font sizes. Inconsistencies can also quickly lead to bulk in your stylesheets. An engineer may think you’ve intentionally chosen a different color for a button and add yet another button style when the designer was actually trying to be consistent, but just didn’t have the exact same hex color.

Lessons learned along the way

As we’ve worked through the design and development of our style guide, we’ve learned a lot. I think our biggest mistake initially was that we didn’t have an accurate understanding of how much time it takes to design, build, and document all these components. Looking back, if I could go back in time to give myself some advice, this is what I would tell myself:

  • Take time to craft a plan for how your components will be rolled out, and be prepared to pivot if your original plan doesn’t work out.
  • Regularly meet with stakeholders to align on planning and execution.
  • Test and experiment with your new components–you may find that they don’t always work as direct replacements for your current interface.
  • Create component guidelines, semantically version your style guide, and provide a changelog for your engineers.
  • Always ask yourself, is this component reusable?

Below is an example of some of the guidelines that we’ve defined in our style guide:

Another big question you need to ask yourself is, how much should a style guide control? SendGrid apps don’t all share the same codebases or frameworks so we’ve made the decision to only include the HTML and CSS for style guide components. Our demo site uses some basic jQuery to demo some of the interactions (accordions, modals, etc.) but we didn’t want to force our teams to try and work around Javascript that may not be as efficient for their application.

In the end, the goal of creating a style guide is to make everyone’s job easier when it comes to designing and developing user interfaces. You should do what’s best for your situation. Talk to your team members and see what makes the most sense for your product or app when creating your own style guide. Reach out to us on  Twitter or Facebook if you would like to share lessons you’ve learned while creating a style guide or have questions for us!



As Sr. Design Technologist, Jason’s focus is on building consistent user interfaces across SendGrid’s products. When he’s not pushing pixels, Jason enjoys riding his Ducati on curvy mountain roads, snowboarding with friends, and visiting local whiskey distilleries.