feat: add preExpand meta info to expanded tokens

[jorenbroekema]

Issue #, if available:
A user has told me that it's kinda difficult for him to apply custom transforms to typography token properties such as letterSpacing or lineHeight, because after expanding them they are typed as dimension/number respectively, and therefore it's hard to set a filter function that matches only letterSpacing/lineHeight tokens when the types have been aligned / reduced to DTCG types.

Description of changes:

Add metadata under $extensions.['com.styledictionary'] (where metadata should go from now on, following DTCG guidelines) so you can set a transform filter that targets expanded typography -> lineHeight tokens

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[dbanksdesign]

While this change seems small, I think it warrants a larger discussion. This is the first time we are using $extensions part of the design token. Once we add this in, it will be difficult to remove.

I would like to see some docs added in this PR as well. It would be helpful to see an example in docs that lays out the user problem this is solving.

[dbanksdesign]

Should this be compositionType to be more explicit?

[jorenbroekema]

compositeType I guess? Although both is probably fine

[dbanksdesign]

This is the first time Style Dictionary is using $extensions. Do we expect to put more in here later?

[jorenbroekema]

I'm thinking that perhaps it makes sense to move other properties that Style Dictionary adds to the token metadata under this namespace, as not to clash with metadata that the token author themselves may add. This could be planned for a future v5 I reckon

[jorenbroekema]

I'll add some docs on this, I agree it makes sense to be clear about use cases 👍🏻

[jorenbroekema]

Hey @dbanksdesign I added some docs, and while describing the use case of letterSpacing I started to realize that maybe we don't need to go through with this PR.

I'm arguing that e.g. for typography.letterSpacing you want to preserve the original type in metadata so you can apply a letterSpacing-only transform on it while still having it be a dimension token, making dimension-specific transforms also apply.

So essentially, this token has 2 types in a sense. But that's kinda stupid imo because a standalone token of type "letterSpacing" could never have 2 types, so expanded tokens would be unique in that capability; this doesn't make much sense.

So if a DTCG extension spec decides there are types that don't exist (yet) in DTCG, they just have to add them to the expandTypesMap:

{
  expand: {
    typesMap: {
      typography: {
        letterSpacing: 'letterSpacing'
      }
    }
  }
}

And then the expanded letterSpacing properties of typography tokens will be of type letterSpacing and you can apply your transform on it. If you then need a StyleDictionary built-in transform to apply to those as well but they only apply to dimension tokens, StyleDictionary actually makes it pretty easy to do this:

StyleDictionary.registerTransform({
  ...StyleDictionary.hooks.transforms['size/rem'],
  filter: (token, options) => {
    const type = options.usesDtcg ? token.$type : token.type;
    // original only applies to dimension and fontSize
    return ['dimension', 'fontSize', 'letterSpacing'].includes(type);
  }
})

This overrides the built-in 'size/rem' transform with a custom filter that includes letterSpacing tokens.
I think the above trick should be better documented though, it's useful for any platform/package that extends the DTCG types but also wants to have the built-ins apply to the extended types in some cases (e.g. letterSpacing is an extension of dimension in this example).

Conclusion: I'd like to close this PR since I don't see an urgent need for it anymore. I'll raise an issue to document the above thing better.

[jorenbroekema]

#1334 @dbanksdesign I found a use case for this PR to be reopened

[aws-amplify-us-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-1269.d16eby4ekpss5y.amplifyapp.com