Re: [community-group] Token name - reserved words (#61)

You're quite right @TravisSpomer, thanks for pointing out my mistake about things in JS not being allowed to begin with `$` (now that I think about it, I used to use jQuery back in the day so I knew this was OK😝). I've updated my comment aboved accordingly. The same might not be true in other programming languages though and we shouldn't assume that every tool that wants to read or write design token files will be written in JavaScript.

I do agree this topic needs further consideration and debate.

@ivnmaksimovic's suggestion of nesting a group's children under a `tokens` property and thereby allowing the top-level group object to be reserved for only format-specific properties is quite elegant. However, if you don't use any special group properties, then it might look a bit verbose.

```jsonc
{
  "group-1": {
    // "special" group properties 
    "description": "Only the coolest tokens get to be in this group!",
    "type": "dimension",

    // this group's items:
    "tokens": {
      "token-1": { "value": "2rem" },
      "token-2": { "value": "99px" },
      "nested-group-1": {
        "description": "A nested group",
        "tokens": {
          "deep-token-1": { "value": "1rem" },
          // ...
        }
      },
      // ...
    }
  },
  
  // So far, so good. But when your group doesn't use any special properties
  // you still need put the items inside a tokens prop.
  "group-2": {
    "tokens": {
      "token-A": { "value": "#ff0000", "type": "color" },
      "token-B": { "value": "#00ff00", "type": "color" },
      "nested-group-A": {
        "tokens": {
          "deep-token-A": { "value": "#00ff00", "type": "color" },
          // ...
        }
      },
      // ...
    }
  }
}
```

What if we flip the idea though? Rather than nesting the group's items, we nest the special properties instead. Let's imagine we have a special `metadata` property for groups and descriptions, default types, etc. all go in there. The example above could then be written as:

```jsonc
{
  "group-1": {
    // "special" group properties 
    "metadata": {
      "description": "Only the coolest tokens get to be in this group!",
      "type": "dimension"
   },

    // this group's items (now at the top level):
    "token-1": { "value": "2rem" },
    "token-2": { "value": "99px" },
    "nested-group-1": {
        "metadata": {
          "description": "A nested group"
        },
        "deep-token-1": { "value": "1rem" },
        // ...
      }
    // ...
  },
  
  // Groups that don't use any special properties remain the same as they are
  // in the current spec draft
  "group-2": {
    "token-A": { "value": "#ff0000", "type": "color" },
    "token-B": { "value": "#00ff00", "type": "color" },
    "nested-group-A": {
      "deep-token-A": { "value": "#00ff00", "type": "color" },
      // ...
    }
    // ...
  }
}
```

We'd still have the same benefits:

* We only need one reserved word (e.g. `metadata`) that group items can't use as their name
* No risk of naming clashes with group items if we want to add more special properties in the future

What do you think?


-- 
GitHub Notification of comment by c1rrus
Please view or discuss this issue at https://github.com/design-tokens/community-group/issues/61#issuecomment-985042086 using your GitHub account


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

Received on Thursday, 2 December 2021 22:10:25 UTC