[community-group] [Meta] Do functions/transforms happen before tokens.json (i.e. to generate it)? Or within tokens.json? (#238)

drwpow has just created a new issue for https://github.com/design-tokens/community-group:

== [Meta] Do functions/transforms happen before tokens.json (i.e. to generate it)? Or within tokens.json? ==
In reviewing a lot of discussion around the DTCG format, one of the biggest continuing debates that seems to pop up in about every suggestion or discussion is the fundamental nature of the JSON file. Is the DTCG spec…

1. **Static token values** (that have been generated from some previous GUI/design tool)?
2. Or is it **A set of formulae** that must be computed to get the final token values?

Many discussions have their authors taking the position of “static values” or “formulae” (terms I’m inventing just for the sake of discussion). The different approaches by contributors tend to result in different solutions / different proposals / different terminology that has led to some confusion and delay in consolidating on approaches. To give some concrete examples:

- The Token Operations proposal ([#224](https://github.com/design-tokens/community-group/issues/224)) seem to assume DTCG should be formulae
- The Color modifiers proposal [#88](https://github.com/design-tokens/community-group/issues/88) also seem to suggest formulae
- The Modes proposal ([#210](https://github.com/design-tokens/community-group/issues/210)) operates off the assumption of static values (assuming the values are generated from Figma), and the large discussion it sparked resulted in both [formulae supporters](https://github.com/design-tokens/community-group/issues/210#issuecomment-1553011810) and [static supporters](https://github.com/design-tokens/community-group/issues/210#issuecomment-1633721916)) both offering responses/proposals to the original concept.

Both the static and formulaic approach are 2 proposals to the same solution: generating a large set of design tokens quickly. But I wanted to write down some thoughts to distinguish the two approaches in the hopes that we could **figure out which of the two the DTCG spec wants to follow.**

## Static values

The static values approach takes the philosophy that **what’s in the JSON are the final values.** Aliases are still allowed of course, but no work is needed to figure out the values

**Pros**

- **Computationally Efficient**: no work is needed to determine token values
- **Statically-analyzable**: Makes [token linting possible](https://cobalt-ui.pages.dev/guides/linting) such as a11y contrast checks (which require static values to work)
- **Portable/universal**: Interop is simple because it’s read-only
- **Follows prior art**: Borrows best practices from existing schema formats like OpenAPI and JSONSchema
- **Flexible**: because all values are static, values can be inconsistent

**Cons**

- **Dependent on external tooling**: this format can’t be generated directly and must be an output of another tool (which may already be a shared assumption, but still worth calling out)
- (Possibly) **Inconsistent**: some values may have typos or errors (which is a reality of other schema formats like OpenAPI, but still worth calling out)
- **Difficult to maintain**: changing one rule could cascade to all values needing to be regenerated, for whatever reason

## Formulaic values

The formulaic values approach allows for a few manual configurations to generate an entire design system with ease. It enforces consistency but comes at the cost of a [<abbr title="Domain specific language">DSL</abbr>](https://en.wikipedia.org/wiki/Domain-specific_language) of sorts to work.

**Pros**
- **Powerful**: an entire design system can be built out of just a few key values (e.g. ilikescience’s [“Crafting colors with functions” idea](https://matthewstrom.com/writing/generating-color-palettes/))
- **Low maintenance**: Only small tweaks are needed to change the entire system, and with little noise
- **Consistent**: values always follow a logical pattern, and are internally consistent/coherent with one another

**Cons**
- **Computationally (more) expensive**: Since each token can’t be statically-read, work has to be done to compute the values (“run” the functions)
- **Mentally complex**: As [some proposals have outlined](https://github.com/design-tokens/community-group/issues/210#issuecomment-1553011810), calculating the final values of tokens may be too complex and requires flowcharts and large systems to even follow mentally what’s happening
- **Inflexible**: If all values are the result of a function, overrides/one-off values become more difficult/impossible to produce
- **Manually-written**: Can’t be generated by an external tool because itself is a DSL _meant_ to generate values.

## Evaluating the two

If that provided enough of a distinction between the two approaches, along with how to classify proposals as one or the other, we should probably ask “which direction should the DTCG spec go in?” And my 2¢ is the major missing piece is **there is no current design tool that can generate the DTCG spec in its entirety** (probably closest is Figma Variables + [TokensBrücke export](https://www.figma.com/community/plugin/1254538877056388290/tokensbrucke)) and a lot of bets are placed on **“will that tool ever exist?”**

If your answer is “no,” and you are doing a lot of manual JSON fiddling, the natural inclination is to take a programmer’s approach and try and express formulae for generating values, and want the DTCG to becomet hat. If your answer is “yes,”—either out of optimism, or you have just built your own custom tools to supplement your design systems—then a DTCG JSON with all-static values is all you need.

To show my cards, I do fall in the “DTCG should be static values” camp as someone that works with OpenAPI/JSONSchema a lot and sees the JSON format’s strengths in describing static data. And the formulaic approach does _technically_ produce static values eventually; it’s just more of a secondary/implicit process. And lastly, the dichotomy is not “are functions/formula needed for a design system” because I think the answer is a universal, resounding **YES** from everyone. It’s more a matter of whether they fall outside the boundary of the DTCG spec or not.

Would love additional thoughts on whether a) outlining this principle as part of the DTCG goals is worthwhile, and b) any additional criteria/considerations/input on navigating the two approaches!

Please view or discuss this issue at https://github.com/design-tokens/community-group/issues/238 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Tuesday, 30 April 2024 17:51:34 UTC