Design tokens > Evaluate grey text mass migration potential

#455676 (closed) allowed us to easily see color usage in the GitLab code scanner. https://gitlab-org.gitlab.io/frontend/playground/gitlab-code-scanner/?search=check_id%20co%20%22color%22

There are lots of grey-400/grey-500/grey-600 usage for text (1600 ??)

This issue: Case-by-case decisions are expected to take too long. Figure out if there are general rules that can get us 90% of the way there.

Considerations

  • Goal is a series of rules that can find $grey-* values and replace them with semantic design tokens.
  • This work will result in minor visual changes.
  • This work will not be perfect, and some manual clean up will be needed after.

Risks

  • This find and replace will not be perfect. In the absence of good guidance, those building GitLab may copy a 'false positive' migration, increasing the amount of debt.

Migration examples

Utility classes

Background color

- <div class="gl-bg-white">...</div>
+ <div class="gl-bg-default">...</div>

note: tread carefully when updating $white to a semantic token and validate in browser in both light and dark mode. $white is updated to gray.900 in dark mode, whereas background.color.default is color.neutral.950 in dark mode.

- <div class="gl-bg-gray-10">...</div>
+ <div class="gl-bg-subtle">...</div>
- <div class="gl-bg-gray-50">...</div>
+ <div class="gl-bg-strong">...</div>

Text color

- <div class="gl-text-gray-500">...</div>
+ <div class="gl-text-subtle">...</div>
- <div class="gl-text-gray-900">...</div>
+ <div class="gl-text-default">...</div>
- <h2 class="gl-text-gray-900">...</h2>
+ <h2 class="gl-text-heading">...</h2>

Icon color

note: use of variant prop on GlIcon

- <gl-icon class="gl-text-gray-500"/>
+ <gl-icon variant="subtle"/>

SCSS variables

Background color

.selector {
-   background-color: $white;
+   @apply gl-bg-default;
}

note: tread carefully when updating $white to a semantic token and validate in browser in both light and dark mode. $white is updated to gray.900 in dark mode, whereas background.color.default is color.neutral.950 in dark mode.

.selector {
-   background-color: $gray-10;
+   @apply gl-bg-subtle;
}
.selector {
-   background-color: $gray-50;
+   @apply gl-bg-strong;
}

Text color

.selector {
-   color: $gray-500;
+   @apply gl-text-subtle;
}
.selector {
-   color: $gray-900;
+   @apply gl-text-default;
}
h2 {
-   color: $gray-900;
+   @apply gl-text-heading;
}

Icon color

note: Tailwind config has icon design tokens for fill property, to add for color we will need to update build_tokens.js in GitLab UI to add to const colors = { ... }

svg {
-   color: $gray-500;
+   @apply gl-fill-icon-subtle;
}

Otherwise we can use the CSS custom property directly:

svg {
-   color: $gray-500;
+   color: var(--gl-fill-icon-subtle);
}
.gl-icon {
  /* update the component itself and not override component styles in SCSS */
}
Edited by Scott de Jonge