feat: Introduce and use brand and common typography tokens #1760

VincentSmedinga · 2024-11-21T23:51:18Z

Describe the pull request

Thank you for contributing to the project!
Please use this template to help us handle your PR smoothly.

What

Separates the ‘Text Level’ concept into headings and body text
Moves the concept from the ‘brand’ level to ‘common’
Prefixes both with ams.brand and ams.common
Renames text to typography
Introduces a new brand scale of line heights
Removes the now obsolete ams.text tokens
Configures Style Dictionary to log invalid tokens by name
No changes in values other than the line heights

Why

Headings and body text of levels 4, 5, and 6 share font sizes, but they don’t share line heights. For example, <Heading level={4}> needs a small line height, while <Paragraph size="large"> needs a large one. Rather than only splitting some levels into two (e.g. text-level-4-(heading|body-text)-line-height), we’ve separated the two concepts entirely.
This also helped us to define our brand tokens more purely as real primitives.
To visually separate the three levels, make it very obvious that common tokens use brand tokens and component tokens use common tokens, prevent naming problems, and keep names simple.
To match NL Design System.
To improve readability, the line heights have been made slightly smaller for headings and larger for body text. The scale is logarithmic, like font size, with a factor of 31/32 (0.96875). Not all large values are available.
We no longer use them and don’t deprecate things yet on major version zero.
To help find errors while refactoring.
To keep this PR focused

How

Created new typography tokens for the ‘brand’ level
Created new typography tokens for the ‘common’ level
Applied them to all components using font-size, line-height, font-family and font-weight
Fine-tuned the hierarchy and naming of the tokens

Checklist

Before submitting your pull request, please ensure you have done the following. Check each checkmark if you have done so or if it wasn't necessary:

Add or update unit tests
Add or update documentation
Add or update stories
Add or update exports in index.* files
Start the PR title with a Conventional Commit prefix, as explained here.

VincentSmedinga · 2024-11-22T19:45:19Z

proprietary/tokens/src/brand/ams/typography.tokens.json

This is much more focused now: just our selection of font families, sizes and weights, and line heights, with proper names for their options.

VincentSmedinga · 2024-11-22T19:48:04Z

proprietary/tokens/src/brand/ams/typography.tokens.json

+    "brand": {
+      "typography": {
+        "font-family": {
+          "body-text": { "value": "'Amsterdam Sans', Arial, sans-serif" },


Including -text is clearer than just body. I dismissed body-copy for not being very common. Utrecht uses ‘document’, but headings are also in the document.

A typesetter […] sees 'body text' as being those sections of the main text that are flowed into columns or justified as paragraphs, as distinct from the headings and any pictures that are floated out of the main body.
– Wikipedia

VincentSmedinga · 2024-11-22T19:48:31Z

proprietary/tokens/src/brand/ams/typography.tokens.json

+      "typography": {
+        "font-family": {
+          "body-text": { "value": "'Amsterdam Sans', Arial, sans-serif" },
+          "headings": { "value": "'Amsterdam Sans', Arial, sans-serif" },


Headings include labels and fieldset legends as well. And accordion buttons use these tokens.

VincentSmedinga · 2024-11-22T19:48:44Z

proprietary/tokens/src/brand/ams/typography.tokens.json

+        "font-family": {
+          "body-text": { "value": "'Amsterdam Sans', Arial, sans-serif" },
+          "headings": { "value": "'Amsterdam Sans', Arial, sans-serif" },
+          "monospace": { "value": "monospace" }


Might be too soon to add this.

If we add a <code> component it might come in handy.

VincentSmedinga · 2024-11-22T19:52:10Z

proprietary/tokens/src/brand/ams/typography.tokens.json

+          "bold": { "value": 700 },
+          "x-bold": { "value": 800 }
+        },
+        "line-height": {


I’ve calculated this scale precisely like we did for font sizes. I started with 1.66667 for paragraphs and found a factor of 31/32 to generated line heights very close to what we aimed for.

The 7 smallest are all used for consecutive heading levels. The 4 largest, creating 1 overlapping, for body text levels. Not all options (e.g. 4xl) have been made available.

VincentSmedinga · 2024-11-22T19:52:37Z

proprietary/tokens/src/common/ams/typography.tokens.json

+            "font-size": { "value": "{ams.brand.typography.font-size.lg}" },
+            "line-height": { "value": "{ams.brand.typography.line-height.2xl}" }
+          },
+          "xl": {


This is a new level for blockquotes because they are not headings.

VincentSmedinga · 2024-11-22T19:53:15Z

proprietary/tokens/src/common/ams/typography.tokens.json

+      "typography": {
+        "body-text": {
+          "font-family": { "value": "{ams.brand.typography.font-family.body-text}" },
+          "font-size": { "value": "{ams.brand.typography.font-size.md}" },


This and line height apply to md – I chose not to make that level explicit, but to make these values the baseline, overridden by the variants, just like we do in CSS.

VincentSmedinga · 2024-11-22T19:54:11Z

proprietary/tokens/src/common/ams/typography.tokens.json

+          "font-weight": { "value": "{ams.brand.typography.font-weight.bold}" }
+        },
+        "headings": {
+          "font-family": { "value": "{ams.brand.typography.font-family.headings}" },


Having two separate tokens for the font-family of headings and body text, while we use the same font for both, allows the community to use two different typefaces.

VincentSmedinga · 2024-11-22T20:13:29Z

proprietary/tokens/src/common/ams/typography.tokens.json

+            "line-height": { "value": "{ams.brand.typography.line-height.md}" }
+          }
+        },
+        "bold": {


Not entirely sure about this one. Is a phrase or paragraph of bold text a variation? Badge uses it, for example. And blockquote. Does it make sense to let our future .ams-strong use this token?

We could also name it ‘emphasis’ and combine it with italics – normal and strong emphasis.

dlnr · 2024-11-25T11:37:48Z

proprietary/tokens/src/brand/ams/typography.compact.tokens.json

@@ -0,0 +1,17 @@
+{
+  "ams": {


To maintain the history of the file you can use git mv, just renaming it deletes it and adds a new file.

dlnr · 2024-11-25T11:39:08Z

proprietary/tokens/src/brand/ams/typography.tokens.json

+        "font-family": {
+          "body-text": { "value": "'Amsterdam Sans', Arial, sans-serif" },
+          "headings": { "value": "'Amsterdam Sans', Arial, sans-serif" },
+          "monospace": { "value": "monospace" }


If we add a <code> component it might come in handy.

dlnr · 2024-11-25T11:41:47Z

proprietary/tokens/src/brand/ams/typography.compact.tokens.json

+    "brand": {
+      "typography": {
+        "font-size": {
+          "sm": { "value": "clamp(0.8889rem, calc(0.9141rem + -0.0253vw), 0.9091rem)" },


This grows smaller on desktop.

dlnr · 2024-11-25T11:45:06Z

proprietary/tokens/src/brand/ams/typography.tokens.json

+          "light": { "value": 300 },
+          "normal": { "value": 400 },
+          "bold": { "value": 700 },
+          "x-bold": { "value": 800 }


"bolder" might be more common.

dlnr · 2024-11-25T11:49:10Z

proprietary/tokens/src/common/ams/typography.tokens.json

+    "common": {
+      "typography": {
+        "body-text": {
+          "font-family": { "value": "{ams.brand.typography.font-family.body-text}" },


We might need to look at the bundler for the tokens here, because everything is bundled. So you're creating:

--ams-brand-typography-font-family and --ams-common-typography-body-text-font-family

Do we need both and how is it more semantic?

dlnr · 2024-11-25T11:50:31Z

storybook/src/styles/overrides.css

@@ -40,7 +40,7 @@
 .sbdocs-content.sbdocs-content > .ams-storybook-status-badge > span:nth-child(2) {
  color: #000;
  font-family: "Amsterdam Sans", "Arial", sans-serif;


Not the custom property?

dlnr · 2024-11-25T11:52:06Z

proprietary/tokens/src/common/ams/typography.tokens.json

@@ -0,0 +1,61 @@
+{
+  "ams": {
+    "common": {


Do we really need this prefix? We don't previx component properties ams-components-?

VincentSmedinga added 8 commits November 22, 2024 12:46

Introduce actually primitive brand typography tokens

7c365d6

Model heading and body scales in common tokens

e0c3640

Apply new typography tokens to all components

ff36227

Merge branch 'develop' into feature/DES-1073-refactor-text-level-scale

946f81a

Remove unnecessary extra logging config

9cb6774

Rename token in stylesheet

a3082d6

Add new compact tokens

4664607

Remove obsolete text tokens

855d488

VincentSmedinga force-pushed the feature/DES-1073-refactor-text-level-scale branch from 73a0f78 to 855d488 Compare November 22, 2024 19:20

github-actions bot deployed to demo-DES-1073-refactor-text-level-scale November 22, 2024 19:21 View deployment

VincentSmedinga commented Nov 22, 2024

View reviewed changes

VincentSmedinga requested review from dlnr, RubenSibon and alimpens November 22, 2024 19:55

VincentSmedinga commented Nov 22, 2024

View reviewed changes

VincentSmedinga marked this pull request as ready for review November 23, 2024 09:02

dlnr reviewed Nov 25, 2024

View reviewed changes

VincentSmedinga marked this pull request as draft December 13, 2024 10:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Introduce and use brand and common typography tokens #1760

feat: Introduce and use brand and common typography tokens #1760

VincentSmedinga commented Nov 21, 2024 •

edited

Loading

VincentSmedinga Nov 22, 2024

VincentSmedinga Nov 22, 2024

VincentSmedinga Nov 22, 2024

VincentSmedinga Nov 22, 2024

dlnr Nov 25, 2024

VincentSmedinga Nov 22, 2024

VincentSmedinga Nov 22, 2024

VincentSmedinga Nov 22, 2024

VincentSmedinga Nov 22, 2024

VincentSmedinga Nov 22, 2024 •

edited

Loading

dlnr Nov 25, 2024 •

edited

Loading

dlnr Nov 25, 2024

dlnr Nov 25, 2024

dlnr Nov 25, 2024

dlnr Nov 25, 2024

dlnr Nov 25, 2024

dlnr Nov 25, 2024

feat: Introduce and use brand and common typography tokens #1760

Are you sure you want to change the base?

feat: Introduce and use brand and common typography tokens #1760

Conversation

VincentSmedinga commented Nov 21, 2024 • edited Loading

Describe the pull request

What

Why

How

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VincentSmedinga Nov 22, 2024 • edited Loading

Choose a reason for hiding this comment

dlnr Nov 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VincentSmedinga commented Nov 21, 2024 •

edited

Loading

VincentSmedinga Nov 22, 2024 •

edited

Loading

dlnr Nov 25, 2024 •

edited

Loading