Using React within a Design System
You’ve probably have heard about concepts like Design Systems and Atomic Design so far (if you haven’t please do read those two articles as some prior knowledge is assumed). You’ve read about all the goodness they can bring to teams building digital experiences and how it can bring designers and developers together, working in harmony, iterating quickly and getting awesome apps to their customers. But what does it actually mean, if you’re on the, let’s face it, receiving end of it as a developer? What can we, the developers, coders and the people that actually build the “stuff”, do to both be part of a design system, plus make both our and our non-coder colleagues’ lives easier?
Let’s look at some of the tools we are employing to help get things done.
The Problem
What is the problem? A “simple” one to express:
How do I, as the person that has to write the code, can collaborate with the designer and/or UX person that dreams up whatever it is I build?
There are buttons, drop-downs, forms, animations and what-not that we have to build, day-in, day-out to create the various apps we put out for our customers to use. The traditional approach so far was that some UX person does what a UX person does, then a UI designer does what a UI designer does and eventually a developer ends up with some PDF or PSD file that has a breakdown of the, let’s say, address details form to decipher and build. By the time the code is done, the UI/UX people have moved on and the developer has a raft of unanswered answers:
- “John Smith” fits nicely in that box but what about “Maria de Los Angeles Hernandez”?
- …so the form breaks to the smaller layout at 800px while the header does so at 750px…?
In any case, these questions are likely not to even be asked until QA has picked this up, which in some cases can be weeks after the code was done. Where I’m getting at is this: by the time the issues are done, nobody knows where the design came from, who coded it and why it was even required. So we might as well release it, because the boss is asking for something, anything, to be released. The big red deploy button is pressed and…everyone is disappointed. The customer, the designers, the developers, the CEO. Predictably, it is your fault for not implementing the glossy design properly.
So what can we do? Let’s look at a few actual things then that we can do today.
React + Atomic Design = UI Library
Hopefully you know what React is (again, if not, look it up, it’s great). I’m using React here simply because this is what we used for this particular project. There area myriad other things you can use in Javascript to get the same effect. Overall there are tons of things that React lets you do, but the one thing it does fit in with here is this: it is really easy to create UI component libraries, based on a Atomic Design principles, that can be reused and shared between projects.
So, step one, we are using React. It makes it easy for the developers to keep components nice and small and atomic, which solves our immediate problem, as developers, on how we organise our code. That still leaves the rest of the issues though. Let’s how we can solve the next one: engaging with UX & designers.
Storybook
Enter Storybook. Storybook is a great tool for showing our React components. At a basic level it is just a React application itself which displays our React components. The way it works is by writing “stories” that describe how the components are to be displayed and setup. This is similar to writing a unit test and the syntax is very simple. Here’s a one line explanation from the docs:
Technically, a story is a function that returns a React element.
If we start to look at what it gives a developer, on their local machine, it is this: the ability to visualise the React components without having to run the actual application being developed. The advantage of this is that we can now view our component, interact with it (after all, this is a React app using our React components) and see very quickly what it is we are developing. This cannot be underestimated. The alternative is to either run the actual app, mocking the flow to the point where we can see our new component, or to build some artificial page showing the components. This is what it actually looks like:
As you can see, there is a simple navigation on the left, where we browse the “stories” per component. On the top right we see the actual components; in the bottom right there are a number of plug-in panels we can have, which can do various things (more on that in a bit).
So far pretty sparse. But wait, what we can do is show our components, from Atoms all the way to Pages (or Environments, depending on your naming convention) live, showing changes as we code. Let’s see how that works:
So now, not only can we see what it is we are coding, but the designer, the UXer, the product owner, QA or anyone else you may be interacting with can see what you are talking/asking/working/feeling-good about. So we have just found a way to quickly demo our code, discuss, review, update, discuss, review, update…neat.
But wait. That’s all very nice but isn’t this limited just to my machine? No it is not, Storybook can build a static site that can be hosted wherever we like. As such, we can setup our CI tools to build a new site and push it to whatever hosting environment we use, ready for everyone to see. And there is our demo, automatically built, every time we commit code to our master branch (or however else we want this setup). So now we have the attention of the wider team. Great, onwards!
Plugins
We’ve seen then how Storybook can let us code and see the results on the fly. But what about the static site and what other things we can we do with it? There are a number of plugins that Storybook has which we are going to use to enhance the experience.
Full screen
That is actually not a plugin but part of the built-in Storybook functionality. A keyboard shortcut (also available on the startup config) lets you get rid of the UI and show just the component. As such the user can then test the responsive UI for various screen sizes and devices.
Knobs
First is the knobs plugin, which allows us to play with the component properties. This lets us modify component properties using a number of simple controls like text boxes, drop-down lists and check boxes without having to manually modify the story. Here’s what it looks like:
If we were to write the code for the component above in our story it would probably be like this for the final state:
<Button size=’large’>This is a long label</Button>
To get the different states we would normally create different stories. Any changes would mean a rebuild. However, with the knobs plugin we can just have one story with a number of controls instead. Not only this is faster but it allows two things:
- when working with a UX/UI person we can quickly try different parameters to see how the control responds.
- when statically hosted, non-developers (e.g. QA) can interact with the components and try the various parameters.
Checkpoint
So far we have a static site, which anyone (whether involved in the projector not) can access and:
- see what components are available
- interact with the components properties and test them
- test how responsive they are
Info
All the above is great but, wouldn’t it be greater if we could add some context and information on each component? This is what our next plugin, storybook-addon-info, does. It allows a developer (or whoever is writing the story) to add some information about the component plus it autogenerates a basic usage info and PropType documentation.
The example above shows the component and usage inline (the actual button is rendered at the top, under the heading). The plugin can be configured to show the info on a separate page. That has its advantages, as for complicated components it would make it clearer to inspect the component. The original plugin, linked above, will only allow some basic text info to be added. We have forked the plugin to allow any valid React node to be added, as such the user can add complex HTML documentation, including links to other sites and documents.
As you can see above, there is some basic text, a link and an image. Therefore, we can now add complete documentation on how to use the component, links to the code repository, related information and design documentation plus include screenshots, examples, etc.
Blabbr
So far we’ve seen how we can use Storybook to
- view our components
- interact with them
- demonstrate and make them accessible to others
- test them
- share some information about them.
This is all great but is still one way communication. The next step we want to take is allow people to discuss what they are looking at. There is already a solution for this, Storybook Hub. The problem we are now facing though this: if we are in an environment where we cannot use github or have code hosted externally we need to have our own hosted solution. This is quite common in large organisations. So for such environments we created a stand-alone solution: blabbr.
Blabbr is a plugin that adds a commenting facility in a new plugin panel. The concept is that a user will sign-up and then can post comments for everyone to see. Pretty simple to begin with but great for spurring discussion around components. Currently we are basing this on CouchDB (using PouchDB to provide offline capability). Why CouchDB? Because we had to start with something! Eventually we aim to provide a number of different solution.
For the time being, blabbr is still in alpha. Sign-up is essentially whatever the user wants to use. We ask for a nickname and email simply to tie the comment to a particular user. “Login” is just an entry in the browser’s local storage. Comments are just text. Tying comments to a component version is yet to come. But new features and ideas are there, we are working on a roadmap to effectively make this DB agnostic and provide a slick user experience, while at the same time providing a valuable collaboration facility for everyone involved in the creation of the app.
Final Thoughts
The above have, so far, helped us in tackling some of the collaboration issues we have encountered. Developers, UX and design now have a better set of tools to create a living style guide and work within a design system, to be able to provide feedback much quicker and to collaborate in an Agile environment.
In the end, the actual tools do not matter that much, it is the principles, the features, the attributes of whatever it is we may be using that make up the solution. Hopefully, though, I have given you a small set of tools to tackle some of the issues arising in the all-important team collaboration arena. Good luck! :-)
