[community-group] Token Operations (#224)

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

== Token Operations ==
Hi folks,

I'm working on a large system of themes (collection of design-token: value pairs) which represent brands, modes, and experiments. In lots of cases, it would be beneficial to define a small set of tokens to inform the greater set. A visual example of the expectation is the [Microsoft Fluent UI Theme Designer](https://fabricweb.z5.web.core.windows.net/pr-deploy-site/refs/heads/7.0/theming-designer/index.html).

![Screenshot 2023-07-19 7 34 15 PM](https://github.com/design-tokens/community-group/assets/12616191/758dc5ad-7888-43cd-aa2f-3f7508cffadb)

In the UI, the theme author selects a few colors which will inform the dozens of tokens that are applied to areas of the UI. To do this, the UI will transform the given colors in different ways. The benefit of this is the curation exercise is more accessible; it is easier for someone without much design token experience to create an appropriate theme with a few input values. However, the computations are embedded in the UI itself and resulting values would be written as-is into a tokens JSON file.

[An idea from an issue here](https://github.com/design-tokens/community-group/issues/88#issuecomment-1073374383) was the following:

```json5
{
  "some-token": {
    "$value": "#ff0000",
    "$type": "color",
    "$operations": [
       {
         "alpha": 0.5
       }
    ]
  }
}
```

The problem I found with this approach is that this requires the spec to define what `alpha` means. Also, any new special keys will need to be introduced, reviewed, and agreed before we'd potentially see platforms support them.

The Tokens Studio folks are solving this with [generators and resolvers](https://tokens.studio/tools/resolvers). I believe this is a valid solution with a few drawbacks. At the moment, this is only available within the Tokens Studio ecosystem. While it's possible that this direction _could_ be included in the spec, it brings me to the second point. The resulting file which defines these relationships is no longer human readable. It _must_ be managed within a UI and a larger ecosystem.

One of the principles I've held is that the tokens file should be human editable, even if a bit intimidating. So I believe a solution should attempt to be human readable while defining how a value might be transformed.

Enter [token-operations](https://github.com/ddamato/token-operations).

## [Pre-defined composite type for refering color modifications (e.g. rgba)](https://github.com/design-tokens/community-group/issues/88)

```json5
{
  "some-token": {
    "$type": "color",
    "$value": "#fffc00",
    "$operations": [
      ["Import.operations", "token-operations/lib/hex-value-alpha-rgba", "$value", 0.5]
    ]
  }
}
```

> **Note**
>
> I am not recommending that this project be the de-facto library for sharable operations. This is a very succinct example in an otherwise plugin-like ecosystem.

I believe this direction could solve for a few other issues that I've seen in the community.

## [A token value with multiple aliases](https://github.com/design-tokens/community-group/issues/192)

```json5
{
  "some-token": {
    "$operations": [
      "{hello}",
      "{world}",
      ["String.concat", "$0", " ","$1"]
    ]
  }
}
```

## [Conditional token values](https://github.com/design-tokens/community-group/issues/169)

```json5
{
  "some-token": {
    "$operations": [
      // The number 1 below represents true, previous operations can determine the binary to pass in
      ["Import.operations", "token-operations/lib/binary-if-string", 1, "yellow", "purple"]
    ]
  }
}
```

And with a little bit of thought, it might even solve this if there's interest:

## [Can alias tokens reference tokens in another file?](https://github.com/design-tokens/community-group/issues/166)

```json5
// Does not work in the token-operations project yet, but could!
{
  "some-token": {
    "$operations": [
      ["Import.token", "./some/token/file.json", "{colors.base.primary}"]
    ]
  }
}
```

The project is available as an [NPM install](https://www.npmjs.com/package/token-operations). Love to know what the community thinks of the idea. [Please read the `README`](https://github.com/ddamato/token-operations#readme) before commenting, there's a lot more detail there.

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


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

Received on Thursday, 20 July 2023 00:06:32 UTC