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 they 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 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.
What is the problem? A “simple” one to express:
How do I, as the person that has to write the code, collaborate with the designer and/or UX person that is dreaming up whatever it is I build?
There are buttons, drop-downs, forms, animations and whatnot 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 has been 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, let’s say, an 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 questions, such as:
– “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
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 see how we can solve the next one: engaging with UX people and designers.
Enter Storybook. Storybook is a great tool for showing our React components. At a basic level, it is just a React application itself that displays our React components. The way it works is by writing “stories” that describe how the components are to be displayed and set up. 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 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 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:
Basic Storybook layout
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; on 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:
Storybook demo (from getstorybook.io)
So not only can we see what it is we are coding, but now the designer, the UXer, the product owner, QA – or anyone else you may be interacting with – can see what you are talking/asking/working with/feeling good about. So we have just found a way to quickly demo our code and discuss, review, update, discuss, review update, etc. 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 set up 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 set up). So now we have the attention of the wider team. Great, onwards!
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 are 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.
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.
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 checkboxes without having to manually modify the story. Here’s what it looks like:
Storybook knobs plugin
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 also 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.
So far we have a static site, which anyone (whether involved in the project or not) can access, and:
- See what components are available
- Interact with the components properties and test them
- Test how responsive they are
All the above is great but, wouldn’t it be even 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 auto-generates 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.
- 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 to 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 is 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 solutions.
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. The ability to tie comments to a component version is yet to come. But new features and ideas are there, and 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.
The above has so far helped us in tackling some of the collaboration issues we have encountered. Developers, UX people and designers now have a better set of tools to create a living style guide and work within a design system, to be able to provide much quicker feedback and to collaborate in an Agile environment.
In the end, the actual tools do not matter that much – it is the principles, the features, and 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! 🙂