Consolidate line-height() and font-size() function values in tokens

[alex-page]

This issue is blocked by #4588 but in the meantime we can land on the approach we want to take.

[aveline]

Line height

token	base	large screen
--line-height-small --line-height-button	16px
--line-height-body	20px
--line-height-large --line-height-input --line-height-display-small	24px
--line-height-display-medium --line-height-display-large	28px	32px
--line-height-display-xlarge	36px	44px

Perhaps --line-height-button isn't necessary. Thoughts?

Otherwise the line heights map to the font sizes below, which should hopefully make it easy to reason about which to use together.

[aveline]

Font size

token	base	large screen
--fs-body	15px	14px
--fs-input	16px	14px
--fs-small	13px	12px
--fs-large	17px	16px
--fs-display-small	16px	20px
--fs-display-medium	21px	26px
--fs-display-large	24px	28px
--fs-display-xlarge	27px	42px

[alex-page]

@aveline this is great, thanks for the first pass.

I am not convinced that we should retain the base and large screen definitions. I am worried that increases confusion between developer + designer handoff as that is extra context that has to be shared. We also don't have a great way to put responsive font-sizes into tools like Figma. I think we could simplify this with a numerical scale:

fs-1: 12px
fs-2: 14px
fs-3: 16px
fs-4: 20px

I also wonder if the 13px and 17px values are useful? Can our users notice the difference? Do they align to a 4x4 grid? We might be able to simplify the scale by removing values.

[aveline]

@alex-page my concern with removing the base/mobile scale is how large of a change it is. But if we are ok with the scope of the changes, then let's try removing them.

The one I do feel strongly about keeping responsive is the input one. We definitely want the input size to be 16px on mobile, any smaller will trigger input zoom on Safari mobile browsers. And perhaps that's why the body was bumped up to 15px, because otherwise the inputs at 16px look a bit large with body at 14px? I can play around with this to compare.

I'm inclined to have a bit more descriptive token names than a numerical scale. Looking at fs-2: 14px and fs-3: 16px it doesn't seem immediately obvious which one is the standard body font size.

[alex-page]

Oof. That is a clear concern. Let me try and jot down what I was thinking.

I see two potential approaches:

1. Remove all semantic connections in tokens. The tokens become a scale of font-size and line-height values we recommend for typography. We help users implement great typography through components and documentation. Display, TextField Label etc. would reference values from this scale. Users creating new or custom components could use existing components or create their own acessing values from the scale. In our documentation we could add important information like 16px is required for iOS devices to stop inputs zooming when focused.
   
   This approach would keep the tokens simple with one object for font-size and line-height. We could iterated and adjust the tokens with little risk as there is no semantic layer.

fontsize: {
  "xxs": "12px",
  "xs": "14px",
  "sm": "16px",
  ...
  "xxl": "48px",
}

.TextInput {
  font-size: var(--p-fontsize-sm);
  font-size: var(--p-lineheight-sm);
  
  @include media(min-width: $mobile) {
    font-size: var(--p-fontsize-xs);
    font-size: var(--p-lineheight-xs);
  }
}

2. Keep semantic connections in tokens. We have values for specific implementations in our tokens. Users can easily access these tokens understanding when to use them. There might be overlapping values but that is okay because we have clear guidance for use. Tokens can be overriden at different breakpoints. Building custom components you have less options for font-size and line-height as it's dependent on implementation.

fontsize: {
  "caption": "12px",
  "body": "14px",
  "input": "16px",
  ...
  "heading-sm": "16px",
  ...
  "heading-lg": "48px",
}

.TextInput {
  font-size: var(--p-fontsize-input);
  font-size: var(--p-lineheight-input);
  
  @include media(min-width: $mobile) {
    --p-fontsize-input: 14px;
    --p-lineheight-input: 20px;
  }
}

My gut feeling is to ship 1 (for this project) and build/update our components to create semantic relationships (future work).

[aveline]

I like the approach of focusing on the scale first, with the intent to layer in semantic tokens down the line. With that in mind, here is what that could look like. The body font size should be the mid value of the scale so it's obvious that is the body font size instead of having to guess or remember that body font size is xs or sm. That does leave us with many larger sizes though, and the xxl pattern doesn't seem very elegant.

Font scale tokens

token	base	large screen
--fs-sm	13px	12px
--fs	15px	14px
--fs-lg	17px	16px
--fs-xl	16px	20px
--fs-xxl	21px	26px
--fs-xxxl	24px	28px
--fs-xxxxl	27px	42px

Line height tokens

token	base	large screen
--line-height-small	16px
--line-height	20px
--line-height-lg --line-height-xl	24px
--line-height-xxl --line-height-xxxl	28px	32px
--line-height-xxxxl	36px	44px

And I would make the case for including one semantic token for input. It's a bit of an edge case since it's important to maintain the current experience on mobile and prevent input zoom.

Semantic font size tokens

token	base	large screen
--fs-input	16px	14px

[aaronccasanova]

Dropping some comments that came out of @aveline and my pairing session:

Since our font-size and line-height tokens are not organized in token groups but rather token scales it might be more idiomatic to refer to each value by their index.

• Example of token groups: --typography-heading1-font-size, --typography-heading2-font-size, etc...
• Example of token scales: fontSize = [1, 2, 3]
  Note: Token scales can still have aliases. See the Scale Aliases section of the System UI spec.

One issue with establishing aliases for each token scale is the resulting custom property name can be excessively large and difficult to parse (visually) :

const fontSize = [1, 2, 3, 4, 5, 6]
--p-font-size-base: fontSize[0]
--p-font-size-lg: fontSize[1]
--p-font-size-xl: fontSize[2]
--p-font-size-xxl: fontSize[3]
--p-font-size-xxxl: fontSize[4]
--p-font-size-xxxxl: fontSize[5]

Alternatively, with array index values.

const fontSize = [1, 2, 3, 4, 5, 6]
--p-font-size-0: fontSize[0]
--p-font-size-1: fontSize[1]
--p-font-size-2: fontSize[2]
--p-font-size-3: fontSize[3]
--p-font-size-4: fontSize[4]
--p-font-size-5: fontSize[5]

// Keep in mind we can still establish aliases
--p-font-size-base: fontSize[1]
--p-font-size-display: fontSize[4]

I believe this pattern translates to all token scales when being transformed to CSS custom properties. Here is an example of how GitHub primary references token scales as an additional reference: https://primer.style/primitives/colors#scale-variables

[sarahill]

I kind of like the approach we came up with during the previous foundation work. Mapping more to h1 - h7 and body and caption sizes. Mapping it more to semantic naming feels a little more intuitive and scalable.

@aaronccasanova is this similar to what you're proposing above?

[alex-page]

I like that example @sarahill as it flattens the values out. I find the base and large-screen layer unecessary right now.

[aveline]

I find the base and large-screen layer unecessary right now.

@alex-page would this mean getting rid of the responsive font sizes?

[aveline]

Here is where I see us being at.

✅ Have a font scale that can be referenced by index

🟠 Create semantic aliases that map to the font scale to make it more intuitive

• Should we include this as part of of the first version, or add the aliasases in the future? The alisases may add a bit of overhead to future changes and adjustments we may want to make.

❓ Font scale values are responsive

• Handle the responsive values where custom properties are defined so there's a single source of truth

[alex-page]

@alex-page would this mean getting rid of the responsive font sizes?

No. It would mean that the responsive sizes are only paired together in components. Not at the token layer. When building new components I can choose to add responsive sizes or keep it as one size.

Adding a semantic layer for screen sizes at the token layer encourages them to be used in a specific way when building new or custom components. This could increase forks or hard coded values. I think the components should add the semantic layer and responsive styles, not the tokens.

[aaronccasanova]

@aaronccasanova is this similar to what you're proposing above?

No, but what you've proposed is actually my preferred approach. I think how you created scoped alias tokens that correspond to a composite token groups enables the most flexibility in regards to theming. Since we don't currently have that flexibility in place and our main focus is to get 100% token coverage in polaris-react I didn't push my bias on this topic.

If we are proceeding with token scales (e.g. a list of values with no alias associated) for font-size and line-height, I'm in favor of using the index value for each custom property (e.g. --font-size-0, --font-size-1, etc).

• Note: Although not my preferred approach, typography token scales are perfectly sufficient for the admin where the values are unchanged between different color schemes. This does not hold true and will eventually breakdown if the tokens are consumed in other applications where type styles change between themes.

Otherwise, if we decide on alias/composite token groups, I'm in favor of restructuring the tokens to match your screenshot. This is the most future facing approach IMO but may be off target from our initiative.