everything-about-style-guides,-design-systems,-and-component-libraries

Ant Design Component Library

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

  1. Why Should You Care?
  2. What Is a Style Guide?
  3. What Is a Component Library?
  4. What Is a Design System?
  5. Where Should You Begin?
  6. Building the Design System
  7. Conclusion
  8. Resources

Why Should You Care?

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

Website Mockup

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?

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?

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.

Design System

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

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, 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.

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:

  1. Designers create/provide raw SVGs.
  2. Optimize and compress the SVGs using SVGO.
  3. Automatically create React components using SVGR for developers.
  4. Output PNGs and JPEGs at different sizes/resolutions for marketing.
  5. 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.

Monorepo

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.
Design System Button

<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.

Component Driven Development

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.

Buttons

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

153 comments

  1. Hi there, You’ve done a fantastic job. I will certainly digg it and
    personally suggest to my friends. I am sure they’ll be benefited from this web site.

  2. I was suggested this website by my cousin. I’m not sure whether this post is written by him as nobody else know such detailed about
    my problem. You’re incredible! Thanks!

  3. Excellent goods from you, man. I have understand your stuff previous to and you’re just extremely excellent.
    I really like what you’ve acquired here, certainly like what you are saying and the way in which you say it.
    You make it entertaining and you still take care of to keep it smart.
    I can’t wait to read far more from you. This is really a tremendous
    web site.

  4. Hi are using WordPress for your blog platform? I’m new to the blog
    world but I’m trying to get started and create my own. Do you require any coding expertise to make your
    own blog? Any help would be greatly appreciated!

  5. I’ve been exploring for a bit for any high quality articles or weblog posts in this sort of house .
    Exploring in Yahoo I finally stumbled upon this website.
    Studying this info So i’m glad to convey that I’ve an incredibly excellent uncanny feeling I discovered just what
    I needed. I such a lot no doubt will make certain to don?t fail to remember this web site and give it a look regularly.

  6. What’s up, everything is going perfectly here and ofcourse every one is sharing data,
    that’s in fact good, keep up writing.

  7. Howdy! I’m at work browsing your blog from my new iphone!

    Just wanted to say I love reading your blog and look forward to
    all your posts! Keep up the superb work!

  8. Pretty great post. I simply stumbled upon your weblog and wished to say that I’ve really loved browsing your blog posts.
    In any case I will be subscribing for your feed and I hope you write once more soon!

  9. Very nice post. I just stumbled upon your blog and wished to
    say that I’ve truly enjoyed browsing your blog posts.
    In any case I’ll be subscribing to your rss feed and I hope you write again very soon!

  10. It’s the best time to make a few plans for the longer term and it is time to be happy.
    I’ve learn this post and if I may just I want to
    suggest you some interesting things or suggestions.
    Maybe you can write next articles relating to this article.
    I desire to learn more things approximately it!

  11. When I initially left a comment I seem to have clicked on the -Notify me when new comments are
    added- checkbox and now every time a comment is added I receive
    four emails with the same comment. There has to be a way you can remove me from that
    service? Thanks!

  12. Attractive section of content. I just stumbled upon your website and in accession capital to assert that I get
    in fact enjoyed account your blog posts. Anyway I
    will be subscribing to your augment and even I achievement you access
    consistently rapidly.

  13. I’m impressed, I must say. Rarely do I encounter a blog
    that’s equally educative and amusing, and let me tell you, you have hit the nail on the head.

    The issue is something which not enough folks
    are speaking intelligently about. Now i’m very happy that I
    found this during my search for something regarding this.

  14. Hello, i think that i saw you visited my web site thus i came to “return the favor”.I’m
    trying to find things to enhance my site!I suppose its
    ok to use some of your ideas!!

  15. Howdy just wanted to give you a brief heads up and let
    you know a few of the pictures aren’t loading correctly.
    I’m not sure why but I think its a linking issue.
    I’ve tried it in two different web browsers and both show the same results.

  16. Hey just wanted to give you a quick heads up.
    The words in your content seem to be running off the screen in Ie.
    I’m not sure if this is a formatting issue or something to do with browser
    compatibility but I figured I’d post to let you know.

    The design and style look great though! Hope you
    get the issue fixed soon. Thanks

  17. hello there and thank you for your information – I have certainly picked up something new from right here.
    I did however expertise some technical issues using this site, as I experienced to reload the web site a lot of times previous
    to I could get it to load properly. I had been wondering if your web host is OK?
    Not that I’m complaining, but sluggish loading instances times will very frequently affect your placement in google and could damage your quality score
    if ads and marketing with Adwords. Anyway I’m adding this RSS to my email and can look out for much more of
    your respective exciting content. Ensure that you update this again very soon.

  18. Your method of telling the whole thing in this article is truly fastidious, every one
    be able to effortlessly understand it, Thanks a lot.

  19. Hey! This is my first visit to your blog! We are a group of volunteers and
    starting a new initiative in a community in the same niche.

    Your blog provided us valuable information to work on. You have
    done a marvellous job!

  20. I’m extremely impressed together with your writing
    abilities and also with the format for your weblog.
    Is this a paid theme or did you modify it yourself?

    Either way stay up the excellent quality writing,
    it is uncommon to peer a nice blog like this one today..

  21. With havin so much content do you ever run into any problems
    of plagorism or copyright violation? My website has a lot of completely
    unique content I’ve either created myself or outsourced but it appears
    a lot of it is popping it up all over the web without my
    authorization. Do you know any ways to help protect against content from being ripped
    off? I’d certainly appreciate it.

  22. No matter if some one searches for his vital thing, thus he/she wishes to
    be available that in detail, so that thing is maintained
    over here.

  23. Hello there, You have done a great job. I will definitely digg it and personally suggest
    to my friends. I am sure they will be benefited from this site.

  24. Just want to say your article is as amazing.

    The clearness in your post is simply spectacular and i
    can assume you are an expert on this subject. Well with your permission let me to grab your
    RSS feed to keep up to date with forthcoming post.
    Thanks a million and please continue the rewarding
    work.

  25. Your style is so unique in comparison to other folks I have read stuff from.
    I appreciate you for posting when you have the opportunity, Guess I will just bookmark this web
    site.

  26. Excellent items from you, man. I have consider your stuff
    previous to and you are simply extremely fantastic. I really
    like what you’ve bought here, certainly like what you’re stating and the
    best way through which you assert it. You are making it entertaining and
    you continue to take care of to stay it smart. I can not wait to
    read far more from you. This is really a great website.

  27. When someone writes an post he/she retains the image of a user in his/her mind that how a user can understand it.
    Therefore that’s why this article is perfect. Thanks!

  28. Thank you, I have recently been searching for information about
    this subject for ages and yours is the best I have discovered till now.
    However, what in regards to the bottom line? Are you sure about the supply?

  29. What i do not understood is if truth be told how you’re not actually a lot more well-appreciated than you
    may be now. You’re so intelligent. You know therefore considerably
    on the subject of this topic, made me individually believe it from so many various angles.

    Its like men and women are not interested unless it’s one thing to
    do with Girl gaga! Your individual stuffs nice. Always deal with it up!

  30. Hi there, I discovered your blog by means of Google
    even as searching for a similar subject, your website got here up,
    it seems to be good. I’ve bookmarked it in my google bookmarks.

    Hello there, just was aware of your blog through Google, and located that
    it’s really informative. I’m gonna watch out for brussels.
    I’ll be grateful should you continue this in future.
    Numerous other people can be benefited out of your writing.

    Cheers!

  31. We’re a gaggle of volunteers and opening a brand new scheme in our community.

    Your web site provided us with valuable info to work
    on. You have done an impressive process and our whole neighborhood will be thankful to you.

  32. At this time it appears like Expression Engine is the top blogging platform available right now.
    (from what I’ve read) Is that what you’re using on your blog?

  33. I have been browsing online greater than three hours nowadays, but I
    never discovered any interesting article like yours.
    It is pretty price enough for me. In my opinion, if
    all website owners and bloggers made good content as you did, the web can be a
    lot more useful than ever before.

  34. Hey, I think your blog might be having browser
    compatibility issues. When I look at your website in Opera,
    it looks fine but when opening in Internet Explorer, it
    has some overlapping. I just wanted to give you a quick heads up!
    Other then that, superb blog!

  35. I do agree with all of the ideas you have
    offered to your post. They are really convincing and can certainly work.
    Still, the posts are too short for beginners. May you please extend them a bit from subsequent time?
    Thank you for the post.

  36. Hello! I know this is kind of off topic but I was wondering which blog platform are you using for this website?
    I’m getting fed up of WordPress because I’ve had issues with hackers and I’m looking at alternatives for another platform.
    I would be great if you could point me in the direction of a good
    platform.

  37. Thank you for the good writeup. It in fact was a
    amusement account it. Look advanced to far added agreeable from you!
    However, how can we communicate?

  38. Write more, thats all I have to say. Literally, it seems as though you relied
    on the video to make your point. You definitely know what youre talking about, why waste your intelligence on just posting videos to your site when you could
    be giving us something informative to read?

  39. You’re so cool! I do not think I’ve truly read anything like
    this before. So good to discover someone with original thoughts on this subject.
    Seriously.. many thanks for starting this up. This web
    site is something that’s needed on the web,
    someone with a bit of originality!

  40. Hi everybody, here every one is sharing these know-how, therefore it’s
    nice to read this blog, and I used to go to see this website all the time.

  41. Write more, thats all I have to say. Literally, it seems as though you relied on the
    video to make your point. You definitely know what youre talking about, why waste your intelligence on just
    posting videos to your site when you could be giving us something enlightening
    to read?

  42. Simply wish to say your article is as surprising. The clarity for your publish is just great and
    i could think you are a professional on this subject. Fine
    together with your permission allow me to take hold of your feed to stay up
    to date with impending post. Thank you 1,000,000 and
    please carry on the rewarding work.

  43. I blog quite often and I seriously appreciate your content.
    The article has really peaked my interest. I am going
    to bookmark your website and keep checking for new information about once per week.
    I opted in for your RSS feed too.

  44. An outstanding share! I have just forwarded this onto a co-worker who was conducting a little homework on this.
    And he actually bought me breakfast because I found it
    for him… lol. So allow me to reword this…. Thank YOU for the meal!!
    But yeah, thanx for spending some time to discuss
    this issue here on your web page.

  45. Currently it seems like WordPress is the top blogging platform available
    right now. (from what I’ve read) Is that what you are using on your blog?

  46. It’s really very difficult in this full of activity life to listen news on TV, so I only
    use the web for that reason, and get the hottest information.

  47. My coder is trying to convince me to move to .net
    from PHP. I have always disliked the idea because of the expenses.
    But he’s tryiong none the less. I’ve been using WordPress on a number of websites for
    about a year and am anxious about switching to another platform.
    I have heard great things about blogengine.net. Is there a way
    I can transfer all my wordpress posts into it? Any help would be greatly appreciated!

  48. Pretty great post. I simply stumbled upon your weblog and wanted to say that I have really loved browsing your weblog posts.
    In any case I will be subscribing in your feed and I
    am hoping you write again very soon!

  49. Today, I went to the beach front with my children. I found a sea shell and gave it to
    my 4 year old daughter and said “You can hear the ocean if you put this to your ear.” She placed the shell to her ear and screamed.
    There was a hermit crab inside and it pinched her ear.
    She never wants to go back! LoL I know this is entirely
    off topic but I had to tell someone!

  50. Hmm it looks like your blog ate my first comment (it was
    extremely long) so I guess I’ll just sum it up what I submitted and say, I’m thoroughly enjoying your blog.
    I too am an aspiring blog blogger but I’m still new to the whole thing.
    Do you have any tips for beginner blog writers? I’d genuinely appreciate it.

  51. Hey I am so delighted I found your blog page, I really found you by accident, while I
    was searching on Yahoo for something else,
    Regardless I am here now and would just like to say
    thanks a lot for a remarkable post and a all round entertaining blog
    (I also love the theme/design), I don’t have time to browse
    it all at the minute but I have book-marked it and also included your RSS feeds,
    so when I have time I will be back to read a lot more, Please do keep up the superb job.

  52. I know this website presents quality depending articles or reviews and additional stuff,
    is there any other website which presents these kinds of information in quality?

  53. Good day! This is kind of off topic but I need some guidance
    from an established blog. Is it very hard to
    set up your own blog? I’m not very techincal but I can figure things out pretty quick.

    I’m thinking about setting up my own but I’m not sure where to start.
    Do you have any tips or suggestions? Appreciate it

  54. Having read this I believed it was extremely informative.
    I appreciate you spending some time and effort to put this
    article together. I once again find myself personally spending a lot
    of time both reading and posting comments. But so what, it was
    still worth it!

  55. Hi! I know this is kind of off topic but I was wondering which
    blog platform are you using for this website? I’m
    getting fed up of WordPress because I’ve had issues with hackers and I’m looking at options for another platform.
    I would be fantastic if you could point me in the direction of a good platform.

  56. Good day I am so delighted I found your site, I really found
    you by accident, while I was browsing on Bing for something else, Regardless I
    am here now and would just like to say many thanks for a fantastic post and a all
    round enjoyable blog (I also love the theme/design), I don’t have time to browse it all at the moment but I have bookmarked it and also added your RSS
    feeds, so when I have time I will be back to read a lot more,
    Please do keep up the superb jo.

  57. I loved as much as you’ll receive carried out right here.
    The sketch is tasteful, your authored subject matter
    stylish. nonetheless, you command get got an nervousness over that you wish be delivering the following.
    unwell unquestionably come more formerly again since exactly the same nearly
    very often inside case you shield this increase.

  58. Hello! I could have sworn I’ve been to this website before but after browsing through
    some of the post I realized it’s new to me.

    Anyways, I’m definitely delighted I found it and I’ll be bookmarking and checking back often!

  59. Thanks for ones marvelous posting! I truly enjoyed reading it,
    you are a great author.I will be sure to bookmark your blog and will eventually come back at some point.
    I want to encourage you continue your great work, have a nice
    morning!

  60. Hello there, just became aware of your blog through Google,
    and found that it’s really informative. I am going to watch
    out for brussels. I will be grateful if you continue this in future.
    Numerous people will be benefited from your writing. Cheers!

  61. I’ve learn a few excellent stuff here. Definitely value bookmarking
    for revisiting. I wonder how a lot attempt you put to make this type of excellent informative site.

  62. Hello! Do you know if they make any plugins to protect against hackers?
    I’m kinda paranoid about losing everything I’ve worked hard on. Any tips?

  63. It’s perfect time to make some plans for the
    long run and it is time to be happy. I’ve read this publish
    and if I may just I desire to recommend you few interesting things or suggestions.
    Perhaps you could write next articles referring to this article.
    I desire to read more issues about it!

  64. whoah this weblog is great i love reading your posts.

    Keep up the great work! You know, many individuals are
    searching around for this info, you can aid them greatly.

  65. I am no longer certain the place you’re getting your info, but great
    topic. I needs to spend a while learning more or figuring out
    more. Thanks for wonderful information I was looking for this information for
    my mission.

Leave a Reply

Your email address will not be published.