CSS `calc()` in tokens

@adamstankiewicz: (https://github.com/openedx/paragon/pull/3186/files#r1739426413)

[curious] Have we looked into whether we can avoid including CSS-specific syntax calc in the token itself, or how such tokens would be transformed outside of CSS variables?

For example, if there is arithmetic like subtraction as in this line, could the token $value be {size.card.border.radius.base} - {size.card.border.width} and have some sort of transform for the CSS variables output to wrap it with calc(...)?

That way, tokens like these would be more portable to other non-CSS based platforms like mobile.

@adamstankiewicz: (https://github.com/openedx/paragon/pull/3186/files#r1741054546)

Dug into this a bit. It appears this still remains a complex problem within the style-dictionary community. There is support for a resolveMath transform, from tokens-studio/sd-transforms; however, when the token outputs references via outputReferences: true | fn, the transformed/resolved math is replaced with the original reference (i.e., a CSS variable with var(--foo: 5px) in this case).

I attempted to craft a solution for https://github.com/tokens-studio/sd-transforms/issues/203, but came to the same realization recently described [here](https://github.com/amzn/style-dictionary/issues/> 1055#issuecomment-2312072149):

The big issue is that outputting refs happens on the format lifecycle and wrapping values in calc() statements usually happens in the transform lifecycle that happens before. So even if you wrap the values in calc() in transform, the format part will just undo that work by outputting refs by using the original value.

Either the calc wrapping needs to happen on the format level or the outputting refs util needs to act on the transformed value somehow (keeping in mind the bugs that this used to cause in v3 and not regressing on > this again)

There are a couple of open issues to rethink how references are resolved and how values with references in them are transformed for a future v5 version of Style Dictionary, but this topic is rather complex and this issue won't be fixed until we have solutions to that broader topic.

tl;dr; Handling the wrapping of math expressions with the CSS calc syntax remains an open question, and likely will not land in v4 of Style Dictionary per the above. Given this, it probably makes sense to keep the calc syntax for now, but when we begin transforming to non-CSS platforms (e.g., JavaScript, iOS, Android), having calc in the token value itself will present an issue. A possible workaround for if/when this becomes an issue might be to introduce custom transforms for the (future) non-CSS platforms that strips the wrapping calc(...) from the underlying math operations used in the token value.

@PKulkoRaccoonGang (https://github.com/openedx/paragon/pull/3186/files#r1741545240)

This is definitely a very interesting question that we haven't thought about yet. Thanks for your research, now we know more!

A possible workaround for if/when this becomes an issue might be to introduce custom transforms for the (future) non-CSS platforms that strips the wrapping calc(...) from the underlying math operations used in the token value.

It seemed to me earlier that when adding mobile platforms, Style Dictionary would generate the necessary variables taking into account the various CSS tools (calc) that we use for design tokens, converting them into alternatives acceptable for mobile platforms.

I also consulted with Android and iOS developers from Raccoon Gang, they confirmed that there is no alternative to calc CSS. There are tools to do this in the languages ​​of mobile platforms, but it is desirable that Paragon design tokens provide static (integer) values ​​for variables.

I agree with you, most likely in the future (if there are no new Style Dictionary updates) we will have to make additional modifiers for mobile platforms.

Android

<resources>
    <dimen name="size_card_border_radius_base">16dp</dimen>
    <dimen name="size_card_border_width">2dp</dimen>
</resources>

iOS

<plist version="1.0">
<dict>
    <key>size_card_border_radius_base</key>
    <string>16</string>
    <key>size_card_border_width</key>
    <string>2</string>
</dict>
</plist>

Resources

• https://blogs.halodoc.io/simplifying-android-apps-design-with-design-tokens
• https://source.android.com/docs/automotive/unbundled_apps/design-tokens

Start by reviewing the token changes and discussion in PR #3186, then read the linked Style Dictionary references about transforms, output references, and CSS calc() handling. The issue does not identify project files or tests. Done would require a decided approach for keeping token math portable beyond CSS, including how non-CSS platform outputs should represent these values.