Everything About Style Guides, Design Systems, and Component Libraries

August 7, 2019

For the better part of the last year, I’ve been investing heavily in front-end development and design.
When I started my new role at Hy-Vee, I identified a need for a component library and created it.
Since then, I’ve learned a lot about style guides, design systems, component libraries, and their best practices. This post will be a deep-dive on everything I’ve learned in the past year.

Why Should You Care?
What Is a Style Guide?
What Is a Component Library?
What Is a Design System?
Where Should You Begin?
Building the Design System
Conclusion
Resources

Why Should You Care?

Every website starts simple. There’s maybe one page with a few distinct pieces. It has modest intentions.

Then, slowly, it begins to scale.

More pages are added and new features are built. There might even be multiple teams devoted to specific sections of the site. You could be developing for mobile, too.

You start to notice the buttons in one part of the site are slightly different than everywhere else. One team decides to build a feature that another team has (unknowingly) already completed. Communication breakdowns happen. Consistency is lost.

Is this a preventable problem? Absolutely. Yet, why does it happen over and over again? Unless you think about your design and development process upfront, you will run into issues later as you scale.

To prevent this issue from happening, or to fix the existing lack of consistency in your products, you need three things:

Style Guide
Component Library
Design System

Don’t worry if you have no idea what I’m talking about yet. By the end of this article, you’ll have consumed almost a year’s worth of trial & error, research, and development.

What Is a Style Guide?

A style guide is a set of rules for how your brand should be displayed. This is both visual (design & imagery) as well as written content (voice & tone).

The purpose of a style guide is to allow multiple contributors to create content clearly that cohesively represents the brand. Almost every major brand has a style guide, though not all are public.

What Is a Component Library?

A component library is living, breathing implementation of your style guide. It’s a shared set of UI components that developers can consume to build applications reflecting your brand. Some notable benefits:

Having a component library means less custom code for consumers.
Since there’s a central location, you can ensure all components meet accessibility requirements.
Components become more robust with multiple contributors submitting bug fixes and improvements in a single place.
Less duplication of code allows you to ship new products and rewrite legacy code faster.

What Is a Design System?

A design system is a complete set of standards, documentation, and principles along with the components to achieve those standards. It is the marriage between your style guide and component library. One of the most popular design systems is Google’s Material Design.

A design system should contain:

Content — The language to design a more thoughtful product experience.
Design — The visual elements of the design system.
Components — The building blocks for developing new products and features.
Patterns — The individual pieces for creating meaningful product experiences.

Where Should You Begin?

Depending on the state of your company/product, you might have a different starting point. This is the outline before we dive into specifics.

Create an inventory of existing design patterns.
Establish design principles and begin a style guide.
Define your design tokens.
Create or identify an icon set.
Choose languages/frameworks supported.
Evaluate Monorepo vs. single package.
Evaluate CSS/Sass vs. CSS-in-JS.
Create a component library.
Choose a documentation platform.
Write design system documentation.

Building the Design System

Create an Inventory of Existing Design Patterns.

Unless you are starting from scratch, you will need to identify all the design patterns currently in use in your interface and document any inconsistencies.
The goal should be the same user experience regardless of which part of the product the user is in.

Start documenting and reviewing these amongst your team and identifying your preferred interaction patterns.
This should start to paint a picture of which pieces your style guide will need.

Establish Design Principles and Begin a Style Guide.

It’s time to translate these findings into the beginnings of a style guide. You can use tools like:

My recommendation would be Sketch, but it’s ultimately up to your team and company. Make sure you understand best practices around Sketch symbols and when to use nesting.

Define Your Design Tokens.

Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development.

This includes things like:

Colors (text, backgrounds, borders)
Fonts
Typography sizes
Spacing values
Shadows

For example, let’s take a look at Geist – Zeit’s Design System.

--geist-foreground: #000;
--geist-background: #fff;
--accents-1: #fafafa;
--accents-2: #eaeaea;
--accents-3: #999999;
--accents-4: #888888;
--accents-5: #666666;
--accents-6: #444444;
--accents-7: #333333;
--accents-8: #111111;
--geist-success: #0070f3;
--geist-error: #ee0000;
--geist-warning: #f5a623;
--dropdown-box-shadow: 0 4px 4px 0 rgba(0, 0, 0, 0.02);
--dropdown-triangle-stroke: #fff;
--scroller-start: var(--geist-background);
--scroller-end: rgba(255, 255, 255, 0);
--shadow-small: 0 5px 10px rgba(0, 0, 0, 0.12);
--shadow-medium: 0 8px 30px rgba(0, 0, 0, 0.12);
--shadow-large: 0 30px 60px rgba(0, 0, 0, 0.12);
--portal-opacity: 0.25;

There is now a shared language between designers and developers.

Create or Identify an Icon Set.

If you already have existing icons, you’ll need to determine which to keep. It might not make sense to create your own icons depending on the size and priorities of your company. You might be better off utilizing an open-source icon library. Here are some examples:

Regardless if you build your own or use open source, you should standardize on usage and identify consumption patterns. It’s also worth considering who are the end-users of your icons set – designers, developers, and marketing?

Using SVGs, you can make the icon library your single source of truth. Your process might look like this:

Designers create/provide raw SVGs.
Optimize and compress the SVGs using SVGO.
Automatically create React components using SVGR for developers.
Output PNGs and JPEGs at different sizes/resolutions for marketing.
Compile SVGs into a bundled font for mobile applications to use.

Choose Languages/Frameworks Supported.

What languages or frameworks are you currently supporting? Which should the component library support?
It’s important to think about this ahead of time so you can properly architecture your library.

If you have an application which uses script tags instead of ES Modules, then you’ll need to
configure your component library to bundle into a single distributable file. For example,
a vanilla JavaScript application would need something like this in an HTML file.

<script src="/js/component-library.min.js">script>

To achieve this, you can use either Webpack or Rollup.
I would recommend Webpack, as it’s the industry standard.

Evaluate Monorepo Vs. Single Package.

A Monorepo allows you to build and publish multiple libraries from a single repo. While it does solve some very real problems, it also creates others. It’s important to understand the pros and cons.

Pros

✅ Small bundle sizes by decreasing the scope of components included in one package.
✅ Shared built, lint, test, and release process for multiple packages versus separate repositories with duplicated code.
✅ More granular control of semver on a package-by-package basis.

Cons

⛔️ Additional tooling and infrastructure needed.
⛔️ Consumers are required to import from a variety of packages instead of one single component library.
⛔️ Cutting edge technology. There is industry adoption, but you can run into issues very few have experienced without a clear path for a solution.

Some questions that will help you identify which solution is right for your company.

Do you currently have multiple repositories all publishing to NPM?
Is your build, test, lint infrastructure complex? Is it duplicated in many places?
How many repositories do you have (or plan to have in the next year?)
How large is your team? How many people will be consuming the component library?
Will it be open-source? Can you lean on others in the industry to help solve problems?
Do you see the need for multiple packages in the future? (e.g. icons, codemods, etc)

For most smaller companies, I would argue that a Monorepo is unnecessary. It has its time and place. We use it at Hy-Vee (~150 developers) to distribute 10 different packages at once, spanning both internal and external apps.

Note: Want to use a Monorepo? Check out Creating a Monorepo with Lerna & Yarn Workspaces.

Evaluate CSS/Sass Vs. CSS-In-JS.

I’ve come to prefer CSS-in-JS, especially styled-components. There’s a variety of different CSS-in-JS options outlined here. The major selling points for styled-components for our component library were:

Feels like writing traditional CSS vs. JavaScript objects
React & React Native support
Auto-prefixing vendor styles
Scoped styles which eliminate global CSS conflicts

If your component library needs to support outputting raw HTML/CSS as an option, I would recommend sticking with Sass. A great example of this is IBM’s Carbon Design System.

<button class="bx--btn bx--btn--primary" type="button">
    Button
button>

Regardless of the technology you choose, I would recommend using CSS variables to contain your design tokens.

Create a Component Library.

With your technical requirements defined and your style guide started, you should now be able
to begin constructing a component library. My recommendation would be to use React alongside Storybook.

Creating a component library is much more than just translating the style guide into code.

You’ll need to think about how consumers will interact with your components.
What sort of API would they expect? What provides the most clarity and is self-documenting?
For example, consider buttons. You have different variations of buttons – primary, secondary, etc.

Should you have separate components for each?

<PrimaryButton>Hello World!PrimaryButton>
<SecondaryButton>Hello World!SecondaryButton>

or should you use a prop?

<Button>Hello World!Button>
<Button variant="secondary">Hello World!Button>

Secondarily, what should the prop be called? variant? type? Did you consider that type is a reserved attribute for the HTML