[community-group] ambiguity around nested vs. flat structure (#253)

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

== ambiguity around nested vs. flat structure ==
[6. Groups](https://tr.designtokens.org/format/#groups) states:
>A file MAY contain many tokens and they MAY be nested arbitrarily in groups like so:

```
{
  "token uno": {
    "$value": "#111111",
    "$type": "color"
  },
  "token group": {
    "token dos": {
      "$value": "2rem",
      "$type": "dimension"
    },
    "nested token group": {
      "token tres": {
        "$value": 33,
        "$type": "number"
      },
      "Token cuatro": {
        "$value": 444,
        "$type": "fontWeight"
      }
    }
  }
}
```

But [6.2.1](https://tr.designtokens.org/format/#file-authoring-organization) also states:
>Groups let token file authors better organize their token files. Related tokens can be nested into groups to align with the team's naming conventions and/or mental model. When manually authoring files, using groups is also less verbose than a flat list of tokens with repeating prefixes.
```
  "brand": {
    "color": {
      "$type": "color",
      "acid green": {
        "$value": "#00ff66"
      }
    },
```

...is likely to be more convenient to type and, arguably, easier to read, than:

```
  "brand-color-acid-green": {
    "$value": "#00ff66",
    "$type": "color"
  },
```

Does that mean the two are supposed to represent the same thing? Because the first example represents a token "acid green" and the second example represents a different token "brand-color-acid-green". 

This seems to suggest there are two different ways to parse a token file: nested or flat. Nested means I should consider the entire token path as part of the token name. Flat means I should assume that the token name is already flat and that any nested paths are just an arbitrary way of grouping items. 

It's very confusing to see that:
```
    "nested token group": {
      "token tres": {
        "$value": 33,
        "$type": "number"
      }
```
represents a token named `token-tres` and NOT `nested-token-group-token-tres` while also seeing that 


```
  "brand": {
    "color": {
      "$type": "color",
      "acid green": {
        "$value": "#00ff66"
      }
    },
```
represents a token named `brand-color-acid-green`. 

I feel like it should be possible to consume a .token file and be able to output a list of all the available design tokens using only the format. Would it be possible to add more clarification around these concepts? 

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


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

Received on Saturday, 28 September 2024 14:57:57 UTC