• Utility Classes
  • Tailwind CSS
    • Building the Tailwind CSS bundle
  • Where are utility classes defined?
  • Where should you put new utility classes?
  • When should you create component classes?
  • Utility mixins
• Naming
• Nesting
• Selectors with a js- Prefix
• Using extend at-rule
• Linting

SCSS style guide

Utility Classes

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

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.

Building the Tailwind CSS bundle

When using Vite or Webpack with the GitLab Development Kit, Tailwind CSS watches for file changes to build detected utilities on the fly.

To build a fresh Tailwind CSS bundle, run yarn tailwindcss:build. This is the script that gets called internally when building production assets with bundle exec rake gitlab:assets:compile.

However the bundle gets built, the output is saved to app/assets/builds/tailwind.css.

Where are utility classes defined?

Utility classes are generated by Tailwind CSS. To see available utility classes install the VSCode Tailwind CSS IntelliSense plugin or if you are using RubyMine the autocomplete should be available by default.

There are also legacy utility classes defined in config/helpers/tailwind/css_in_js.js. These utility classes do not comply with Tailwind naming conventions and will be iteratively migrated to the Tailwind equivalent. Please do not add new instances of these utility classes, instead use the Tailwind equivalent.

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.

Where should you put new utility classes?

Utility classes are generated by Tailwind CSS which supports most CSS features. If there is something that is not available we should update tailwind.defaults.js in GitLab UI.

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, you can use the @apply directive to add Tailwind styles to a CSS selector. @apply should be used for any CSS properties that are dependent on our design system (e.g. margin, padding). For CSS properties that are unit-less (e.g display: flex) it is okay to use CSS properties directly.

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

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

// Okay
.my-class {
  display: flex;
}

// Good
.my-class {
  @apply gl-mt-5 gl-flex;
}

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.