Forem Creators and Builders

Cover image for Forem's CSS Utility Classes
Nick Taylor
Nick Taylor

Posted on • Updated on

Forem's CSS Utility Classes

When I joined in January of this year, I had a call with one of our product designers, Pawel (@pp).

We discussed the design system that was to be built and I was on board for surfacing it in Storybook. It is still a work in progress, but you can see it in action at

Fast forward a bit and we had another discussion about CSS. We opted to go with bespoke CSS utility classes.

Here's Pawel's PR for that if you're interested

CSS Components, Variables + Utility classes #6334

What type of PR is this? (check all applicable)

  • [x] Refactor


This PR is another step towards our design system. It should mostly NOT affect how the website is rendered - it only introduces bunch of CSS files with components and variables that are not yet referenced anywhere. It's purely frontend infrastructure work. The only exception is adding reset.scss file which can cause tiny visual differences (mostly in line-heights --> alignment of elements) but hopefully not breaking things.

Except adding variables AND components, this PR also brings [utility-first classes], for example:

.mr-4 --> margin-right: 1rem;
.fs-2xl --> font-size: 1.25rem;
.overflow-auto --> overflow: auto;

Main purpose of this is to let our devs NOT write any CSS anymore (well, soon) so if they have to build a view/feature they would use bunch of available classes like <div class="flex mr-4 p-2">.... Thanks to this we will stay consistent across whole website. It would also greatly reduce our CSS and all the spaghetti code we have in here so far.

In this PR, I've only introduced SOME classes like that. There's more to come. I also don't want to simply import whole tailwind library so we can have full control over what we need.

If you wanna learn more about utility-first classes go to, for example, - this CSS framework is all about utility-first classes and they explain lots of concepts pretty well.

🔸🔸🔸FYI: This PR does NOT bring The Tailwind Framework to the codebase 🔸🔸🔸

Related Tickets & Documents

Added tests?

  • [x] no, because they aren't needed

Added to documentation?

  • [x] no documentation needed

For those that have contributed to the Forem code base in the frontend, at some point, you have most likely touched some CSS. Not many have used our CSS utility classes though unless it was brought up as there is no documentation for it. Even core team members aren't really aware!

This PR changes that. Now there will be documentation hosted for utility classes in Storybook. At the time of writing, the PR is still in review, but will most likely be merged this week. It's merged!

Auto-generate CSS utility classes documentation in Storybook #9633

What type of PR is this? (check all applicable)

  • [ ] Refactor
  • [ ] Feature
  • [ ] Bug Fix
  • [ ] Optimization
  • [x] Documentation Update
  • [x] Developer experience


CSS utility classes are generated by the file. This PR generates CSS from that file and parses the CSS style sheet to auto-generate Storybook stories to provide documentation for CSS utility classes.

CSS utility classes are grouped by the property they modify. In some cases, some utility classes modify more than one CSS property. In cases like that, the utility class is grouped in each CSS property it modifies.

CSS utility classes will typically have values set with the !important attribute so as to work with pre-design system CSS.

Also noteworthy is CSS properties in the auto-generated documentation point to MDN.


Related Tickets & Documents

QA Instructions, Screenshots, Recordings


To test:

Added tests?

  • [x] yes
  • [ ] no, because they aren't needed
  • [ ] no, because I need help

Added to documentation?

  • [ ]
  • [ ] readme
  • [x] no documentation needed

[optional] Are there any post deployment tasks we need to perform?

[optional] What gif best describes this PR or how it makes you feel?

Mr. Krabs from Sponge Bob saying "I'll show you automated!"

It's mentioned in the PR, but you can check out the PR's Storybook so that you can see it in action.

Also, thanks to Storybook's built-in filtering, it's easy to find a utility class, e.g. searching for flex.

Screenshot of Forem's Storybook with CSS utility class documentation being filtered

If you have any questions or feedback, feel free to drop a comment in the PR, send me a connect message on or hit me up on Twitter.

Looking forward to your future contributions!

Discussion (5)

link2twenty profile image
Andrew Bone

Sort of related, just noticed this while scrolling down the page on mobile.

Z index

I think it's need a z-index change for the liquid tag.

pp profile image
Paweł Ludwiczak

Good catch. As old saying says:

z-indexes are hard...

I'll give it a look.

link2twenty profile image
Andrew Bone • Edited on

Specifically it's this section.

Is it worth having some z-index levels in crayons?

$appBar: 100;
$drawer: 200;
$modal: 300;
$notification: 400;
$tooltip: 500;
Enter fullscreen mode Exit fullscreen mode
Thread Thread
pp profile image
Paweł Ludwiczak

Definitely, that's our goal. But it's more tricky than it sounds: we have lots of legacy code from "pre-crayons" era when z-indexes were pretty random :D Most of the new (crayons) stuff is pretty much in good place in terms of handling z-indexes but you know - as long as we have some legacy code in the codebase the z-index conflicts are unavoidable. And we can just keep fixing them slowly, one by one.

amorpheuz profile image
Yash Dave

This is awesome! 😁 I would love to see a mention of Storybook and the docs under Could be a great issue for first time contributors?