Skip to content

feat(Typography): Add heading scale classes

Dan MH requested to merge generate-heading-scale-classes-danmh into main

What does this MR do?

We are trying to increase results, quality, and efficiency by using typography in a systematic way.

This MR builds on !3673 (merged), creating classes that can be applied to headings, enabling us to apply heading styles consistently in future work.

The heading utilities should only be applied to the corresponding heading element. For example:

  • ✅ Do: <h2 class='gl-heading-2'>
  • ❌ Don't: <h1 class='gl-heading-4'>

In the future we should create tools to make this easier to apply, and warnings when not compliant. These classes are needed for migration reasons, and aren't intended to be permanently required.

The 'fixed' and 'contextual adjustments' variants have very rare use. Most instances these will be in components where visual hierarchy is communicated through additional mechanisms.

What does this MR do (as written by @sdejonge)

Summarizing my understanding from a sync-up on these heading mixins/utility classes:

There are 2 sets of heading mixins and utility classes being generated:

  1. gl-heading-{1-6} semantic stack: the desired classes used for iterative typography updates e.g. <h2 class="gl-heading-2">...</h2> as demonstrated in the POC integration branch !3586.
  2. gl-heading-scale-{100-800} font-size stack: a set of utility classes and mixins for updating specific cases where the semantic heading scale does not visually align (contextual adjustments), these classes and mixins are required to enable migration work on components such as alert/card where a heading has a semantic level, but a much smaller visual style.

Usage

gl-heading-{1-6} classes are promoted as the preferred approach to heading typography updates. Their usage should align with semantic heading level e.g. <h2 class="gl-heading-2">...</h2>. While it is possible to use a different class to heading element e.g. <h2 class="gl-heading-3">...</h2>, the migration work will adjust headings to provide meaningful heading levels.

gl-heading-scale-{100-800} classes are used in exceptions where semantic classes aren't appropriate and are not promoted/documented as synonyms of gl-heading-{1-6}. their usage could be linted to provide warnings to users highlighting their use-case.

Suggestion outcome

The suggestion to make gl-heading-{100-800} be more generic e.g. gl-typography-{100-800} (!3685 (comment 1576585192)) isn't necessarily applicable here as the gl-heading() mixin provides other properties such as font-weight, letter-spacing, and line-height which are specific considerations of the heading visual hierarchy with explorations in gitlab-org/gitlab-services/design.gitlab.com#1550 (closed). Other typographic elements that would use the font-size stack would have different font-weight, letter-spacing, and line-height and would not make use of any of these shared properties, only the get-font-size-variable function.

Margin opt-in vs. opt-out

The gl-heading-{1-6} classes provide a default margin-bottom (and reset Bootstrap's margin-top). In order to opt-out of the margin users add a gl-mb-0! class:

<h2 class="gl-heading-2">...</h2> <!-- has margin -->
<h2 class="gl-heading-2 gl-mb-0!">...</h2> <!-- to remove margin -->

The proposal is that a greater amount of headings will have a margin by default, and this provides consistent spacing for all headings. Removing the margin is an exception which requires added friction.

For more context see:

Screenshots or screen recordings

No visual change

Integration merge requests

Does this MR meet the acceptance criteria?

This checklist encourages the authors, reviewers, and maintainers of merge requests (MRs) to confirm changes were analyzed for conformity with the project's guidelines, security and accessibility.

Toggle the acceptance checklist

Conformity

  • Code review guidelines.
  • GitLab UI's contributing guidelines.
  • If it changes a Pajamas-compliant component's look & feel, the MR has been reviewed by a UX designer.
  • If it changes GitLab UI's documentation guidelines, the MR has been reviewed by a Technical Writer.
  • If the MR changes a component's API, integration MR(s) have been opened (see integration merge requests above).
  • Added the ~"component:*" label(s) if applicable.

Security

If this MR contains changes to processing or storing of credentials or tokens, authorization and authentication methods and other items described in the security review guidelines:

  • Label as security and @ mention @gitlab-com/gl-security/appsec
  • Security reports checked/validated by a reviewer from the AppSec team

Accessibility

If this MR adds or modifies a component, take a few moments to review the following:

  • All actions and functionality can be done with a keyboard.
  • Links, buttons, and controls have a visible focus state.
  • All content is presented in text or with a text equivalent. For example, alt text for SVG, or aria-label for icons that have meaning or perform actions.
  • Changes in a component’s state are announced by a screen reader. For example, changing aria-expanded="false" to aria-expanded="true" when an accordion is expanded.
  • Color combinations have sufficient contrast.
Edited by Scott de Jonge

Merge request reports