Systematising typography styles in the admin UI

[jameskoster]

There are several typographic styles used throughout the editor, including:

• Body text at 13px
• Help text at 12px
• Labels at 11px, all-caps

However, these styles are not globally registered, leading to inconsistent and ad hoc usage across the interface. For example, in the data views pagination control, the 'label' styling is applied ad hoc to the 'of 3' suffix here:

This means that if the label style is updated in the future, this suffix will not automatically align with the preceding label leading the UI breakage.

Another problem is unique type styles, such as the section headings in the Editor Preferences modal. This is an inevitable consequence of using such a small / rigid scale and leads to inconsistency and fragility in the overall design. Some of these pain points are already felt in Data Views as mentioned above.

Establishing beautiful and consistent typographic rules will be increasingly important as the admin redesign progress and we begin building UIs outside of the Editor interface (settings forms and so on).

Solution

To ensure design consistency and ease of maintenance, we should establish a set of typographic styles that can be utilized throughout the admin interface.

Goals

• Develop a comprehensive set of typographic styles.
• Define high-level heuristics like how weight is applied.
• Ensure that all typographic elements in the UI adhere to these styles.
• Facilitate easier updates and maintenance of typographic consistency.

Let's discuss which type styles we'll need keeping in mind high-density UI's like the block inspector, but also admin pages like settings screens where there can be more breathing room. As we explore properties, ideally line-height values should be multiples of 4 to align with the 4px baseline.

[jameskoster]

Typography Tokens

Tokenizing typographical properties allows for streamlined, future-proof adjustments while ensuring that any ad-hoc customizations remain consistent with the established system. Here’s a breakdown of the tokens I've been exploring:

Font Sizes

• XS: 11px
• S: 12px
• M: 13px
• L: 15px 🆕
• XL: 20px 🆕
• 2XL: 32px 🆕

These sizes largely align with the current design, with a few new additions to enhance flexibility.

Line Heights

• XS: 16px
• S: 20px
• M: 24px 🆕
• L: 28px 🆕
• XL: 32px 🆕
• 2XL: 40px 🆕

Line-height application is quite inconsistent across the UI. By standardizing line-height values as multiples of 4px, we ensure text elements align seamlessly with the 4px vertical rhythm established in many components. This alignment is crucial for creating a visually cohesive interface, especially when placing text next to elements like buttons and inputs.

Font Weights

• Regular: 400
• Semi-bold: 500

Font weight usage has also been inconsistent, with identical headings sometimes utilising different weights. Simplifying this to just two weights—Regular for body text and Semi-bold for headings—ensures a more uniform and polished appearance.

Font Families

• Headings: -apple-system, "system-ui", "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif
• Body: -apple-system, "system-ui", "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif
• Mono: Menlo, Consolas, monaco, monospace;

These font families are based on the current system, now divided between headings and body text. In the future, platform personalization options might allow users to customize fonts alongside color schemes and other visual elements. By tokenising families we can hopefully make this easier to implement.

Text Styles

By combining these tokens, we can create a set of text styles that can be applied to headings, body text, and other UI elements.

Headings

Headings serve to organize content within the admin interface, enabling users to quickly scan and navigate. While typically applied to heading elements, these styles can also be used for other purposes, such as input labels or tabs. In denser UIs, headings may share the same size as body text, so weight is used to distinguish between them.

Body Text

Body text styles are used for any text not specifically intended for navigation or section separation. This includes paragraphs, input fields, tooltips, and more.

Contextual Mockups

To illustrate these styles in action, I've created a series of mockups. These sketches demonstrate how the existing editor UI can largely retain its current appearance while achieving greater consistency in other areas of the admin as we work on redesigning them.

[jasmussen]

Looks good, and will be excellent documentation for what's de-facto shipping. I don't know that this necessarily needs a ton of design feedback, as despite the sound of this, there's practically very little news here, all of this is shipping. Which is to say, it'll be good to add this documentation to Storybook. Any changes we make to font sizes or type scales in the future, we can simply update the documentation along with it.

[jameskoster]

I've started looking into the implementation for this one. The css/scss side of things seems straight-forward; we can create variables for each token, and mixins for the different text styles, e.g.:

@mixin heading-small() {
	font-family: $font-family-headings;
	font-weight: $font-weight-semi-bold;
	font-size: $font-size-x-small;
	line-height: $line-height-x-small;
}

The js is a bit more complicated due to the existing Text and Heading components, which include logic for calculating font size and other details. This logic is not fully aligned with the scale we're looking to implement so will need to be revised, removed, or new component(s) created. Let's discuss how we expect things to work so we can investigate the path forwards.

To align with the css, my thinking is that Text and Heading would support predefined styles that match (or utilise, if that's possible) the scss mixins. Consumers could do something like:

<Text style="body-medium">Code is Poetry</Text>

Which would output a span that is styled according to the properties of the body-medium mixin.

Heading would work similarly, but needs to entertain different levels (h1, h2, h3, and so on). Levels can refer to certain styles by default – for instance level 1 might use heading-xl – but it should also be possible to apply different styles to different levels, e.g.:

<Heading level="1" style="heading-small">Code is Poetry</Heading>

This example would output a <h1> with the heading-small style properties.

Finally, though niche, it should be possible to not use a preset style at all. Consumers should have the option to create custom styles, using either the supplied tokens, hard-coded values, or a mixture thereof.

cc @WordPress/gutenberg-components for thoughts.

[mirka]

To align with the css, my thinking is that Text and Heading would support predefined styles that match (or utilise, if that's possible) the scss mixins. Consumers could do something like:

Sounds good to me. We can't use the style prop because that clashes with a standard React prop, but variant or preset could do. The preset can be overridable through more specific props like weight and size. We can also anticipate that presets will eventually be fully customizable through theming.

The js is a bit more complicated due to the existing Text and Heading components, which include logic for calculating font size and other details. This logic is not fully aligned with the scale we're looking to implement so will need to be revised, removed, or new component(s) created.

Right, a lot of the current props (not just style-related) are unused and don't align with our current needs, so we need to assess whether we can salvage the current component or we should start a second version from scratch.

[ciampo]

The preset can be overridable through more specific props like weight and size

I was wondering if those are needed — if we allow folks to specify variant={ undefined }, they could just bring their own CSS, without a need for extra props. And the CSS could refer to individual theme tokens, if they wanted to mix & match preset value with fully custom values. What do you think, @mirka ?

Right, a lot of the current props (not just style-related) are unused and don't align with our current needs, so we need to assess whether we can salvage the current component or we should start a second version from scratch.

Had the same thinking. Also, I'd be tempted to remove truncation features — if consumers need truncation, maybe they can compose the elements themselves?

[mirka]

I was wondering if those are needed — if we allow folks to specify variant={ undefined }, they could just bring their own CSS, without a need for extra props. And the CSS could refer to individual theme tokens, if they wanted to mix & match preset value with fully custom values. What do you think, @mirka ?

Yes, I guess that would be simpler, given how rare it should be to stray from the presets.