Style Guide Driven Development with React

Filed under:


Style guides and pattern libraries are a great collaboration and communication tool in cross-functional teams. These tools have many names and variations (see, but in this post I'll just call them style guides. Essentially they break down the user interface into its component parts, and serve as a resource for new designers and developers to locate existing patterns for further use. Decoupling the UI from application data, and splitting the UI into components often results in a more consistent and efficient UI for users.


Style guides are often static, with no direct connection with the app templates. As Ian Feather emphasizes in his excellent article, A Maintainable Style Guide, once your style guide falls out of sync with your application it has entirely lost its purpose. So how can we ensure your style guide is relevant and always up-to-date?

Main Style Guide types

So far, I've worked with the following four main types of style guides:

I prefer the last option: a living style guide with the same shared components used everywhere. I've worked with style guides on different tech stacks over the years, but since I nowadays work a lot with React, I've created a simple Living Style Guide with React on Github.

I didn't do much styling as I wanted to keep things simple in this project. If you want to read more on how to structure your CSS, see Architecting CSS for Responsive Large Scale Applications.

Style Guide Driven Development

Having a style guide drive your design and development work really helps in establishing a shared vocabulary in the team. It also helps in finding patterns in the UI, saving extra development time as we can consolidate similar components. We want to create atomic design systems, not pages, so having all the components in one place ensures that we can test and iterate over them more easily. When you need new components, build them first in the style guide, consuming the same data than your app does. Then you can mix and match these components to compose pages for production.

Finally, I don't think style guides can be fully automated. They are part of the workflow, showing the whole organization's commitment to a coherent design system. You'll want to define your components - and the data they consume - one way or the other, and also describe their usage for team members with different roles. This is just one way of doing it. I hope you find it useful - and as usual, feedback is appreciated on how to make it better.

Living Style Guide with React on Github