What it does is it gives you a very nice graphical representation of the items in the bundle. It is interactive as well so you can zoom in/out and see what gets what.

Setup

Setting it up in your repo is very simple. The docs are pretty comprehensive really but here’s a quick summary.

1. add the package to your repo: npm install -D webpack-bundle-analyzer.
2. Add the the following options to your webpack script --profile —-json stats.json. This will output the stats to stats.json.
3. Run webpack-bundle-analyzer stats.json from the command line (or just add it as a script in your package.json.

Here’s what your package.json will look like:

"build": "webpack <your options> --profile --json > stats.json",
"build:analyze": "npm run build && npm run webpack-bundle-analyzer stats.json"

This way, you can just run npm run build:analyze which will build your app and then show the analyzer.

Why is this useful

If you need to look at why your bundle size is too big, this tool is a great start. In our case our external packages looked like this:

This shows all the external packages we load into our project. One thing that stuck out was lodash. While we do use lodash, we do not use all of it, so this showed somewhere in our code we were importing the entire library vs just the bits we need. This is easy to miss if you import usingimport { map } from 'lodash' vs import map from 'lodash/map' .

A quick fix later our bundle is 500KB smaller:

Not bad. Now, time to go through all the other stuff (I’m looking at you moment.js…).

1. Let’s say we have 10 versions of our style guide released as static Storybook builds.
2. These builds all use an addon (the versions one in our case).
3. That the addon has a bug, which we have now fixed.
4. That’s all very nice and we can now release a new version of our style guide with includes the addon with the fix.
5. But what about the rest of the published guides with the buggy addon?

On the face of it, it looks like we’d have to go back and rebuild every single version. Luckily, that is not the case. When you create a static Storybook build, you end up with something like this:

What you’re getting in that build is, first the index.html which will load your style guide. That loads the static/manager.<hash>.bundle.js which is the main storybook interface, which in turns uses the iframe.html to display your stories. The stories are in static/preview.<hash>.bundle.js

As such, what we can do is replace index.html and static/manager... and that will have any updates we may have done in the packages and addons. However, since the configuration (what goes in .storybook/config.js) is bundled with the stories in the preview file, we cannot make any changes of that sort.

Overall, a nice thing to know as we can now retrofit updates to storybook and its addons without having to checkout and rebuild each older version of our style guide. Obviously there is the caveat of making changes to an addon that are incompatible with the stories, plus the usual dangers of retrofitting stuff to released software. But it can still be helpful to know all the above, when it comes to releasing bug fixes to our style guide. Hope this helps!

Versions

Obviously, we are using React Storybook for our living style guide. I won’t bore you with what it can or cannot do yet again, however one of the important things it does is that we can build a static version of it. As such, when you commit your code (or merge to master or finish your sprint, whatever your process is), your build pipeline can run a simple npm script to generate a static version of Storybook. Therefore, you can then automatically deploy that to a host of your choice and let anyone see what the current state of your component library is. Since all this is automated, it is easy to end up with a bunch of builds for your UI library hosted together. So we may end-up with a folder structure that perhaps looks like this:

- static-storybook
|-- 0.2.4
|-- 0.2.5
|-- 0.2.6
|-- 0.3.0

So now we can navigate to our different storybook folders and see what each different version looks like, say http://styleguides/0.2.5/ for version 0.2.5. However, there is no way to actually do that from within Storybook. To solve this, we created the versions add-on. What this does is that it adds a new panel showing you the various versions available. For the time being, the way the plugin works is that it expects to find a JSON file in the root of the host, giving info about what versions are installed and what the path pattern is (which is a regex, which is black magic).

{
  "storybook": {
    "versions": [
      "0.2.4",
      "0.2.5",
      "0.2.6",
      "0.3.0"
    ],
    "regex": "\/([^\/]+?)\/?$"
  }
}

See the documentation for more information on how to set it up.

With it all setup then, the add-on is installed and the config available. Here is what it looks like. In the example below we have a button component with the style changing between different versions (we are using the info add-on to add the documentation around the component).

Nice and simple then, and we can now travel back and forth in versions, seeing how a component evolved. Add the ability to comment with blabbr and you now have a living style guide, showing you all the different versions of your components and all the discussions around them.

Additionally, there is a “dev” checkbox, which shows a “local dev” button. This is handy as when you are running your Storybook locally as a developer, you will want to see what the code you are writing does. However, you can still navigate to the other versions, living on another host, as long as your config is valid. But then, once you go to the official version, how do you go back to your local dev version? Just enable the dev mode and the flag travels across the versions (as URL params, like all other Storybook options) and you can go back & forth.

Simple. Hope it helps. :-)

Let’s start with a bit of history. In the beginning there was Sketch (bear with me in this first section). Actually probably Photoshop. Or some other tool like that. You probably know the story, a designer (and I will use the term loosely here, can be UX, can be UI, can be visual designer, service designer or even a dev who paid the $99 to get Sketch) spends quite a bit of time in Sketch creating some super cool assets, then finally hits the export button. A PDF is generated, GreatDesign.pdf, it is promptly emailed to the development team and everyone is happy. Eventually some changes are done in the next sprint or ten by said designer (or maybe another one), another PDF is generated, GreatDesign_v2.pdf, repeat the emailing and so on. Then some more changes are done, because some things were forgotten, and, finally, we have the final version of the design. So now we have GreatDesign_final.pdf. And that’s it. Or is it? Wait, we forgot a few things so, finally, finally, we have GreatDesign_final_final.pdf. Or do we? Because there is also a GreatDesign_final_final(1).pdf. Oh dear. Oh dear. Oh dear indeed.

Ok enough with the third rate sarcasm! Things have moved on a bit from the above, there’s stuff like Axure, Zeplin, InDesign and a few more that sprang up while you are reading this. At least your designs are organised; developers have a link to go get the latest; we can all agree what the right version is. You can even get some code samples or even fully working prototypes (the value of which, when it comes to how usable the code is, we can debate another time). Let’s have a brief look at what the workflow may look like using these tools to create a couple of apps:

I’ll assume some basic knowledge of what Sketch does so I’ll concentrate on the rest. You could argue that the PDF is now obsolete and there are tools like Zeplin. However, with Zeplin while we may get some measurements on how things should be laid out and also get some autogenerated CSS, we still need to manually copy and paste all that into our code. Additionally, Zeplin will not tell us how the responsive layout should work, what happens in the in between states and other things like that. It is just a nicer way of handing over from design to dev. As such, there is a whole raft of things that are left open to interpretation, plus a lot more that will just fall through the cracks and not surface till QA has a go at our app. Still, it is an improvement as we now have an easier way to get to the design vs trawling emails and PDFs.

Let’s see where we are now. It is easy to find the designs but what about the code? Right now, the only way to see what assets are there is to look at the code, the actual apps, and then take screenshots to catalogue them. Not that easy. Now, in our particular case these happen to be React apps. As such we can do something very easy: use Storybook. I’ve written a bit about the React toolchain here but, in a nutshell, Storybook will visualise our components, our actual React components, without having to run the app. As such we can now catalogue our components.

Let’s see those apps then. We’ve taken the example of a bank on this occasion and we made a couple of simple apps: one to see your account statements and another one to pay someone.

Looking at them (please ignore the garish design, this was a POC made to look a bit off on purpose), we quickly see that we have a couple of common things: a header and a footer. In fact we probably have three, a header, a footer and the buttons. Or maybe we have a few more, like section titles and so on, depending how we break them down (atomic design anyone?). We may also note that the buttons are different: one app has square buttons, the other rounded ones. This is a reality (not for a button specifically but for consistency overall) for many organisations where designs have to be translated to code again and again. The same design ends up slightly different in various parts of the system and, sometimes, even the design files end up diverging.

As such, the next step is obvious: create a component library! I say obvious but it is surprising how many organisations actually do not have one. So let’s see how things will look with a component library.

As such, we now have a library of common components. We can update them in one place instead of two (or three, or ten, or fifty). Not only that, but notice how we have gone from two manual updates (copy/paste) in the first diagram, to one automated export plus two manual updates in the second diagram, to three automated updates and one manual action in this. We are now automating more things than we do manually. As such we are now close to using the automation capabilities of our CI environment as part of the design process. For now, our library is packaged and distributed and any updates end up in the apps automatically.

Additionally, we can use Storybook in our library to see the components, plus use the rest of the capabilities that come with it: interacting, testing, commenting (again, see this on how Storybook helps with all that).

What we now have is a sort of living style guide within the development domain. However that still leaves the rest of the process outside. In the video above, the last thing we see is someone commenting that the colours are all wrong. What next?

As it is now, a designer would have to make a change in Sketch/Zeplin. The developers would then have to deconstruct what they see, interpret it and write the code for it. That bit in the middle, the “interpret”, is where mistakes happen. Let’s see how we can improve on that.

Enter Brand.ai. The first thing Brand.ai does is to give us a Sketch plugin. As such we can now export from Sketch to brand.ai components, styles, images, etc. We can also upload assets direct to Brand.ai. For example, we can have all our logos and colours for the brand identity. We also get bidirectional updates: update something in Brand.ai and the Sketch file gets updated too.

The next important thing it has is an API to extract that info. Therefore, within the build process of our app, we can hit that URL, download the latest assets and use them. Here’s what our system now looks like.

Notice how we no longer have any manual steps (by which I mean copy and paste type stuff). We have linked design into our CI environment. Finally, to enhance collaboration and distribution of information, we can hook into Slack and get notifications. When updates occur we get notified that a new version exists. When we comment on blabbr, we get notifications on Slack. Here’s what it actually looks like when working with it:

All the above show us is how we now can update our UI library, automatically, by initiating a change in Sketch. Once we can do that we are ready to update the actual apps as well. As such, we now have end to end flow, from design to production. That last word, “production” is the most significant one as that is what our customers get to see. It is important to realise that in our diagram above, once we hit the app box (App 1, App 2, etc) what I mean is that we are hitting the point where the app is ready to be deployed to a live environment.

Hold on. You may ask that its probably a bit too much trouble all this. We’ve added yet more tools, changed a lot in our environments, our processes, how people work and all that to get rid of that manual step in Figure 2. Yes we have. Let’s have a look at that diagram again:

That is a nice little example of a very simple system. The reality is that for starters, there is another line from Zeplin to each of the apps. The reason? Our UI library may have a lot of components but it will not have all of them. There are always app specific things and, in any case, the views are owned by the app. These need to exist as code too. So our diagram is now this.

This also covers just one platform. Most places will have a mobile platform, web and web apps too. You may have a few dozen apps per platform too. As such we would be looking at something like this:

That is a lot of manual work, work that will inevitably go wrong, things will get misinterpreted and as such quality and consistency will rapidly decline. It is also interesting to see that since the jump from Zeplin to the library is manual, the automation to the right of each library will simply amplify any errors. Here is the alternative:

Still a lot of lines but at least they’re all linked. So any mistakes can be rectified very quickly, any updates too and we are always taking advantage of all the CI tooling. If we collapse this back to the lines via the libraries only this is what we have.

You’ll notice I rearranged the library boxes a bit. We now have a web (ie HTML/CSS) library, a web app (ie some JS framework like React) and mobile. Imagine then how we can start sharing some styles between the different components. In the end the top two are both running in a browser, as such with a bit of clever thinking we can start sharing CSS between them. In fact we could share CSS with our mobile components too, depending on our technology choices.

That may start looking complicated quickly. However, the importance of it is that we have now automated changes. We have also reduced the number of sources. Instead of having a plethora of styleguides, PDFs, Zeplin pages and the rest we have a living styleguide. This gives us access to the actual components that are going to be deployed to production, as such we no longer have to make assumptions about what will be delivered, we are looking at it.

We can also start prototyping without having to use off colours or fake components. We can do that using actual components and styles. The importance of this cannot be underestimated. How many times have we found designs, styles and code that were supposed to be “just a throwaway POC” in production? I’ve certainly found them myself, I even put them there on occasion. In fact, let’s have a look at how this looks like.

We can see then how a working prototype can now be created using our existing components. We can also see what components are available and thus make some more informed decisions, as opposed to a prototype coming up with more and more components that are just ever so slightly different to what is in the library, this either increasing the number of components or ending up using components that do not do exactly what is needed.

We can keep going and start adding more concepts, showing how testing fits in, eg kicking off accessibility testing well before the app is created, how copywriters can try new copy using the living style guides, et cetera, etc…

People do not make mistakes on purpose. They do not set off to write bad code. They do not start a new UI kit just because they want to play or introduce inconsistency. In the vast majority of cases, these things happen simply because they just want to get on with the job of building something vs trying to find what to use to build it. In some cases it is even just down to internal barriers, perhaps a department not sharing their designs & code or just IT security making it impossible to share a PDF or use a hosted service. So people find workarounds hoping they will do something good.

What we are trying in this particular instance is to:

• make collaboration as easy and smooth as possible
• automate as many steps as possible to reduce mistakes and inconsistencies
• make as much as possible visible for others to find, thus encouraging reuse and eliminating waste

I have probably over-simplified a few things. I’ve also used certain technologies and tools in the above example, but that is purely as these are the things we are currently using. That doesn’t mean that what we are doing is limited to just those. In any case, whatever we choose today will probably be gone in 3 years and there is something new starting as I type this. What matters are the principles that drive a design system as these are what DesOps need to apply and support. Hopefully our little example here can help demonstrate some of the things we can do, in order to get everyone working closer and better together.

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:

1. when working with a UX/UI person we can quickly try different parameters to see how the control responds.
2. 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! :-)