GitLab Next

I created this issue to document the feedback provided by @nfriend about the usability of the utility class library. The other goal is using the issue for a technical discovery process where we can explore solutions to all these problems. The outcome of this process is spawning one or more issues that target a specific problem with a proposed solution. The following content is a exact copy of the feedback he wrote in gitlab!48062 (comment 462623022).

Documentation/discovery

The best way I've found to discover which utilities are available is to browse to https://unpkg.com/browse/@gitlab/ui@latest/src/scss/utilities.scss and search the page for the CSS property I want to apply. This works okay, but it's not quite as easy I'm used to (for example, when working with Tailwind (example)).

Incompleteness

Related to the point above, there's a lot of utility variants that simply aren't implemented. So unlike a Tailwind project, where I can mostly go by memory with the expectation that all the variants are available to me, I have to check the documentation for every utility I use to make sure it's implemented. (For example, as part of this MR, I had to add gl-md-flex-direction-column.)

Inconsistency

The naming conventions are just inconsistent enough that I have to check the documentation every time I use a utility. For example, display: flex utilities are formatted like this: gl-display-sm-none, while the align-items utilities puts the breakpoint modifier right after the gl: gl-sm-align-items-flex-end.

In addition, some breakpoint utilities are implemented using @media (min-width: ...) while others are implemented using @media (max-width: ...). For example, this one uses min-width:

.gl-sm-align-items-flex-end {
  @media (min-width: $breakpoint-sm) {
    align-items: flex-end;
  }
}

while this one uses max-width:

.gl-sm-flex-direction-column {
  @media (max-width: $breakpoint-md) {
    @include gl-flex-direction-column;
  }
}

This makes it hard to compose several utilities together, since their behavior isn't consistent beyond their defined size. It also will lead to cases where more than one variant will be applied (for example, when the screen size exactly equals $breakpoint-sm).

In addition, some rules are simply incorrect:

.gl-sm-pr-5 {
  @media (max-width: $breakpoint-sm) {
    padding-right: $gl-spacing-scale-5;
  }
}

(This rule will only apply for xs screens, since the breakpoint variables define the lower bound.)

Implementation

In order to make a larger breakpoint style override a "base" style, I found I had to use the ! version of the utilities, for example:

gl-flex-direction-row gl-md-flex-direction-column!

I don't have to think about this when using Bootstrap/Tailwind utilities - I feel like I should be able to just do:

gl-flex-direction-row gl-md-flex-direction-column

(Not exactly sure how Bootstrap/Tailwind accomplish this, but it works.)

Okay, so what's the fix?

My personal opinion is that almost all of these problems could be mitigated/removed entirely by introducing more automation into our SCSS utility generation. If we automate the process of generating all variants of a particular rule, we would guarantee:

1. Consistent naming conventions (i.e. gl-<breakpoint>-<rule name>-<value>)
2. Complete implementation (all variants of a particular rule would always be available)
3. Consistent responsive implementations (all variants are generated using the same @media rules)

... all of which would make the documentation much less important, since developers could code by memory once they understood the conventions.

We would probably have to pair this with PurgeCSS on GitLab's side, because generating the utilities would result in a lot of unused CSS that would otherwise be a big bloat. (This is the approach Tailwind uses.)