Replace Bootstrap4 utility classes with in-house utility classes

Description

The Bootstrap4 utility classes have some significant downsides:

Ideally, we remove the import of bootstrap/scss/utilities and replace it with either:

  • Option 1: A custom utilities.scss we base off an existing framework
  • Option 2: A third party functional css library (with an aliases.scss to keep support references to preexisting BS4 classes)

Analysis

With the advent of the CSS-Gitlab UI working group and the commitment of our time to a wholesale CSS refresh, now seems to be the right time to beef up our utility classes into a full-fledged set of comprehensive options. (For an example, see the Tailwind documentation.) By doing this, we gain two of the big pros of a utility-first system: the reduction of CSS file churn and a brake on the growth of CSS files. That is, developers should be able to access all the classes they need for a standard styling job from the utilities and should therefore not be adding things into CSS. That means when we do add something it becomes indicative — either we missed a needed utility, the implementor has misunderstood the system, or we have a new design element — and we can get the attention of UX and maintainers onto the situation.

Beyond the clashes noted above, the Bootstrap4 utility classes are not comprehensive enough to cover all cases, especially in terms of spacing (width, margin, padding).

This leaves us with the two options above, creating our own custom utilities based off a third-party framework or using a third-party framework itself — probably Tailwind or Tachyons.

For the custom option, the primary pros are we do not need to change our build process and we can use Bootstrap4 names, reducing the number of changes that need to be made to affected files. The downsides are that it is more work — we do have to add the utility code. We will also need to generate our own class-name documentation in order to support developers in learning the pattern of names / finding the needed utility. In order to be comprehensive, we will need to use a third-party library as a guide.

For the third-party option, the pros are less CSS/SCSS work on our end — a more comprehensive starting point. Both are reliant on PostCSS, so we would have to add a build step in, but we do already have Webpack setup. The PostCSS step also removes unused classes from the built CSS, I believe, and so the resulting stylesheet would not need to include all the style rules — only those we are using.

Proposal

Let's create our own set of utility classes.

  • Support the BS4 utility class names as aliases.
  • Include the more comprehensive set of classes according to our design system and using Tailwind as a reference.
  • This utility CSS would live in gitlab-ui (gitlab-ui#160 (closed)).
Edited by Takuya Noguchi