Typography type feedback

[c1rrus]

Is the typography composite type fit for purpose? Should the lineHeight sub-value use a number value, dimension or a new line-height type?

Please share your feedback, thoughts and ideas in this issue.

[mkeftz]

Thanks @c1rrus for the amazing work on composite types. It's been fantastic from a tool makers perspective to have these properly defined.

There are a couple of things on Typography I'm unsure of: -- I feel it's missing a few frequently used properties. Specifically fontStyle, textDecoration, and textTransform. This makes it hard to translate between different design tools Text styles and design tokens. -- With the fontName property, is there a reason this is not fontFamily? This might be more of a personal preference, but all the other names align with their css equivalent.

[ilikescience]

I think that the typography composite type serves as a good test balloon (or stress test, or canary in the coal mine, maybe) for some of the higher-level ideas about composite types.

For example, #86 defines a typography token as one that must include the following five values:

• fontName
• fontSize
• fontWeight
• letterSpacing
• lineHeight

However, in CSS alone, there are at least 57 properties that can change the way text is displayed.

CSS properties that modify text

• direction
• font
• font-family
• font-feature-settings
• font-kerning
• font-language-override
• font-optical-sizing
• font-palette
• font-size
• font-size-adjust
• font-stretch
• font-style
• font-synthesis
• font-synthesis-small-caps
• font-synthesis-style
• font-synthesis-weight
• font-variant
• font-variant-alternates
• font-variant-caps
• font-variant-east-asian
• font-variant-emoji
• font-variant-ligatures
• font-variant-numeric
• font-variant-position
• font-variation-settings
• font-weight
• glyph-orientation-vertical
• hanging-punctuation
• hyphens
• letter-spacing
• line-break
• overflow-wrap
• tab-size
• text-align
• text-align-all
• text-align-last
• text-combine-upright
• text-decoration
• text-decoration-color
• text-decoration-line
• text-decoration-style
• text-emphasis
• text-emphasis-color
• text-emphasis-position
• text-emphasis-style
• text-indent
• text-justify
• text-orientation
• text-shadow
• text-transform
• text-underline-position
• unicode-bidi
• white-space
• word-break
• word-spacing
• word-wrap
• writing-mode

I know it's a bit obtuse to imply that anyone would use all those properties in any given type definition. But It raises an important point: when we choose a subset of these options, we're going to leave out use cases.

One approach to this problem is to allow composite types to "openly defined," in that they have a minimum requirement for definition, but that an author may choose to include as many additional properties as they see fit.

I'd suggest that if the spec is "open", each composite type is defined as the minimum amount of information necessary to render a given element. In the case of typography, that might just be "fontName" (or "fontFamily") and ("fontSize").

This approach takes a lot of pressure off of the spec, but makes it harder for implementers on the tool side.

Another approach is to use a "closed" definition — each composite type has a maximum set of properties, and authors can choose a subset of those properties.

In that case, the typography composite type would be defined as one that includes any number of a fixed set of properties (like the ones in the collapsible above).

This approach makes it much easier for implementers, since the possibilities for the token are limited. But it does put a lot of pressure on the spec to get the list "right."

---

Typography is definitely the pressure test here; for a token like "shadow," it's possible to just require the full list of properties, since that list is short. But the approach should be consistent between composite types, so typography is a good place to start with some of these challenging questions.

[TravisSpomer]

Really insightful. Typography is interesting because it does feel like some of those properties (like the specific five you called out) are very "core" to the look and feel and function of text, and some of them like white-space and text-align and text-decoration are instead things that you think of again each time you want to use that text style. In web terms, the former group are the sorts of things you'd set as CSS/SCSS variables or on high-level elements like html or body, and the latter are the sorts of things you'd use for much more scoped situations like div.mySpecificUsage.

I think the crucial questions are: do we think we can adequately nail down the right set of those "core" properties in the first group? Do all people have approximately the same mental picture of what text properties are really core and which ones are things that you decide for each specific instance of text? If we can't answer "yes" very confidently to those two questions, I'm a lot more inclined to agree with you here.

[drwpow]

Re the “open spec” idea from @ilikescience, I don’t think including all the properties would be too hard on implementers, because most tools will be somewhat platform-specific. For example, several of the 57 CSS properties named don’t work for all browsers on the web yet. Or if they work on web, they may not for native apps. Since typographic attributes are somewhat platform-specific, there could be a wide list of properties and every tool only selects the subset its build target can use.

[ChristophLabacher]

I, too want to point out that the current selection of properties seems very restrictive.

To make it more explicit these are a few I use regularly in our token system:

• text-underline-offset and text-decoration-thickness
• word-spacing
• text-transform

If they were missing from the spec I would definitely be unable to use the token format for our design tokens. I do think they are important because they finally allow designers more control over the typography in digital designs.

My preferred solution would be to have an open spec (minimum requirements + users can add any property), with a list of spellings and definitions for common properties, that is not exhaustive but serves as a guide to tool-makers.

If the decision is made to make the spec closed and the list exhaustive, there are some properties that I’d consider out of scope because for me they are about the box that contains the type, rather than the type itself if that makes sense? E.g.:

• hanging-punctuation
• hyphens
• text-align

---

On another note, I think the description of the lineHeight property is somewhat ambiguous:

• lineHeight: The vertical spacing between lines of typography. The value of this property must be a valid JSON string or a reference to a string token.

“The vertical spacing between lines of typography” doesn’t seem quite right to me. It sounds like it is describing leading, as in the size of the lead strip put between two lines of text, when it is (probalby?) actually refering to the space from one baseline to the next (as in CSS and common design tools).

[solemone]

Hi Community,

how about open font features. E. g. to activate a stylistic set? I would like to use a token like fontFeatures. Maybe with an array of active features. Like:

fontFeatures: ["ss07", "liga 0" ]

or a little bit more explicit:

fontFeatures: [ { "ss07": "on" }, { "liga": "off" } ]

[emilianorodriguez]

Hi, I wonder if you have considered adding color as part of the composite typography token.

Whilst I know color is not part of the typography properties as fontSize, lineHeight or even textDecoration, it is intrinsically related to the overall style. ie: assigning specific colors to links or connoting danger through the use of red typography is a common practice.

The use of a "typography composite token" relating 2 existing tokens could be extremely beneficial to the overall simplicity. What I mean by this is the following use case.

1. Create tokens specific to font family, size, weight, etc.
2. Create, for example, a Heading 3 token, referencing the previously created font family, size, weight...
3. Create a "Danger heading 3" token, referencing the Heading 3 token + a color token ( ie: color.danger)

This logic could be applied to even a default color across typography, communicate different status, etc...

[DeDiamondPro]

I think that the type for lineHeight and letterSpacing are not fit for purpose, In both of these variables the following values are useful:

• px
• em
• rem

Currently lineHeight only supports em and letterSpacing only supports px and rem.

I would like to suggest the creation of a new type with a name like fontDimension which supports px, em and rem and gets used by lineHeight and letterSpacing

[ch99q]

Why do the Typography values use "fontFamily" instead of "family"?

When comparing, e.g. shadow to typography I see that shadow's values are more context-based, but when writing typography, it's more based on the CSS properties.

"microcopy": {
  "$type": "typography",
  "$value": {
    "fontFamily": "{font.serif}",
    "fontSize": "{font.size.smallest}",
    "fontWeight": "{font.weight.normal}",
    "letterSpacing": "0px",
    "lineHeight": "1"
}

We could make it more context based so it matches the other types in the spec by replacing some of the keys like this?

"microcopy": {
  "$type": "typography",
  "$value": {
    "family": "{font.serif}",
    "size": "{font.size.smallest}",
    "weight": "{font.weight.normal}",
    "spacing": "0px",
    "height": "1"
}

The only problem I encounter is the height property's meaning since we removed the "letter" part.

[lukasoppermann]

One approach to this problem is to allow composite types to "openly defined," in that they have a minimum requirement for definition, but that an author may choose to include as many additional properties as they see fit.

I encounter an issue were we don't define a lineHeight so that it inherits the parents lineHeight in css. However this is not possible with the current definition as lineHeight is required.

I think there should be a minimum requirement like fontFamily and fontSize and leave the rest optional.

CC: @ilikescience

[nesquarx]

Even font family or size could be inherited.

On Thu, 29 Sep, 2022, 1:08 pm Lukas Oppermann, @.***> wrote:

One approach to this problem is to allow composite types to "openly defined," in that they have a minimum requirement for definition, but that an author may choose to include as many additional properties as they see fit.

I encounter an issue were we don't define a lineHeight so that it inherits the parents lineHeight in css. However this is not possible with the current definition as lineHeight is required.

I think there should be a minimum requirement like fontFamily and fontSize and leave the rest optional.

CC: @ilikescience https://github.com/ilikescience

— Reply to this email directly, view it on GitHub https://github.com/design-tokens/community-group/issues/102#issuecomment-1261887142, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEKS36CHO6OJEAO2L4IJ4ULWAVBOPANCNFSM5L454Y7Q . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[lukasoppermann]

Even font family or size could be inherited.

True, from a css centric view those are required for the font property which is the closest one to this token. But yes, this could also be inherited.

[EllyLoel]

Looking at WCAG 2.1 Success Criterion 1.4.12: Text Spacing it describes all of the values relative to the font size:

• Line height (line spacing) to at least 1.5 times the font size;
• Spacing following paragraphs to at least 2 times the font size;
• Letter spacing (tracking) to at least 0.12 times the font size;
• Word spacing to at least 0.16 times the font size.

So being able to use something like em that is relative to the font size for line height and letter spacing would be really great.

[chris-dura]

I couldn't find another issue to tack this on, but I've run into a scenario where I want to use the keyword normal for letterSpacing, but the current draft requires that it be a $type: dimension, which needs a px or rem, afaict.

But, 0px is not the same as normal for letterSpacing. What do authors (or tools makers) do in this case?

(and now that I think about it, at least in CSS, there's A LOT of properties that can be either a keyword (string), or some other specific type (dimension, duration, color ...) perhaps there is already discussion on how we're supposed to handle a "union" type like that?)

[CITguy]

Are all properties of a composite typography token required?

I'd like to define partial token definitions so that I can compose more complex styles after translation?

  { fontFamily, fontWeight                                      } # base
+ {                         fontSize, lineHeight, letterSpacing } # extended
-----------------------------------------------------------------
  { fontFamily, fontWeight, fontSize, lineHeight, letterSpacing } # composed

---

Context

I've got a slew of various font + style combinations for my typography styles (3 different fonts, 10 different styles/font), and I'd like to minimize the amount of duplicate definitions.

I'm thinking that I could define a "base" token, that defines common styles among typography tokens for a particular font, so that I can compose a final value out of base + style, as follows...

{
  "type": {
    "base": {
      "$type": "typography",
      "$value": {
        "fontFamily": [ "Arial", "sans-serif" ],
        "fontWeight": 400,
      }
    },
    "heading1": {
      "$value": {
        "fontSize": "48px",
        "lineHeight": "1.25",
        "letterSpacing": "0px",
      }
    }
  }
}

When I apply this to Sass, I should then be able to compose a final definition as follows...

@use "sass:map";

// generated from tokens.json
$type-base: (
  "fontFamily": (Arial, sans-serif),
  "fontWeight": 400
);
$type-heading1: (
  "fontSize": 48px,
  "lineHeight": 1.25,
  "letterSpacing": 0px
);

// manually composed style Map
$heading1: map.merge($type-base, $type-heading1);
// ^^ should be equivalent to...
$heading1: (
  "fontFamily": (Arial, sans-serif),
  "fontWeight": 400,
  "fontSize": 48px,
  "lineHeight": 1.25,
  "letterSpacing": 0px
);

[chris-dura]

So being able to use something like em that is relative to the font size for line height and letter spacing would be really great.

@EllyLoel -- I think em should be supported, but fwiw, at least for line-height... "unitless" line-height is almost always the best practice.

Unitless line heights are recommended due to the fact that child elements will inherit the raw number value, rather than the computed value. With this, child elements can compute their line heights based on their computed font size, rather than inheriting an arbitrary value from a parent that is more likely to need overriding.

[EllyLoel]

I think em should be supported, but fwiw, at least for line-height... "unitless" line-height is almost always the best practice.

@chris-dura Yeah I'm on the same page, "unitless" line-height is almost always the best option, but we should allow options even if they aren't best practice because there will likely always be an edge case.

[CITguy]

I agree, there may be valid use cases for defining a line-height with a unit, so it makes sense that the lineHeight prop should support either a unitless number or a Dimension.

• The current drawback to Dimension support is that the spec only supports ~px~ a subset of potential units, but it's possible that it could be expanded in the future to support additional units.
• Unfortunately, if an author requires the use of a % value, there's no token type in the spec that currently supports it.
• A possible fallback for the lineHeight property could be a verbatim string instead of a number or Dimension, but that runs the risk of incompatibility when translated to different environments. What works in CSS may not translate to other platforms.

[chris-dura]

The current drawback to Dimension support is that the spec only supports px units, but it's possible that it could be expanded in the future to support additional units.

@CITguy -- fwiw, the current draft for the Dimension type also supports rem. https://design-tokens.github.io/community-group/format/#dimension

[tamm]

Having just read this topic in its entirety, I feel the above definitions of Typography seem to differ more in the sense of Typography as a Design Token vs. Typography as a Component.

For a lot of the above-discussed properties a defined composite token might make sense, but in some cases such as the question of whether this might include color attributes it is less clear.

If the goal here is to define a format to share combinations of tokens, perhaps something less strictly defined is more appropriate. But at what point are you defining CSS in JSON? And how would changes to a coupled system like that of CSS impact the maintainability of this composite token?

[caraya]

I think the typography type is trying to do too much.

There are multiple areas we can split the current implementation in a way that would be easier to use and easier to reason through without having to go through every single CSS property and its equivalent in design tools that consume the tokens. I'm also assuming that if a tool cannot use a given property, it will ignore it

The ones that come to mind off the top of my head:

• font-declaration: Equivalent to CSS font-face at-rule and its associated attributes (see MDN). Since the values are specific to a font, I think it's good to create a composite token
• font-layout: line height, font-kerning, letter spacing, word spacing, text indentation. These values are more dependent on the design of content so they should be more flexible or open

[fraincs]

This feels like a game of 80/20 here. How can the typography catch 80% of use cases? Out of the 57 CSS properties some are more useful than others.

The ones that I feel should be at least included, that would cover many cases are text-decoration(useful for link styles), and text-transform(useful for all caps titles/labels).

[VIPofJoy]

After much thought, I firmly believe that font weight should not be part of typographic tokens. For example, in the example in the screenshot below, the regular weight content contains a small amount of bold-weight content.

[fraincs]

These bold text would have to be in a DOM element anyway, a different token would be used.

After much thought, I firmly believe that font weight should not be part of typographic tokens. For example, in the example in the screenshot below, the regular weight content contains a small amount of bold-weight content.

[VIPofJoy]

My thinking is that the font-weight attribute should be applied to the tokens individually. typography token don't need a font-weight attribute. Under normal circumstances, users only need to apply typography tokens. If partial text needs to be bolded, first select the text, and then apply font weight tokens. For those bold headlines, you can use the composite token. It contains typography tokens and font weight tokens. This is in line with the design logic of the web front end.

These bold text would have to be in a DOM element anyway, a different token would be used.

After much thought, I firmly believe that font weight should not be part of typographic tokens. For example, in the example in the screenshot below, the regular weight content contains a small amount of bold-weight content.

[TravisSpomer]

In this case the font weight tokens are telling you what the "normal" and "bold" weights are, so tokens are still a great match for this. For example, maybe design wants "Apple Design Resources" and all of the other bolded sections to appear in weight 600 instead of 700. That's still typically a decision for the design language—the tokens—and not the content being presented.

[chris-dura]

After much thought, I firmly believe that font weight should not be part of typographic tokens. For example, in the example in the screenshot below, the regular weight content contains a small amount of bold-weight content.

IMO, I think the idea behind "typography/type-style tokens" is that this would not be thought of as "regular weight content"... it would be thought of as "body paragraph style content", and it has a couple "strong body paragraph style content" elements.

[equinusocio]

Small question...why are we putting inside the spec terms that exist only inside CSS? DT are platform agnostic, they must be transformed for each platform and web/css could not be included. For example letter-spacing is a CSS only thing, the technical name is kern/kerning and for example on iOS is called kern, not letterSpacing... It seems this spec is becoming web-target-only, and so useless for a real multi-platform project (where DT really shine)

[TravisSpomer]

The technical term for letter spacing would be tracking, not kerning. (Kerning is different from tracking—in CSS that's font-kerning.)

I'm in favor of terms everyone can understand, and "letter spacing" is self-explanatory and familiar to everyone, where "tracking" is not. I agree it's very important that this spec not become CSS-only, but it's just natural that CSS terms are going to be familiar to the most people. (So for example, I'd prefer "line height" instead of "leading," too.)

[mryechkin]

I'm in favor of terms everyone can understand, and "letter spacing" is self-explanatory and familiar to everyone, where "tracking" is not.

Agreed. I always have to stop and think about which is which (leading vs tracking) when using Tailwind CSS for example, whereas something like "line height" and "letter spacing" is self-explanatory.