Include gitlab-ui utility-class library

Proposal

Let’s include the GitLab UI utility-class library in GitLab, and define a plan to consolidate all existing utility-class libraries across repositories. The purpose of this issue is to track the steps necessary to accomplish this task.

Current utility classes available in Gitlab UI

Phase 1: Identify cases where existing gl class names in Gitlab clash with the Gitlab UI values and rename them.

Grep used:

git grep -E "([\"']|\.|\s)gl-(p|p\w|m|m\w|w|h|border|rounded|font|text|line|fill|vertical|shadow|display|flex|justify|align|relative|absolute|static|bottom|left|overflow|relative|top|right|bottom|cursor|user|bg|transition|opacity|content|fill|white|z|min|outline|inset)\W"
SAME NAME, SAME VALUE
gl- class in Gitlab Gitlab UI equivalent files
gl-pr-0 gl-pr-0 (does not currently exist) app/assets/javascripts/error_tracking_settings/components/error_tracking_form.vue
gl-pl-0 gl-pl-0 app/assets/javascripts/error_tracking_settings/components/error_tracking_form.vue, app/assets/javascripts/error_tracking_settings/components/project_dropdown.vue, ee/app/assets/javascripts/insights/components/insights.vue, ee/app/assets/javascripts/vue_merge_request_widget/components/visual_review_app_link.vue, ee/app/assets/javascripts/status_page_settings/components/settings_form.vue
gl-pt-0 gl-pt-0 ee/app/assets/javascripts/vue_merge_request_widget/components/visual_review_app_link.vue
gl-pb-0 gl-pb-0 (does not currently exist) ee/app/assets/javascripts/vue_merge_request_widget/components/visual_review_app_link.vue
gl-cursor-pointer gl-cursor-pointer app/views/shared/_check_recovery_settings.html.haml, app/assets/javascripts/vue_shared/components/sidebar/collapsed_grouped_date_picker.vue
gl-line-height-24 gl-line-height-24 app/assets/javascripts/vue_merge_request_widget/components/mr_collapsible_extension.vue
gl-bg-blue-50 gl-bg-blue-50 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-bg-red-100 gl-bg-red-100 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-bg-orange-100 gl-bg-orange-100 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-bg-gray-100 gl-bg-gray-100 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-bg-green-100 gl-bg-green-100 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-text-red-700 gl-text-red-700 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-text-orange-700 gl-text-orange-700 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-text-green-700 gl-text-green-700 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-text-blue-500 gl-text-blue-500 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-text-gray-700 gl-text-gray-700 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-text-gray-800 gl-text-gray-800 (not currently in place) ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
gl-text-gray-900 gl-text-gray-900 ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue,
DIFFERENT NAMES, VALUES IN PLACE
gl- class in Gitlab Gitlab UI equivalent files
gl-font-size-large gl-font-lg app/assets/javascripts/monitoring/components/panel_type.vue, ee/app/assets/javascripts/environments/components/deploy_board_component.vue, ee/app/assets/javascripts/subscriptions/new/components/order_summary/summary_details.vue,
gl-font-size-12 gl-font-sm app/assets/javascripts/vue_merge_request_widget/components/deployment/deployment_info.vue, ee/app/assets/javascripts/geo_nodes/components/geo_node_header.vue,
gl-font-size-small gl-font-sm app/assets/javascripts/vue_merge_request_widget/components/mr_collapsible_extension.vue
gl-font-size-14 gl-font-base ee/app/assets/javascripts/design_management/components/toolbar/index.vue, ee/app/assets/javascripts/design_management/pages/design/index.vue, ee/app/assets/javascripts/environments/components/deploy_board_component.vue, ee/app/assets/javascripts/related_issues/components/related_issues_list.vue
gl-font-size-16 gl-font-lg ee/app/assets/javascripts/packages/details/components/activity.vue, ee/app/assets/javascripts/subscriptions/new/components/order_summary.vue,
SLIGHTLY MORE COMPLICATED
gl- class in Gitlab Gitlab UI equivalent files
gl-font-size-20 gl-font-size-h1 (23) / gl-font-size-h2 (19) app/assets/javascripts/releases/components/release_block_header.vue, app/views/devise/registrations/new.html.haml, ee/app/assets/javascripts/design_management/pages/design/index.vue, ee/app/assets/javascripts/packages/details/components/package_title.vue, ee/app/assets/javascripts/subscriptions/new/components/order_summary.vue,
gl-line-height-14 gl-line-height-16 (is the min line-height) ee/app/assets/javascripts/boards/components/board_settings_sidebar.vue
gl-text-purple -- do not exist -- ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue
gl-bg-purple-light -- do not exist -- ee/app/assets/javascripts/security_dashboard/components/vulnerability_severity.vue

SPACING SCALE DIFFERENCES

gl- class in Gitlab Gitlab UI equivalent files
gl-pl-1 gl-pl-2 app/assets/javascripts/releases/components/evidence_block.vue, app/assets/javascripts/pipelines/components/graph/job_group_dropdown.vue, app/assets/javascripts/pipelines/components/graph/job_name_component.vue, app/assets/javascripts/vue_shared/components/date_time_picker/date_time_picker.vue, app/views/ci/status/_dropdown_graph_badge.html.haml,
gl-p-2 gl-p-3 ee/app/views/subscriptions/groups/edit.html.haml, app/assets/javascripts/vue_shared/components/date_time_picker/date_time_picker.vue
gl-pl-2 gl-pl-3 app/views/projects/blob/_template_selectors.html.haml
gl-p-3 gl-p-5 app/assets/javascripts/monitoring/components/dashboard.vue, app/views/projects/graphs/show.html.haml, ee/app/assets/javascripts/related_issues/components/related_issues_block.vue, ee/app/views/registrations/welcome.html.haml, ee/app/views/subscriptions/groups/edit.html.haml,
gl-pl-3 gl-pl-5 app/views/shared/issuable/form/_branch_chooser.html.haml
gl-pr-3 gl-pr-5 app/views/shared/issuable/form/_branch_chooser.html.haml
gl-py-4 gl-py-6 ee/app/views/trial_registrations/_signin_form.html.haml
gl-pt-5 gl-pt-7 ee/app/views/subscriptions/groups/edit.html.haml,
gl-w-8 gl-w-3 app/assets/javascripts/clusters_list/components/clusters.vue
gl-w-16 gl-w-5 app/assets/javascripts/registry/explorer/pages/details.vue
gl-h-8 gl-h-3 app/assets/javascripts/clusters_list/components/clusters.vue
gl-h-32 gl-h-7 app/assets/javascripts/logs/components/environment_logs.vue,
gl-w-64 gl-w-11 app/views/clusters/clusters/cloud_providers/_cloud_provider_button.html.haml, ee/app/assets/javascripts/vulnerabilities/components/vulnerability_list.vue
gl-h-64 gl-h-11 app/views/clusters/clusters/cloud_providers/_cloud_provider_button.html.haml

TODO list

  • Rerun the grep to be sure the list is up-to-date >> raw output
  • Identify clashing classes
  • Replace the listed classes with class-name -deprecated and
  • Include documentation about where to look to add a class to utilities.css
  • Add a danger warning for adding classes to framework/common.scss

Phase 2: Include gitlab-ui utility-class library, document usage and implementation

TODO list

  • Include gitlab-ui utilities.scss file.
  • Remove same-named doubles from the list in section 1 ▶ !31863 (merged)
  • Document how to implement utility classes in the front-end development guidelines. ▶ !31963 (merged)
  • Document where to implement utility classes in the front-end development guidelines.
  • Expand danger warning for adding classes to utilities.scss
  • Replace -shim- classes

Phase 3: A single spacing scale for padding utilities

gitlab-ui and gitlab declare their own spacing-scale variables: $spacing-scale and $gl-spacing-scale. To consolidate utility classes in this category, I propose to delete $spacing-scale and use gitlab-ui’s variable to declare utilities in both repositories.

// gitlab spacing scale

$grid-size: 8px;
$spacing-scale-0: 0;
$spacing-scale-1: 4px;
$spacing-scale-2: 8px;
$spacing-scale-3: 16px;
$spacing-scale-4: 24px;
$spacing-scale-5: 32px;
// gitlab-ui spacing scale
$grid-size: 8px;
$gl-spacing-scale-0: 0;
$gl-spacing-scale-1: 2px;
$gl-spacing-scale-2: 4px;
$gl-spacing-scale-3: 8px;
$gl-spacing-scale-4: 12px;
$gl-spacing-scale-5: 16px;
$gl-spacing-scale-6: 24px;
$gl-spacing-scale-7: 32px;
$gl-spacing-scale-8: 40px;
$gl-spacing-scale-9: 48px;
$gl-spacing-scale-10: 56px;
$gl-spacing-scale-11: 64px;
$gl-spacing-scale-12: 80px;
$gl-spacing-scale-13: 96px;

TODO list

  • Decide what to do with the complicated classes (replace, backport, rename)
  • Remove usage of Gitlab UI mixins directly
  • Replace gl-py-4 with gl-py-6 gitlab-ui equivalent in gitlab:
    • ee/app/views/trial_registrations/_signin_form.html.haml.
  • Replace gl-p-3 with gl-p-5 gitlab-ui equivalent in gitlab:
    • [-] app/assets/javascripts/monitoring/components/dashboard.vue (no longer applies)
    • app/views/projects/graphs/show.html.haml
  • Replace gl-pl-3 with gl-pl-5 gitlab-ui equivalent:
    • gitlab/app/views/shared/issuable/form/_branch_chooser.html.haml
  • Replace gl-pr-3 with gl-pr-5 gitlab-ui equivalent:
    • app/views/shared/issuable/form/_branch_chooser.html.haml
  • Replace gl-pl-2 with gl-pl-3 gitlab-ui equivalent:
    • app/views/projects/blob/_template_selectors.html.haml
  • Replace gl-pl-1 with gl-pl-2 gitlab-ui equivalent:
    • app/assets/javascripts/pipelines/components/graph/job_group_dropdown.vue
    • app/views/ci/status/_dropdown_graph_badge.html.haml
    • ee/app/assets/javascripts/vue_merge_request_widget/components/visual_review_app_link.vue
  • Remove $spacing-scale variable and use gitlab-ui $gl-spacing-scale to declare spacing utilities in gitlab going forward.
  • Remove currently defined gl-p utilities in common.scss. Update documentation to encourage developers to declare utilities using the same conventions as in gitlab-ui.

Phase 4: A single spacing scale for margin utilities

Phase 5: Replace conformant append / prepend classes

  • [-] Replace old append-* and prepend-* classes ▶ Being worked on it its own issue #217418
Edited by Sarah Groff Hennigh-Palermo