Comments for categories, etc. (not just properties)

[lukasoppermann]

It would be great if comments could be supplied at other levels of the json tree and not just within a property.

Use case:

{
  "color":{
    "utilities":{
      "comment":"Use these colors only when specified in design docs, they are only to be used in specific situations",
      "error":{
        "value":"red",
        "comment":"Use for error text on bg-error"
      }
    }
  }
}

This would than ideally translate to something like this in css and similarly to other languages.

/* Use these colors only when specified in design docs, they are only to be used in specific situations */
--color-utilities-error: red; /* Use for error text on bg-error */

Since one of the big benefits of design tokens should be that it brings more documentation to a design system, allowing for more written documentation within the system would be very helpful towards this goal.

[vkoopmans-resoluut]

Absolutely! Great idea

[dbanksdesign]

Those would work, except those comments (or any other metadata) would not be reflected in some formats, like css/variables or scss/variables for example. Other than the issue with json/nested (#464 and PR #465 ), the json format will pass that data through to the output. But maybe we could make css/variables and scss/variables output those comments as well.

[lukasoppermann]

It would be awesome if the comments would be added above the nested values. 😍

[jared-christensen]

I think supporting category comments would make storybook design tokens easier to work with. https://github.com/UX-and-I/storybook-design-token