I'm not 100% on these tokens, and would welcome feedback. These are being carried forward from existing variables:

Note that I did not use the 499 value here, since this is essentially a browser-specific quirk. As such, it might make sense to apply that transformation as part of the CSS transformation, but the raw value and how it's used elsewhere (e.g. Figma) should be 500.

Being a browser app, isn't it plausible that the same quirk would manifest in Figma though?

Being a browser app, isn't it plausible that the same quirk would manifest in Figma though?

That's a good question. I'm not really sure. Doing some brief inspecting, it looks like the main canvas area in Figma is a <canvas /> element, so I'm not sure if it'd have the same issue.

I think the root of the decision here is codifying the decision that we want 500 as the value in the source design tokens, and dealing with the implementation details as close to the consumption-level as we can manage.

I think we need to ship with 499 until we do actually put in place whatever implementation-side handling is necessary?

Ok, let's go with that. Updated in 5d57c17 . This also means it'll be 499 in Figma, which may be what we want or expect, but may also be slightly misaligned.

I tested it on the web version of Figma on Windows OS, but it seems that Segoe UI cannot be selected in the first place.

On the other hand, in a local app, I can select Segoe UI, but I cannot enter a font weight numerically.

It seems like 500 is probably fine for design tokens.

Thanks for testing @t-hamano ! I'd guess "Semibold" could work here to check. You could also import the tokens themselves as Figma variables so you could use the variable option to check.

These combinations did give me pause to consider if this is evidence of the tokens being "primitive", with "semantic" tokens referencing the combinations of those aspects toward application of higher-level concept of "heading" and "body" content.

There's some suggestion to this effect in examples in the DTCG specification: https://www.designtokens.org/tr/2025.10/format/#typography-component-references

My hunch is that the way we're using these values is still semantic, and something we'll need to support. And maybe, on top of that, we could explore pre-composed combinations as a separate set of tokens referencing these.

I agree they are still semantic. And yes, I think we'll want to offer preset configurations (likely based on these mixins).

Could there be a style property to handle that? It'd allow consumers to use presets, but still override individual aspects when necessary.

Could there be a style property to handle that? It'd allow consumers to use presets, but still override individual aspects when necessary.

I'd want to avoid style ambiguity with the style property, but we could do something like variant="heading" if that's what you mean, where the variant would apply some precomposed "typography" value in typography.json tokens like...

{
  "font": {
    "style": {
      "heading": {
        "$type": "typography",
        "$value": {
          "fontFamily": { "$ref": "#/font/family/heading/$value" },
          "fontWeight": { "$ref": "#/font/weight/medium/$value" },
          // ...
        }
      }
    }
  }
}

Is that what you'd have in mind?

I'd want to avoid style ambiguity with the style property

Derp, of course. Yeah, variant could work. I suppose we'd want presets like body-sm – body-xl and heading-sm – heading-xl. Maybe things like label as well and button.

We should definitely support variants as mentioned, and we should probably assign those styles with a low-enough specificity that will allow consumers to override indivual aspects without struggling (although we should encourage sticking to variables as much as possible)

Being a browser app, isn't it plausible that the same quirk would manifest in Figma though?

We can probably add this package to this exemption.

We can probably add this package to this exemption.

Interesting. I think it'd follow that we'd want this package to be consistent, yes. And generally I think documentation like this specific example isn't especially useful. I think there could be cases where it'd be useful to include (require) parameter documentation, namely when the parameter isn't a props object. I guess it'd be difficult to differentiate.

Any reason why we have a fallback here? I think we can just make that the consumer's responsibility to use a valid token, like the other props.

Any reason why we have a fallback here? I think we can just make that the consumer's responsibility to use a valid token, like the other props.

This component is since removed from the pull request, but I'll revisit this and target itself if / when I propose it in a separate pull request. This followed from the Box component, where Box defaults to "surface" token group values but allows configuring to use another grouping like "interactive" or "track" (not as useful currently, but useful if we consider groupings like "card" or "dialog"). The idea being to always have a fallback if the grouping didn't define its own value. In the case of text color specifically, we don't have "surface" colors, we have "content" colors.

But for Text, I don't know that it was particularly useful to have the fallback, because target only ever affects the text color, so it's reasonable to expect that it'd be assigned to a valid value for text color.

Personally I think this is another upside to these abstractions, as it forces us to reckon with what these groupings actually mean, how they relate to each other, carry over between different types of tokens, etc.

I think we need to ship with 499 until we do actually put in place whatever implementation-side handling is necessary?

It still looks like 2xs is in place of 2xl (both in this file, and in the dependent files generated via the build script)

Whoops, I fixed it for line-height, but missed the one for size, which is updated in 182ad3d.

For added extensibility, have we considered setting an internal CSS property instead of setting inline styles? eg

// in the render function
elementRef.current.style.setProperty("--wpds-text-color", `var(--wpds-color-fg-${ target }-${ color }`);

and use it in the styles

.text {
  color: var(--wpds-text-color);
}

this would allow consumers of text to define the style prop without it being unexpectedly overridden

this would allow consumers of text to define the style prop without it being unexpectedly overridden

Can you clarify the issue here? The component should gracefully merge style from its own as well as passed in from a consumer, achieved with the props spreading here, but I'd expect we could use mergeProps now for this as well.

Even if Text was removed from this PR before merging, I'll still clarify my previous comment.

Reading the code, it looks like certain inline styles (such as color, fontFamily, fontSize, fontWeight and lineHeight) would be overridden by Text via the internal style.* = assignments.

This means that, for example, the inline style in this code snippet would be ignored <Text style={{ color: 'red' }} color={color} target={target} >Hello</Text>

I see what you mean, though I find the use-case a bit hard to follow, since I'd expect someone to be specifying either style.color or color, but not both. In what scenario would they need to provide both?

Although I think more generally it's a question of which takes precedence, and it'd be fairly straightforward to prioritize the style prop values if we wanted that behavior.

Judging by your initial comment, maybe there's also some value in composing those default assigned values into the consumer's overridden value, though again I'm not sure what the practical use-cases would be. Maybe as part of use of a set of values like max, or calculated modifications using calc.

Caveating all this that it's moot unless we decide to implement support for controlling these properties in a Text component 😅

I feel like type or typography would be a better name for this group of tokens — font feels specific to some aspects (family, weight, size, style, face....) but not to all (line height, letter spacing, etc)

Hm, it's a good question. I could have sworn I took inspiration from this somewhere in how the file and top-level grouping was named, but the examples I could find in either the spec or examples in Terrazzo documentation either don't mention it, or do group them as "typography".

I think how I may have been considering it was reserving "typography" as a grouping for the compositions of individual font token values, similar to how it's documented in the specification with "$type": "typography" composing "base/text" values.

I see. In my mind, I still think that "type" or "typography" is a better name for this group, and it seems to match how terrazzo and others' approach too (colors, typography, spacing...).

That doesn't mean that we can not have $type: "typography" (what the spec that you linked above calls a "Typography component").

In fact, it poses the question of how we should structure those "presets" — are they semantic tokens, or an even higer-level entity?

@jameskoster out of curiosity, do you foresee the need for more tokens in the future (targeting things like letter spacing or other metrics)?

Maybe 😄 Difficult to say at this stage. I don't think letter-spacing is used in the existing componentry.

Not a blocker for now, but have we considered which unit to use to express these tokens? Using px, at least initially, makes sense as a way to ensure continuity with previous variables, but I'd like to understand if other alternatives are completely off the table (most typically, rem for sizes, and unitless for line heights)

I'm not personally aware of any consideration to that extent, but I'd be curious as well. I think it's a change we could choose to make down the line also.

I have mentally put rem off the table, one because it's almost impossible to transform an existing app into truly rem-compatible (dynamic) styling, and two because WP is not even 1 rem = 16px 😱

I'm interested in the px/unitless decision for line-height. That has a lot of implications, not only on new things, but for migrations of existing styles (almost all unitless?).

Re line-height, I assumed that unitless was always the better approach, since we can have just a few values and mix-and-match them with different font sizes as needed.