Incorrect/unexpected output for $dimension token types when using DTCG format spec

[adamstankiewicz]

According to the DTCG format spec, the $dimension token type (source) should have a $value that:

MUST be an object containing a numeric value (integer or floating-point) and unit of measurement ("px" or "rem").

From the DTCG spec example:

{
  "spacing-stack-0": {
    "$value": {
      "value": 0,
      "unit": "px"
    },
    "$type": "dimension"
  },
  "spacing-stack-1": {
    "$value": {
      "value": 0.5,
      "unit": "rem"
    },
    "$type": "dimension"
  }
}

When trying this syntax for $dimension tokens in style-dictionary v4, we're seeing the following output:

Token definition:

{
  "size": {
    "$type": "dimension",
    "border": {
      "width": {
        "$value": {
          "value": 1,
          "unit": "px"
        },
        "$description": "Default border width."
      }
    }
  }
}

Token output in CSS variables

(Includes a pgn prefix).

--pgn-size-border-width-value: 1; /* Default border width. */
--pgn-size-border-width-unit: 0px; /* Default border width. */

I believe the expected CSS variables output should be:

--pgn-size-border-width: 1px; /* Default border width. */

Our current workaround is to define the token with a $value that combines the value/unit together, e.g.:

{
  "size": {
    "$type": "dimension",
    "border": {
      "width": {
        "$value": "1px"
        "$description": "Default border width."
      }
    }
  }
}

It seems like style-dictionary's support for composite tokens (per the DTCG format spec) is causing $dimension tokens to output multiple variables (i.e., splitting the value from the unit) vs. outputting a single CSS variable combining the configured value/unit.

Is this by design or is there a potential bug when trying to adopt the DTCG spec for $dimension tokens? Thanks!

[jorenbroekema]

I think the dimension type token was updated quite recently in the DTCG spec, we haven't updated Style Dictionary accordingly yet. We need to find a way to do this in a non-breaking manner so that the old method is also still valid for some time at least until the next major version of SD.

• Support new syntax
• Support old syntax
• Update the convertToDTCG utility to correctly convert a set with the old syntax for dimension, to the new, so that they are forward compatible with Style-Dictionary v5

In v5, we will likely stop supporting outdated versions of the DTCG spec (color type will get an update in the spec soon as well).
Additionally in v5, potentially stop supporting the old SD JSON format altogether, but imo that also depends a bit on how stable and complete the DTCG spec is at that point..

[jorenbroekema]

This probably could be picked up by outside contributors as well just FYI, it shouldn't be too difficult from my estimation, so I added good first issue label

[brian-smith-tcril]

@jorenbroekema for clarification, when you say "find a way to do this in a non-breaking manner" do you mean both

{
  "size": {
    "$type": "dimension",
    "border": {
      "width": {
        "$value": "1px"
        "$description": "Default border width."
      }
    }
  }
}

and

{
  "size": {
    "$type": "dimension",
    "border": {
      "width": {
        "$value": {
          "value": 1,
          "unit": "px"
        },
        "$description": "Default border width."
      }
    }
  }
}

from the examples should produce

--pgn-size-border-width: 1px; /* Default border width. */

or do you mean that there should also be a way to produce

--pgn-size-border-width-value: 1; /* Default border width. */
--pgn-size-border-width-unit: 0px; /* Default border width. */

from

{
  "size": {
    "$type": "dimension",
    "border": {
      "width": {
        "$value": {
          "value": 1,
          "unit": "px"
        },
        "$description": "Default border width."
      }
    }
  }
}

[jorenbroekema]

The former:

--pgn-size-border-width: 1px; /* Default border width. */

The latter can be produced as well already, if you use expand and expand the dimension token with the appropriate typesMap: https://styledictionary.com/reference/config/#expand but this is optional of course