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
gl
class names in Gitlab clash with the Gitlab UI values and rename them.
Phase 1: Identify cases where existing 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) -
gl-font-size-20
➡ !39972 (merged) -
gl-line-height-14
-
the purple colors -
Add the $purple-
variables from gitlab-ui to gitlab https://gitlab.com/gitlab-org/gitlab-ui/-/blob/master/src/scss/variables.scss#L85. -
Deprecate $purple
and$purple-light
in gitlab. -
Replace instances of $purple
,$purple-light
,$gl-text-purple
, and$gl-text-purple-light
with the closest purple variable from the new ones
-
-
-
Remove usage of Gitlab UI mixins directly -
Replace gl-py-4
withgl-py-6
gitlab-ui equivalent in gitlab:-
ee/app/views/trial_registrations/_signin_form.html.haml
.
-
-
Replace gl-p-3
withgl-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
withgl-pl-5
gitlab-ui equivalent:-
gitlab/app/views/shared/issuable/form/_branch_chooser.html.haml
-
-
Replace gl-pr-3
withgl-pr-5
gitlab-ui equivalent:-
app/views/shared/issuable/form/_branch_chooser.html.haml
-
-
Replace gl-pl-2
withgl-pl-3
gitlab-ui equivalent:-
app/views/projects/blob/_template_selectors.html.haml
-
-
Replace gl-pl-1
withgl-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 incommon.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-*
andprepend-*
classes▶ Being worked on it its own issue #217418
Edited by Sarah Groff Hennigh-Palermo