[CSS utilities TG] Add best practice regarding selectors

Problem to solve

While replacing custom legacy util CSS classes with Tailwind CSS classes, we found util CSS Classes being used in stylesheets as selector.

Example:

.gl-mb-5 {
  margin-bottom: $gl-spacing-scale-5;
}

.gl-mt-5 {
  margin-top: $gl-spacing-scale-5;
}

div.gl-display-flex:last-of-type {
  @include gl-display-none;
}

Although technically working, there are two potential problems with this approach:

  1. It creates more effort in the Tailwind CSS migration. Because instead of replacing CSS classes in HTML files (.haml, .vue...), also CSS files have to be checked for occurrences.
  2. Regardless of the migration, the usage of util CSS classes is likely to change. At some point a developer might want to change the margin from gl-mt-5 gl-mb-5 to gl-mt-4 gl-mb-4. Or a developer might want to refactor is to gl-my-5. Or a gl-display-flex gets changed to `gl-flex. These changes will lead to a bug, because the selector in the CSS file would then be incorrect. This gets harder to maintain and we want to prevent this.

To improve the developer experience, we want to document that util CSS classes should not be used as selectors in CSS files.

The goal of this issue is not to replace or fix them. In this issue, we want to add a section in the Best practices documentation.

Further details

To find more examples where util CSS classes are used as selector in the codebase try grepping for .gl- in *.scss files.

Other links/references

Similar to !158787 (merged)

Edited by Vanessa Otto