I've been building a component library for my company. 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
- 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 this is new to you. 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 styling solutions.
- Create or adopt 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. My recommendation would be Figma, but it's ultimately up to your team and company.
Define your design tokens
Design tokens are the visual design atoms of the design system — 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, take a look at some of Vercel's Design System.
:root {
--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;
}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.
- Output PNGs and JPEGs at different sizes/resolutions for marketing.
- Consume SVGs in your component library or application.
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>Update 2024: For bundling, you'll probably want to use Vite or tsup.
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 doesn't come without tradeoffs. It's important to understand the pros and cons.
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)
Note: Want to use a Monorepo? Learn more in Building a Design System Monorepo with Turborepo.
Evaluate styling solutions
Update 2024: CSS has evolved a lot in the past few years. Here are my latest thoughts.
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 Shadcn UI.
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 <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.
Update 2024: With the rise of popularity in Shadcn UI, and the general trend of "build your own" component libraries starting from a base of well-designed APIs and accessible primitives, it makes this part of the process much easier.
Choose a documentation platform
I would recommend you design tool remaining the source of truth for the design system.
For example, if you're using Figma, you can still make the system easily accessible to your company without them needing to be designers. The living implementation of the design system should be in the component library.
Conclusion
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 frontend development and design. Below, you'll find a list of design systems which have inspired me and serve as great resources.