community-group
community-group copied to clipboard
design-tokens
Additional property -> $comment
Comment
We currently have the "description" property that tools could use in different ways to inform users about the intention of a token. However, these definitions are in many cases very different from an actual "comment" used for example in code.
A dedicated property to add code or design comments about a specific token would be great.
My proposal for this is "$comment"
What do you see as the difference between a "description" and a "comment"?
What do you see as the difference between a "description" and a "comment"?
For example in a "font-size" token, you could add a "$description" for a specific token saying; "This font size should be used only for short opening paragraphs.", and add a "$comment" for the developer's user experience saying; "1.25rem - 20px". That way, tool manufacturers will also have a better predictor as to when to print a comment with a token in code and when not. Documentation tools can use the $description for display and know that it is intended for that purpose.
Hi @reblim, that's a good point.
In my opinion, $description & $comment are too similar and this is not obvious for the affordance.
In your example, $comment is used for developers' hand-off. Do you have other use-cases? Because "1.25rem - 20px" can easily be retrieved by design tool vendors thanks to the format module standard.
Thanks again for your proposition, can't wait to read you :)
Hi @lauthieb,
The example I provided is a very simple one. However, there are plenty of scenarios where you can make a difference between what's communicated in a documentation tool, or to designers versus what can be a comment in code. The $description prop can be used to provide a more descriptive "actual" description of the token, whereas the $comment prop could serve more as information about the token that does not have to be exposed, or better yet, must be kept private.
Hi @reblim oh okay I understand better. Maybe a more explicit could help understand. I didn't understood directly that comments means "comment inside the codebase"
Thank you for this suggestion. The spec editors have reviewed this issue and decided not to add this functionality to the specification at this time. We understand the constraint of the JSON format does not allow for commenting, but in order to keep the feature set of the initial spec small, we're going to stick with a single $description field for now.
I believe that choosing simplicity is not the right approach when talking about a specification. I would like to hear a better argument before this ticket is closed.