Make frontend UI libraries great again (with npm and living style-guides)
Over the last 2/3 weeks I’ve been building out a front-end UI library for internal use at Pathship. Something most web startups don’t have the time for is the luxury of extensive documentation, so I sought to throw that frustrating stereotype in the trash and build something seriously powerful and useful in the little time I had spare, in-between shouting at build failures and authoring new UI components.
The following is a thinkpiece-cum-explanation-cum-tutorial of what my process was for building it out, going into various levels of detail along the way.
The goals I set myself for what the new library should cover were simple enough but difficult to quantify. Nonetheless — they were:
- that we’d be able to build at least 80% of all new designs with the components that exist in the library
- that a living styleguide would be available as part of the same codebase as the UI library
- that we could use it as npm dependency in other projects without bundling the styleguide files with it
Solving the problem of extensibility by soothsaying
When I say soothsaying, I actually mean predicting the future.
Yup. You basically need to be able to see the future. Predicting what’s to come is key to being able to deliver product faster than everybody else.
So now we have our first problem — a UI library that can build the vast majority of any future design thrown at you. It sounds like something you can shake your stick at, but I can assure you it’s 100% possible.
I’ve found the most effective method for keeping your UI code DRY is to get good at identifying patterns in your UI designs that are repeatable. Repeatable UI is reusable UI. Conversely, being able to draw the line in the right spot between 100% abstraction and specificity is a skill in itself (protip: it is always different).
I worked very closely with the designers on my team to ensure they consistently stuck to a set of rules we already reasoned about for our UI, and if you’re building out a library you should endeavour to do the same (unless of course, you’re the designer and UI architect. In which case, talking to yourself is fine. I do it all the time).
Enough jibber-jabber. I’ll make Mr T. mad. Let’s get to the good stuff.
Identifying patterns
For argument’s sake, let’s say you’re building a chat UI.
In your head you can probably already visualise and identify repeating patterns in the UI. Here’s an example;
Right away you can probably see a lot of UI components that repeat themselves. Even without being aware of the “real” content in this example, it’s very easy to spot which parts we can abstract into their own dedicated UI component.
There’s a lot of instances where there are what seems to be an image next to some textual content. This pattern is suitable to be re-used.
These headers appear at the top of a couple of areas in the UI. It’s likely that this kind of feature would be used again in future designs, so this kind of pattern is suitable for re-use too.
Buttons are (well, they should be) part and parcel of every UI kit you’ll ever see on the web. They’re something that’s very highly reusable by nature so we can abstract that out too.
Building patterns
Identifying UI patterns is only half of the work. It’s all well and good being able to figure out what you can abstract, but if you’re not able to execute well you’re gonna have a bad time.
Before you start building UI, you should define how you’re going to write your styles in the first place. Put a naming convention in place and enforce sensible authorship rules for your styles before you begin; it’ll save you a world of pain later when you’re knee deep in a refactor if your class-names are consistently named and namespaced properly.
Here’s an example of a namespacing ruleset. This is one I’ve built and refined over the course of my time as a frontend developer.
“a-” Atomic class
Atomic classes are inspired by Atomic CSS. I dislike the terseness of Atomic class-names because at a glance they’re very hard for a developer to parse. I recommend being explicit versus implicit in regards to class-name definitions.
Atomic classes should follow the Single Responsibility Principle (S.R.P.) and affect only one property per definition at a time.
“o-” Object class
Object classes are where we’d define repeatable UI patterns, like the ones we identified above. Objects should define layout and very little else. Objects should never rely on a component.
“c-” Component class
A “component” is a bespoke, implementation-specific piece of UI. If something’s difficult to break down and abstract, it should probably be a component.
“i-” Immutable class
Immutability is a concept that doesn’t truly exist in CSS, but we can somewhat simulate it by using !important in class definitions pro-actively as opposed to reactively. Never use !important to fix something, only use it to prevent something.
“is-, has-” Stateful classes
Stolen shamelessly from SMACSS. These indicate that a piece of UI is in/has a given state.
“js-” Used for binding to with JS
What it says on the tin, really.
Styleguide time
At this point let’s assume you’ve built your library, and you’re happy with it. Now comes the time to document it!
I explored a lot of different solutions for building a styleguide, but in the end I opted for Knyle Style Sheets (KSS), which is mature in comparison to many other solutions out there.
I opted for it because it’s not very intrusive and is compatible with any pre-processor (e.g. Sass, Less, Stylus etc). It also took the least time to set up, and getting it to generate a guide was a breeze. I won’t go into too much depth here as KSS is well documented — long story short I build the style-guide using a gulp task. The task parses the comments in your styles directory and spits out a neatly organised style-guide with no other intervention necessary.
Making it a dependency
After exploring several different methods for making our UI library available as a dependency, I ended up at what I believe to be the simplest and most elegant solution.
npm allows you to define a project dependency as a Git repository. This is useful for a few reasons, but the major points that were important for me were:
- I’m able to update the style-guide as needed without having to change my authorship process
- I can get the updated UI library in a project just by typing npm update.
tl;dr
Here’s the scoop, ya’ll.
- Keep your styles DRY
- Document them using KSS
- Keep your code in git
- Build your style-guide using something like gulp
- Define your style-guide as an npm dependency
If you enjoyed this post or have any feedback/questions, feel free to get in touch with me on twitter @doot0 or throw a comment at this post.
Thanks!
