SCSS style guide

Utility Classes

NOTE: Please do not use any utilities that are prefixed with gl-deprecated-, instead use a Tailwind utility.

In order to reduce the generation of more CSS as our site grows, prefer the use of utility classes over adding new CSS. In complex cases, CSS can be addressed by adding component classes.

Tailwind CSS migration

We are in the process of migrating our CSS utility class setup to Tailwind CSS. See the Tailwind CSS blueprint for motivation, proposal, and implementation details.

Where are utility classes defined?

Prefer the use of utility classes defined in GitLab UI.

An easy list of classes can also be seen on Unpkg.

Or using an extension like CSS Class completion.

Classes in utilities.scss and common.scss are being deprecated. Classes in common.scss that use non-design-system values should be avoided. Use classes with conforming values instead.

Avoid Bootstrap's Utility Classes.

NOTE: While migrating Bootstrap's Utility Classes to the GitLab UI utility classes, note both the classes for margin and padding differ. The size scale used at GitLab differs from the scale used in the Bootstrap library. For a Bootstrap padding or margin utility, you may need to double the size of the applied utility to achieve the same visual result (such as ml-1 becoming gl-ml-2).

Where should you put new utility classes?

Because we are in the process of migrating to Tailwind the utility class you need may already be available from Tailwind. The IntelliSense for VS Code plugin will tell you what utility classes are available. If the utility class you need is not available from Tailwind, you should continue to use the utility classes defined in GitLab UI which can be seen on Unpkg. If the utility class is still not available we need to enable a new core plugin in Tailwind. Find the relevant core plugin and open a MR to add the core plugin to the corePlugins array in tailwind.defaults.js.

When should you create component classes?

We recommend a "utility-first" approach.

1. Start with utility classes.
2. If composing utility classes into a component class removes code duplication and encapsulates a clear responsibility, do it.

This encourages an organic growth of component classes and prevents the creation of one-off non-reusable classes. Also, the kind of classes that emerge from "utility-first" tend to be design-centered (for example, .button, .alert, .card) rather than domain-centered (for example, .security-report-widget, .commit-header-icon).

Inspiration:

• https://tailwindcss.com/docs/utility-first
• https://tailwindcss.com/docs/extracting-components

Utility mixins

We are currently in the process of migrating to Tailwind. The migration removes utility mixins so please do not add any new usages of utility mixins. Instead use pre-defined CSS keywords with SCSS variables.

// Bad
.my-class {
  @include gl-mt-3;
}

// Very bad
.my-class {
  @include gl-deprecated-mt-3;
}

// Bad
.my-class {
  margin-top: 0.5rem;
}

// Good
.my-class {
  margin-top: $gl-spacing-scale-3;
}

Naming

Filenames should use snake_case.

CSS classes should use the lowercase-hyphenated format rather than snake_case or camelCase.

// Bad
.class_name {
  color: #fff;
}

// Bad
.className {
  color: #fff;
}

// Good
.class-name {
  color: #fff;
}

Avoid making compound class names with SCSS & features. It makes searching for usages harder, and provides limited benefit.

// Bad
.class {
  &-name {
    color: orange;
  }
}

// Good
.class-name {
  color: #fff;
}

Class names should be used instead of tag name selectors. Using tag name selectors is discouraged because they can affect unintended elements in the hierarchy.

// Bad
ul {
  color: #fff;
}

// Good
.class-name {
  color: #fff;
}

// Best
// prefer an existing utility class over adding existing styles

Class names are also preferable to IDs. Rules that use IDs are not-reusable, as there can only be one affected element on the page.

// Bad
#my-element {
  padding: 0;
}

// Good
.my-element {
  padding: 0;
}

Nesting

Avoid unnecessary nesting. The extra specificity of a wrapper component makes things harder to override.

// Bad
.component-container {
  .component-header {
    /* ... */
  }

  .component-body {
    /* ... */
  }
}

// Good
.component-container {
  /* ... */
}

.component-header {
  /* ... */
}

.component-body {
  /* ... */
}

Selectors with a js- Prefix

Do not use any selector prefixed with js- for styling purposes. These selectors are intended for use only with JavaScript to allow for removal or renaming without breaking styling.

Using extend at-rule

Usage of the extend at-rule is prohibited due to memory leaks and the rule doesn't work as it should.

Linting

We use stylelint to check for style guide conformity. It uses the ruleset in .stylelintrc and rules from our SCSS configuration. .stylelintrc is located in the home directory of the project.

To check if any warnings are produced by your changes, run yarn lint:stylelint in the GitLab directory. Stylelint also runs in GitLab CI/CD to catch any warnings.

If the Rake task is throwing warnings you don't understand, SCSS Lint's documentation includes a full list of their rules.