Everything I Know About Style Guides, Design Systems, and Component Libraries
Jonathan Wong / August 07, 2019
12 min read • ––– views
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.
Table of Contents#
- 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
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:
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:
For example, take a look at Vercel'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.
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.
- ✅ 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.
- ⛔️ 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:
- 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>
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?
type? Did you consider that type is a reserved attribute for the HTML
<button> element? These are the type of decisions that you will need to make as you build your component library.
Some other things you might want to consider:
- Should you allow consumers to pass CSS properties in as props to the React components, or should they have to extend/wrap components to achieve their desired styling? If you choose the former, consider styled-system.
- Should you build loading states directly into components, or should there be a generic component for loading (spinner, skeleton?)
- How should you test purely visual components? Snapshot testing? Visual diff testing?
- What will consumers need to do to integrate with your component library? Should there be a global style reset? Should they add any Babel plugins?
- Should you utilize Conventional Commits to auto-generate a changelog?
- Will your components need to support web and mobile? Consider using React Native Web to share code across platforms.
Choose a Documentation Platform.#
You need a platform to display your design system. If you're just getting started, I would recommend using Storybook Docs.
- Easily copy code snippets from component examples
- Auto-generate a props table based on
- Easily view all permutations of a component
- Write custom docs using MDX
If you're adamant on your design system reflecting your brand and dogfooding your component library, I would recommend a custom solution using MDX. This will allow you to insert React components inside Markdown files. The blog you're reading right now uses this.
Having a truly custom solution allows you full control over your docs. One example I'm extremely impressed by is Atomize React.
Write Design System Documentation.#
Now that you've chosen a documentation platform, it's time to write the docs. You should include:
- Installation and setup instruction for the component library
- Props schemas and type definitions for each component
- Component examples along with copyable code snippets
- Technology choices and rationale
Consider also adding:
- A "Getting Started" section involving a tutorial
- Completed UI templates to choose from
- Information about theming
- A live code playground for interacting with components
I've spent a lot of time in the past year thinking about design systems. Building a component library from the ground up gave me a new appreciation for the amount of work that goes into front-end development and design. Below, you'll find a list of design systems which have inspired me and serve as great resources.
Feel free to reach out if you wanna chat about building design systems.