CODEBASE as a Living Style Guide

Problem

When a new small feature request arrives, programmers create yet another inputs/buttons/etc introducing more technical debt & inconsistency to the product, instead of creating a very simple UI by following basic rules and styles, that can be easily observed by just browsing/using/clicking-through the product.

Solution?

Some kind of Living Style Guide or UI Kit or UI Pattern Library tool that's going to help us create consistent UI faster; rather without designers involved.

Analyzing existing tools

First of all, all those helper tools started to pop up because there were not enough communication between developers and designers and there’s too much chaos in the codebase; “every” designer wants to introduce his own “better” styles; and “every” developer wants to implement yet another button with his own approach.

So a new layer of management has to be created to regulate those and to calm those crazy heads down and to bring at least some order to development.

After the investigation and browsing Internet, it’s easy to get that current tools really suck and the positive effect from those tools is very short and can’t even cover the development/integration costs in most cases, especially, if the company/product isn’t huge as Yandex or Google.

Above to that, having such tools integrated limit future development as well.

Reasons NOT to integrate:

  • Locking into 3rd party tech or framework;
  • Hard to maintain in a long time prospect;
  • Maintenance of one is usually prioritized lower;
  • Sample templates differ from actual templates used in real application;
  • Most combinations of templates can’t be foreseen, thus not even worth trying to come up with;
  • Changing developers habits not to crawl in the codebase;

Reasons TO integrate:

  • One credit/reference point;
  • Consistency;
  • Development culture;
  • All styles in one place?; that won’t happen in real life
  • Copy-Paste templates?; as mentioned before, that won’t work

Coming up with a better solution

CODEBASE AS A LIVING STYLE GUIDE

The idea is to write templates with predefined ‘atomic’ modifiers & avoid creating new styles at all, ideally. The workflow remains the same: no need to reference some external sites or read the Internet or what; the only difference is trying to avoid writing CSS as much as possible.

PROS

  • No need to maintain, as the latest codebase state is the latest state;
  • One credit/reference point — it’s our code;
  • Consistency
  • Development culture;
  • All styles in one place;
  • Copy-Paste templates;
  • No 3rd-party lock in;
  • No need to change developers habits;
  • Codebase grows a slower;

CONS

  • There’s no live site that display our ‘style guide’, but our site is;
  • Templates may become verbose;

Example of atomic CSS modifiers:

.text-left { }
.text-primary { }
.panel { }
.delimiter-slim { }
.push-top-small { }
.pull-bottom-big { }

Example of usage aforementioned:

<div class="col-md-12">
<div class="panel panel-default">
<div class="container-fluid">
            <div class="row" ng-repeat="patient in filteredPatients()">
<div class="col-md-12 text-left">
<div class="flex-container push-top-smaller push-bottom-smaller">
<div class="flex-col">
<div class="photo default placeholder push-top-smaller"></div>
</div>
<div class="flex-col-gap"></div>
<div class="flex-col flex-col-autosize">
<div class="text-highlighted push-bottom-smaller">
<a href="#" ui-sref="">
<h3 class="reset-margin"></h3>
</a>
</div>
<div class="text-default push-bottom-small">
</div>
<div class="text-secondary push-top-bigger">
<div class="push-bottom-small"></div>
</div>
</div>
<div class="flex-col flex-col-gap"></div>
<div class="flex-col flex-col-align-self-center">
<a href="#" ui-sref="patients.modal.details({patient: patient})"><div class="icon icon-go"></div></a>
</div>
</div>
<div class="delimiter-slim delimiter-slim-compansate-col-padding-right"></div>
</div>
</div>
        </div>
</div>
</div>

No custom CSS was written for the whole chunk! We use what’s already created. When we need spacing for the element, we use .push-DIRECTION-SIZE. When you want a text alignment in a block, just add .text-[left,center,right] to the parent block. And so on...

There’s no magic in our codebase nor rocket science in our designs, so more probably that the block you want to create is already created somewhere: save your time and browse the dashboard to see where you can find such a block or ask anyone, instead of writing yet another chunk of CSS that won’t be reused.

Oh, and yes, when you’re using atomic modifiers, don’t forget to attach .useUpdatedStyles class on top of your enclosing element/page/section. (ideally, when the whole dashboard is updated, main.scss is cleaned up, we can ditch .useUpdatedStylescompletely)

What you can really do is to try to keep spacing equal on top & bottom; and, of course, when you have to create a new unique component, it’s better to discuss with anyone who has UX/UI authority, before starting doing it, maybe there’s no need to create one, and it was the initial perception that something has to be created.

// More design suggestions here?

So even if you make some mistakes, they can be easily fixed with just renaming classes or tags. The most important part is that template is functional, because if something is off by +/- 10px, but is clickable — it’s ok, but not vice versa. What is more importantly, straight developers will never be able to create interfaces as designers can; no matter how good a Style UI Mega Ultra Guide is.


Why exactly that way?

Our codebase is growing day by day, so why would we want to grow it even more? How the front-end stuff is done today: new task comes in > HTML > CSS > JS. What if we could eliminate at least one step? We can’t go on without tasks, right? Right. Can we launch something without templates? — I don’t think so. JS? — Sometimes, but as we use Angular, we have to write it all the time. When it comes to CSS, we can really avoid growing this part in most cases, by reusing what’s already created and not creating new styles for whatever reason.

Some development principles

There’re some other principles beyond not touching CSS:

  • Leave the code in a better state that you found it.
  • Reuse as much as possible: technologies and components.
  • The entire codebase should look like one person wrote it
  • Keep it simple!!!

Reuse as much as possible

When building new features, try to identify reusable parts which can be abstracted.

Keep it simple

Our codebase is too large to hold in your head and there’s no return in trying to do so. And when you introduce a new functionality with a new way of doing things, you force anyone to learn even more. The easier code is, the easier it is to understand and less time required to start shipping something new or to provide a fix.


Tools/approaches considered:

More related articles:

Real-wolrd success story (showcase):

https://www.smashingmagazine.com/2016/05/creating-a-living-style-guide-case-study/

Excerpt from the end of the article: Even though it’s released, we still have a long way to go

Real-world fail story:

When I was working @ DataRobot, we created the UI Library — a live site with colors, typography, templates, comprehensive components, like buttons and various states, preloaders, links, labels, dropdowns, fade-ins/outs, inputs with optional integrated options, verifications and so on, but developers weren’t happy, because we were forcing them to use it and they didn’t like to use Angular directives.

Developers had various reasons why they don’t like it all the time, no matter what we change. They just wanted freedom, simplicity (but using one-line components is easy, isn’t it?) and they didn’t want to have yet another tool/framework to use. What is more importantly, before we had UI Library created we kept them in the loop what we (designers) are doing and what it will look like and everyone was excited before it was released (not because we created a piece of shit, it was full functional stuff, simplest public example is https://app.datarobot.com/sign-in), because no one really cared (human factor). We had a nice plan, we sold it to CEO, CTO.. Basically we had all the green lights we could get.

Did I tell you that we also tried to teach them to use BEM (or any other alternative that’s ok to dev)?

Everything ended-up by using a limited set of CSS classes we created for directives we worked on (but not directives themselves, because devs found them theoretically limiting..!) and agreement not to alter CSS until it’s really necessary. In another words — almost nothing has changed in the workflow.

End of story.

Like what you read? Give Pavel B. a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.