Skip to content

Case Study: Building a Component Library

Kathryn Grayson Nanz on August 18, 2019

Over the last year and a half, I've been the lead on a project to create and implement a robust Component Library. Our Component Library been a hug... [Read Full]
markdown guide

Thanks - this definitely mirrors my experience. Can I ask: how did you share the components across members of your team? Did you share across teams too (like product, design, engineering)? I'm wondering what the best practices are for getting different teams and people to stay in sync with component libraries. Thanks!


Within the dev team, we have the Component Library set up as it's own repo, so anyone on the team can check it out and make a branch for a new component they'd like to work on. We've already added the Component Library to all our main applications (in the same way you'd add d3, lodash, or any other external js library), so they have access to the components for any projects they're working on. Staying "insync" in that regard is just a matter of running yarn upgrade 'component-library' haha

For non-developers, we have a URL where they can view the Storybook – we use this internally as a kind of brand/style guide. We're in the process of working up to a full Design System, but for now this is helping us bridge the gap, and it allows non-devs to see the components we have as well as some more general brand info like colors, fonts, icons, etc. Beyond that, it's just a word-of-mouth thing – we include new/edited components in our sprint reviews and make a point of reminding folks about the existence of the library when they ask brand style-related questions.

Let me know if this answers your questions!


Really interesting post! I love design systems. Learned a lot from your lessons, I'm currently creating an update to my component library with Atomic Design. I use SCSS with css custom variables to drive the base UI and to easily theme the app (Dark Theme, high contrast themes etc. And generate all the utility classes and atoms components. I try to do this base UI kit framework agnostic so I can use it in both SPA and SSR apps. I use Storybook in this new version, I was using kss in the previous one. I'm looking into giving the ability for designer to download components as well into sketch files so we can all work from the same library. Looking forward to hearing more about your journey !


We're also super interested in finding a way for designers to download sketch (or really any type of editable) files – let me know if you make any progress on that front! I've seen this, but haven't had a chance to actually try it out yet:


Hi Kathryn,

thanks a lot for the nice post!

As you were talking about how component libraries become unmaintained and that you import your components into your projects... I was wondering if there is no way that storybook and your projects use the same files? That way a component library would never be unmaintained as it always shows the actual components of your project.

Also, when you write about "zooming out"... You wrote that you use the atomic design principle. By following that you could also create templates in your component library which gives you the bigger picture, couldn't you? You wouldn't have to wait until the components are imported into your application then.

I was really curious about this post as I recently build my own component library application. So, not the components itself, but basically my own storybook (you can find it here).
What was important for me that I can import it into my project and that it then uses the actual component files, because in my opinion it's absolutely necessary to keep the component library up-to-date - and that it will never stay 100% up-to-date if your project and your component library don't share the same files.

When I work for clients we usually even go a step further and develop a whole dummy implementation of the website in our component library (usually patternlab - unfortunately I wasn't able to use my app with a client yet). That way the frontend can be developed completely independently from the backend. Later on, the backend developers take the files and do the integration. But I guess that's a different use case than what you have in your company.

Anyway, thanks again!



Alright, I want to make sure I answer all your questions, so let me know if I leave anything out, haha!

Re: using the same files – our use case is actually pretty similar to the one you describe at the end of your comment. We also have an application for our Component Library that includes the Storybook UI as well as the components themselves. This blog post describes an approach VERY similar to what we do. Currently, all our apps have the component library added in the same way you would add d3, lodash, or any other external library, so keeping them updated is as simple as running yarn upgrade 'component-library'.

Re: zooming out – in an ideal world, yes. But in a more practical sense, we already had 3 different applications with similar (but not exactly the same) UIs. Our hope was to start creating components that could unify the visual look, so our suite of applications actually felt like a suite – to try and get an "easy win" on this front, we opted to start replacing small components (like buttons, form inputs, etc) to start creating consistency. In doing this, we felt some chafing re: integration of new components into various existing UIs. I think a "pure" Atomic Design approach probably could have fixed this, but only if you were willing to do ALL the design upfront in the Component Library, and not start to implement any of it in actual applications until you had all of it figured out – we opted to start implementing small pieces and adjust as we went. In the long run, I still feel like this was the right move – it's a little bit more agile and iterative, and that fits how we tend to work as a company.

Hopefully this was helpful!


Hi! Nice post! Can I ask: How would you manage your fonts in the case you would not use FontAwesome? I mean, let's imagine if we have one .woff file, and one of the components uses it. How can we tell the client who uses the font that they need to serve this .woff file in their system? should we use a CDN for these font files or what would be the best option? Thanks!


Hey there! Font Awesome actually has a somewhat misleading name – it's an icon font, so it only provides icons; it's not actually a font manager or standard text font.

We found this StackOverflow answer to be helpful when we tackled the issue: Hopefully that's helpful in your situation as well!


Thank you so much for sharing this information, it is the whole tutorial for me. As I am a very beginner in the computer science field I must say I have two great helpers for me, the first one is and this site is the second. I will have my test tomorrow and I don't know what I would do without that comprehensive online practice.

code of conduct - report abuse