Proposal: add design tokens for font weights

[eljefe223]

Describe the feature that you would like added

We should add design tokens for font weights for fluent web components. This would add the following design tokens as part of the fluent-design-system. We still need to determine the defaulted values.

 fontWeightExtraLight
 fontWeightLight
 fontWeightNormal
 fontWeightSemiBold
 fontWeightBold

export const fontWeightExtraLight = create<string>('font-weight-extra-light').withDefault('200');
export const fontWeightLight = create<string>('font-weight-semi-light').withDefault('300');
export const fontWeightNormal = create<string>('font-weight-normal').withDefault('400');
export const fontWeightSemiBold = create<string>('font-weight-semi-bold').withDefault('500');
export const fontWeightBold = create<string>('font-weight-bold').withDefault('700');

What component or utility would this be added to

packages/web-components/src/design-tokens.ts

Some questions to ask

Do we like the concept of named variables extra-light ???, light, semi-light, normal, semi-bold, bold?
Setting a flat token (a string value) seems like the best approach since these values can be any number between 1 - 1000

Accessibility concerns

People experiencing low vision conditions may have difficulty reading text set with a font-weight value of 100 or 200, especially if the font has a low contrast color ratio. Something that can be considered when setting default values.

[chrisdholt]

@bheston for his thoughts on names of the tokens as well.

[bheston]

I was about to add something like this based on the plugin work I've been doing. The shape should be different though.

Based on what we have right now in terms of specifying the ramp, and the fact that the base components use nearly only one value from the ramp, in order to change the weight for a given component what we need is a way to adjust the fontWeight token applied to a region or component type.

This blends into the need for scoping design tokens. For instance, there are designs where buttons are pill-shaped but other inputs are default. The only way to achieve this without individually overriding each button (or overriding the direct css attribute of the button selector) is to do something like fontWeight.setValueFor('button', '500').

That's the preferable solution I see, which requires some needed updates to the token infrastructure. The temporary solution that would allow us to use the css property aspect of design tokens is to create a single design token fontWeight that can be any string. Then it's possible to target all buttons like:

fast-button {
    --font-weight: 500;
}

[bheston]

Per our chat, I didn't have the context that this was intended for potentially adjusting the font weight on a variable font. For instance, changing all uses of "semibold" from 500 to 550.

In that case we could start with these tokens to represent the adjustable values. Essentially it's an enum with variable values. We would still need the fontWeight token to actually apply the value into the component styles. That becomes an alias to one of the specific named font weights.

Naming

Regarding the names, if we go with this model I would implement the full set of common names and default weights from https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight#common_weight_name_mapping. Modern tools seem to favor "Regular" over "Normal", and I lean that way as well, despite normal being the accepted css value. Not a big deal either way.

Values

The one concern I have is with someone abusing the system with a value that changes the meaning. For instance, the correct model would not be to adjust semibold to 200 just because you wanted to change everything that was semibold before. This is true with other systems though as well.

Accessibility

Regarding the accessibility issues you mention, that's a great reason to implement it this way. We could then easily give a customer the option of having no text lighter than x and we could scale the entire weight ramp the same way we can with the size. So in that regard I'm a fan of this.

Further context

I don't think we need to model it this way however. We do have support for aliases in the design token system, and while I suspect the performance considerations are minimal, using a simple value is less processing.

The alternative is to simply use a constant when setting up the design token values when loading the app. Something like

const semiboldWeight = 550;
fontWeight.setValueFor('button', semiboldWeight);
fontWeight.setValueFor('text-field', semiboldWeight);

The benefit of aliasing the design tokens only comes if we expect to support adjusting what "semibold" means at runtime.

The equivalent in our model today is baseLayerLuminance and to some degree bodyText. We set the luminance to a LightMode or DarkMode constant, but those could each also be tokens if we wanted to offer the choice between light mode and dark mode, and also how light or dark each mode is at runtime. Of course that's a bit contrived since the easy solution there is to simply offer a slider from 0 to 1. I once thought I had a need for this actually, but @nicholasrice talked me out of it. :)

[chrisdholt]

Adding the current values for Fluent UI react so we can take that into consideration here as well:

  // Font weight tokens
  fontWeightRegular
  fontWeightMedium
  fontWeightSemibold

[eljefe223]

@bheston Have we thought about what values would be part of this enum, would there be an enum for each weight or a broad enum for all weights starting from 200 to 1000 with increments of 50?

[chrisdholt]

@bheston Have we thought about what values would be part of this enum, would there be an enum for each weight or a broad enum for all weights starting from 200 to 1000 with increments of 50?

Personally, I would just type it as a number as that will scale better. Additionally, certain fonts may support different variations here - not sure we should take that much opinion here.

[eljefe223]

@bheston Have we thought about what values would be part of this enum, would there be an enum for each weight or a broad enum for all weights starting from 200 to 1000 with increments of 50?

Personally, I would just type it as a number as that will scale better. Additionally, certain fonts may support different variations here - not sure we should take that much opinion here.

I think I agree, was just trying to understand Brian's proposal

[bheston]

Yes, typed as a number, with an enum representing the current non-variable standards. I don't see a realistic way or benefit in having 50-level values, so only the defined 100-level.

I'm revisiting my second comment, and I still believe the original proposal is not the right shape. One of the main reasons is my "Values" section, where I don't want to provide the ability for "semibold" to equal 100.

I started working on some other type ramp related updates and incorporated font-weight into the system due to some technical limitation around variable fonts. I'm working on writing an issue to support that, which I will link to this, but the summary of it is that we'll need to have a set of tokens representing "family", "size", "line height", "weight", and "optical size". I think this is pointing to some sort of convenience wrapper that allows us to combine something like "type ramp base" and "standard semibold" or "custom 550 semibold". Those convenience combos are what we end up with regarding the "Semantically named use case based styles" section in heading.md in one of my old PRs I need to reopen.

I'll link what I have soon.

[chrisdholt]

Yes, typed as a number, with an enum representing the current non-variable standards. I don't see a realistic way or benefit in having 50-level values, so only the defined 100-level.

Just a note here that I do not believe we should use an enum like this. Enums do not compress and quickly turn into death by 1000 cuts. We should use them only when they are absolutely necessary which in many cases for our work is rare.

[bheston]

Closed per #22079