1--- 2stage: none 3group: unassigned 4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 5disqus_identifier: 'https://docs.gitlab.com/ee/development/fe_guide/style_guide_scss.html' 6--- 7 8# SCSS style guide 9 10This style guide recommends best practices for SCSS to make styles easy to read, 11easy to maintain, and performant for the end-user. 12 13## Rules 14 15Our CSS is a mixture of current and legacy approaches. That means sometimes it may be difficult to follow this guide to the letter; it means you are likely to run into exceptions, where following the guide is difficult to impossible without major effort. In those cases, you may work with your reviewers and maintainers to identify an approach that does not fit these rules. Please endeavor to limit these cases. 16 17### Utility Classes 18 19In 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. 20 21#### Where are utility classes defined? 22 23Prefer the use of [utility classes defined in GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/css.md#utilities). 24 25<!-- vale gitlab.Spelling = NO --> 26 27An easy list of classes can also be [seen on Unpkg](https://unpkg.com/browse/@gitlab/ui/src/scss/utilities.scss). 28 29<!-- vale gitlab.Spelling = YES --> 30 31Classes in [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/stylesheets/utilities.scss) and [`common.scss`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/stylesheets/framework/common.scss) are being deprecated. 32Classes in [`common.scss`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/stylesheets/framework/common.scss) that use non-design-system values should be avoided. Use classes with conforming values instead. 33 34Avoid [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/). 35 36NOTE: 37While migrating [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/) 38to the [GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/css.md#utilities) 39utility classes, note both the classes for margin and padding differ. The size scale used at 40GitLab differs from the scale used in the Bootstrap library. For a Bootstrap padding or margin 41utility, you may need to double the size of the applied utility to achieve the same visual 42result (such as `ml-1` becoming `gl-ml-2`). 43 44#### Where should I put new utility classes? 45 46If a class you need has not been added to GitLab UI, you get to add it! Follow the naming patterns documented in the [utility files](https://gitlab.com/gitlab-org/gitlab-ui/-/tree/main/src/scss/utility-mixins) and refer to [GitLab UI's CSS documentation](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/contributing/adding_css.md#adding-utility-mixins) for more details, especially about adding responsive and stateful rules. 47 48If it is not possible to wait for a GitLab UI update (generally one day), add the class to [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/stylesheets/utilities.scss) following the same naming conventions documented in GitLab UI. A follow-up issue to backport the class to GitLab UI and delete it from GitLab should be opened. 49 50#### When should I create component classes? 51 52We recommend a "utility-first" approach. 53 541. Start with utility classes. 551. If composing utility classes into a component class removes code duplication and encapsulates a clear responsibility, do it. 56 57This 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`). 58 59Inspiration: 60 61- <https://tailwindcss.com/docs/utility-first> 62- <https://tailwindcss.com/docs/extracting-components> 63 64### Naming 65 66Filenames should use `snake_case`. 67 68CSS classes should use the `lowercase-hyphenated` format rather than 69`snake_case` or `camelCase`. 70 71```scss 72// Bad 73.class_name { 74 color: #fff; 75} 76 77// Bad 78.className { 79 color: #fff; 80} 81 82// Good 83.class-name { 84 color: #fff; 85} 86``` 87 88Class names should be used instead of tag name selectors. 89Using tag name selectors is discouraged because they can affect 90unintended elements in the hierarchy. 91 92```scss 93// Bad 94ul { 95 color: #fff; 96} 97 98// Good 99.class-name { 100 color: #fff; 101} 102 103// Best 104// prefer an existing utility class over adding existing styles 105``` 106 107Class names are also preferable to IDs. Rules that use IDs 108are not-reusable, as there can only be one affected element on 109the page. 110 111```scss 112// Bad 113#my-element { 114 padding: 0; 115} 116 117// Good 118.my-element { 119 padding: 0; 120} 121``` 122 123### Selectors with a `js-` Prefix 124 125Do not use any selector prefixed with `js-` for styling purposes. These 126selectors are intended for use only with JavaScript to allow for removal or 127renaming without breaking styling. 128 129### Variables 130 131Before adding a new variable for a color or a size, guarantee: 132 133- There isn't an existing one. 134- There isn't a similar one we can use instead. 135 136### Using `extend` at-rule 137 138Usage of the `extend` at-rule is prohibited due to [memory leaks](https://gitlab.com/gitlab-org/gitlab/-/issues/323021) and [the rule doesn't work as it should to](https://sass-lang.com/documentation/breaking-changes/extend-compound). Use mixins instead: 139 140```scss 141// Bad 142.gl-pt-3 { 143 padding-top: 12px; 144} 145 146.my-element { 147 @extend .gl-pt-3; 148} 149 150// compiles to 151.gl-pt-3, .my-element { 152 padding-top: 12px; 153} 154 155// Good 156@mixing gl-pt-3 { 157 padding-top: 12px; 158} 159 160.my-element { 161 @include gl-pt-3; 162} 163 164// compiles to 165.my-element { 166 padding-top: 12px; 167} 168``` 169 170## Linting 171 172We use [stylelint](https://stylelint.io) to check for style guide conformity. It uses the 173ruleset in `.stylelintrc` and rules from [our SCSS configuration](https://gitlab.com/gitlab-org/frontend/gitlab-stylelint-config). `.stylelintrc` is located in the home directory of the project. 174 175To 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 176catch any warnings. 177 178If the Rake task is throwing warnings you don't understand, SCSS Lint's 179documentation includes [a full list of their rules](https://stylelint.io/user-guide/rules/list/). 180 181### Fixing issues 182 183If you want to automate changing a large portion of the codebase to conform to 184the SCSS style guide, you can use [CSSComb](https://github.com/csscomb/csscomb.js). First install 185[Node](https://github.com/nodejs/node) and [npm](https://www.npmjs.com/), then run `npm install csscomb -g` to install 186CSSComb globally (system-wide). Run it in the GitLab directory with 187`csscomb app/assets/stylesheets` to automatically fix issues with CSS/SCSS. 188 189Note that this doesn't fix every problem, but it should fix a majority. 190