Add section to Tailwind docs about autocomplete

Also add section about spacing and colors on official Tailwind docs
and update copy in danger rule

danger/tailwindcss/Dangerfile

@@ -67,15 +67,24 @@ module Danger
       return "" if files_with_legacy_utils.empty?
 
       <<~MARKDOWN
-      ### Legacy utils
+      ### Legacy CSS utility classes
 
-      The following files contain legacy utils:
+      The following files contain legacy CSS utility classes:
       #{format_files_with_legacy_utils_list(files_with_legacy_utils)}
 
-      Use the [Tailwind documentation](https://tailwindcss.com/docs/installation) to find the Tailwind
-      equivalent to these legacy utils. If the Tailwind equivalent is not available it is okay to use the
-      legacy util for now. The Tailwind equivalent will be made available when the corresponding migration issue
+      We are in the process of migrating our CSS utility classes to [Tailwind CSS](https://tailwindcss.com/).
+      The above CSS utility classes do not comply with Tailwind CSS naming conventions.
+      Please use the Tailwind CSS equivalent if it is available.
+      For more information on how to determine what CSS utility classes to use see
+      our [Tailwind CSS developer documentation](https://docs.gitlab.com/ee/development/fe_guide/style/scss.html#tailwind-css).
+
+      If the Tailwind CSS equivalent is not available, it is okay to use the legacy CSS utility class for now.
+      The Tailwind CSS equivalent will be made available when the corresponding migration issue
       in [&13521](https://gitlab.com/groups/gitlab-org/-/epics/13521) is completed.
+
+      If a legacy CSS utility class is listed above but you did not change it in this MR it is okay to leave for now.
+      If it is a small or simple MR, feel free to leave the code better than you found it and migrate those
+      legacy CSS utility classes to Tailwind CSS.
       MARKDOWN
     end
 

doc/development/fe_guide/style/scss.md

@@ -10,6 +10,25 @@ info: Any user with at least the Maintainer role can merge updates to this conte
 
 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.
 
+### Where are CSS utility classes defined?
+
+Utility classes are generated by [Tailwind CSS](https://tailwindcss.com/). Use [Tailwind CSS autocomplete](#tailwind-css-autocomplete) or the [official Tailwind CSS documentation](#official-tailwind-css-documentation) to see available CSS utility classes.
+
+There are also legacy CSS utility classes defined in `config/helpers/tailwind/css_in_js.js`. These CSS utility classes do not comply with Tailwind CSS naming conventions and will be [iteratively migrated](https://gitlab.com/groups/gitlab-org/-/epics/13521) to the Tailwind CSS equivalent. Please do not add new instances of these CSS utility classes, instead use the Tailwind CSS equivalent.
+
+Classes 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.
+Classes 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.
+
+Avoid [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/).
+
+NOTE:
+While migrating [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/)
+to the [GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/css.md#utilities)
+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`).
+
 ### Tailwind CSS
 
 We are in the process of migrating our CSS utility class setup to [Tailwind CSS](https://tailwindcss.com/).
@@ -26,24 +45,54 @@ called internally when building production assets with `bundle exec rake gitlab:
 
 However the bundle gets built, the output is saved to `app/assets/builds/tailwind.css`.
 
-### Where are utility classes defined?
+#### Tailwind CSS autocomplete
 
-Utility classes are generated by [Tailwind CSS](https://tailwindcss.com/). To see available utility classes install the [VS Code Tailwind CSS IntelliSense plugin](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) or if you are using RubyMine the autocomplete should be available by default.
+Tailwind CSS autocomplete will list all available classes in your code editor. Keep in mind it will also list legacy CSS utilities. Unfortunately we don't have a way to mark the legacy CSS utility classes in the autocomplete so try to cross reference with the [official Tailwind CSS documentation](#official-tailwind-css-documentation) if you are unsure.
 
-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.
+##### VS Code
 
-Classes 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.
-Classes 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.
+Install the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension. For best results and HAML and custom `*-class` prop support these are the recommended settings:
 
-Avoid [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/).
+```json
+{
+  "tailwindCSS.experimental.classRegex": [
+    ["class: [\"|']+([^\"|']*)[\"|']+", "([a-zA-Z0-9\\-:!/]+)"],
+    ["(\\.[\\w\\-.]+)[\\n\\=\\{\\s]", "([\\w\\-]+)"],
+    ["[a-z]+-class(?:es)?=\"([^'\"]*)\""]
+  ],
+  "tailwindCSS.emmetCompletions": true,
+  "editor.inlineSuggest.enabled": true,
+  "editor.quickSuggestions": {
+    "strings": true
+  },
+  "css.validate": false
+}
+```
 
-NOTE:
-While migrating [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/)
-to the [GitLab UI](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/doc/css.md#utilities)
-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`).
+##### RubyMine
+
+Tailwind CSS autocomplete is [enabled by default](https://www.jetbrains.com/help/ruby/tailwind-css.html).
+For full HAML and custom `*-class` prop support these are the recommended updates to the default settings:
+
+```json
+{
+  "includeLanguages": {
+    "haml": "html"
+  },
+  "emmetCompletions": true,
+  "experimental": {
+    "classRegex": [
+      ["class: [\"|']+([^\"|']*)[\"|']+", "([a-zA-Z0-9\\-:!/]+)"],
+      ["(\\.[\\w\\-.]+)[\\n\\=\\{\\s]", "([\\w\\-]+)"],
+      ["[a-z]+-class(?:es)?=\"([^'\"]*)\""]
+    ]
+  }
+}
+```
+
+#### Official Tailwind CSS documentation
+
+GitLab defines its own Tailwind CSS config in [https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/tailwind.defaults.js](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/tailwind.defaults.js) to match the Pajamas design system and to prefix CSS utility classes with `gl-`. This means that in the [official Tailwind CSS documentation](https://tailwindcss.com/docs/installation) the spacing, sizing, and color CSS utility classes may not match. Also, the `gl-` prefix will not be shown. Here is our [spacing scale](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/tailwind.defaults.js#L51) and [colors](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/main/tailwind.defaults.js#L8). In the future we plan to utilize [Tailwind config viewer](https://github.com/rogden/tailwind-config-viewer) to have a Tailwind CSS documentation site specific to GitLab.
 
 ### Where should you put new utility classes?