Wallace Sidhrée
Apr 8 · 6 min read
In a style-guide far, far away…

The best way to keep an overview over the intended UX while developing an application is through a style-guide. It’s a great tool to identify challenges between the intended UX and the HTML implementation.

Fortunately, maintaining a style-guide as an integral part of a web application has become a norm within the web development industry. It ensures consistency and reflects the expected interactivity, while building a bridge between business goals, UX and development.

And yet a style-guide might not be enough when components are put into their final context.

Components (composite elements with intrinsic logic that render content based on properties passed to them) are usually self-contained in a typical style-guide, but even when 100% of their styles are shared and well integrated, certain styles need to remain undefined as we don’t know in which context these components might be used.

Take for instance vertical spacing. One could define it at the component level, but in complex applications it may vary depending on unpredictable conditions: is the heading above an image, an introductory text or a quote? What might come under it and how much vertical space should there be in each case?

In a very flexible and modular UX, we don’t always know how things like vertical spacing will render before the context is determined

That’s why I tend to resort to helper classes, which I can use directly, extend, rebuild through SCSS mixins or simply pass to components as properties. The classes to be used can then be set by logic present in the component, which determine the context the component is going to be rendered at.

There are many ways one can define these classes. I have often used this flavour:

The SCSS above outputs this CSS:

Somewhat lengthy, but does the job pretty well. Keep the $space-values list short, with only what you need. The classes can be extended, included in a mixin or used directly, like so:

If you intend to visualise these bottom margins using the technique that follows, you must define (or pass) these classes directly on the markup.

The values could be modified to use rem rem units instead of px, or any other unit, but I’ll keep it as it is for the sake of simplicity. In the same light, we’re only going to work with top and bottom margin visualisation in this article.

The need to debug UX by visualising space

This brings me to a project where I had many different scenarios to cover, and the style-guide fell short in spite of being documented and me already using similar helper classes.

The customer was having difficulties to approve the final prototype as it was hard to review “empty spacing” that could not be visualised. Me (the frontender) and my colleague (the UX) felt we needed a better way to ensure the vertical spacing was applied correctly in every case, but at the time we didn’t know exactly how.

A sneak-peak to keep you warmed-up! It’s a treat to see how everything falls into place on different resolutions…

The UX defined all the variations, while I dug deep into every instance, manually, to double-check and make corrections when necessary. It was incredibly time-consuming. One day, as I was using the developer inspector on Chrome, it dawned on me:

What if I could visualise the margins and their values without using the inspector, doing it in such a way that a non-technical person could easily relate to (ie. by clicking on a link)?

This musing summarised our need, and with that in mind I understood that our best opportunity lied in building upon the spacing helper classes we already had. So I ended up with this:

There are quite a few things happening here, but it boils down to using pseudo-elements to both visualise the spacing and output the class name, so both can be seen at a glance. In this case the class name contains the value in pixels, so one also gets the benefit of knowing the value straight away.


There’s a caveat with this approach, though. It becomes obvious when one uses more than one spacing helper class on the same element, as shown below:

One should rather set the margin bottom (`m-b-10`) on the “Did you know…” paragraph, but this is just an example of how a certain context can force us into using top and bottom margin classes in one element.

Since we’re using only one pseudo-element (::before), the last valid condition in the Sass loop will take over, overriding the originally set condition.

This is where ::after comes to our rescue!

Before and after

We have now separated top margin visualisation from bottom margin visualisation. Sometimes they will overlap each other visually, but that turns out to be a “feature” since you now will be able to optimise your vertical spacing in a way that avoids this.

Our helpers are ready and we can visualise top and bottom margins:

A live example of the helper classes in action, and how to apply them

Making it available to others

We’re now ready to engage others in reviewing the vertical spacing, but we can only show them these visualisations on our local machine, since these visualisations are very visible to anyone visiting our page. We have to comment out the styling of these pseudo-elements before eventually pushing it to production.

To enable the visualisation of margins beyond our local machine, we need to load it conditionally.

Let’s say that we’re only going to show these visualisations when an URL parameter is present. This approach is great because it enables us to share preview links to non-tech-savvy people.

One way of getting this to work is by combining JavaScript with CSS:

  • We check the URL for the expected parameter;
  • If the URL has the parameter, assign a class to the body element;
  • Now that the class that triggers the visualisations is present in a wrapping element, show the visualisations.

The URL with the ‘helpers’ parameter:


example.com is now a thing, for real!

The presence of this parameter will give the body the class show-helpers, which will activate the pseudo-elements styling. It doesn’t matter what value is given to the helpers parameter, but it must have a value. In this case I gave it the value 1, but I could have written fuzzy-popcorn, just as well.

It’s all in the final code section below!

Final code

The final SCSS. Note the ‘show-helpers' class doing the heavy lifting.
The JavaScript ❤.

Not a silver bullet

While this is a solution that worked very well for our immediate needs then and there, there’s of course a few caveats to keep in mind:

  • These helper classes must be present in the markup.
  • We can only use two pseudo-elements for these visualisations: ::before and ::after.
  • This approach assumes an aggressive style reset is in place prior to using these helper classes. That’s the only way to reduce all vertical spacing to whatever is defined by these classes.
  • It requires discipline as one has to keep the use these helper classes in mind.

Even though one could choose to omit the use of these helper classes in some sections of the frontend, the best way to empower those reviewing the margins to be debugged is to establish all vertical spacing through these helper classes. Limiting its use to only some sections is possible, but can cause confusion and diminishes the impact of the whole effort.

This is it. I hope you found it interesting and are now adequately teased to have a whack at it. Cheers!


Vi løser digitale hverdagsproblemer! / We make stuff that works.

Wallace Sidhrée

Written by

An OK Dude. Ex Yoga Monk. Senior Frontend Developer. One-man-band Musician. Breather of Air. @sidhree www.sidhree.com



Vi løser digitale hverdagsproblemer! / We make stuff that works.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade