community-group
community-group copied to clipboard
design-tokens
Additional property -> "$reference" (for alias tokens)
Reference
When talking about "alias" tokens. One of the key properties I miss in this specification is the one that would allow me to identify the token that an alias token is referring to. We currently have the value property, which is supposed to inform us about the token used, but the value of the alias token in many cases will simply represent a "path" to the "option" or "primitive" token "value".
It would be very helpful to have a property that preserves the name of the referenced token as is.
My proposal for this is "$reference"
maybe best to split this in two separate tickets. It's tricky to discuss two questions in a single thread :)
maybe best to split this in two separate tickets. It's tricky to discuss two questions in a single thread :)
Good idea ;)
Done, here is the ticket for the "$comment" property: https://github.com/design-tokens/community-group/issues/146
Could you explain a little bit about why this would be helpful? I'm guessing you mean for things like using var(...) in CSS output. But there's no reason that token tooling couldn't preserve that information for you using the current spec, without using a redundant property. If I recall correctly, Style Dictionary 3 already does that.
For example, when working with deep-nested alias tokens, tools could expose the $reference property (name of the referred token) to the UI to let the user understand token inheritance a bit better.
When an "alias" token inherits its value from another token, the value of the token becomes the value of the original "option" or "primitive" token. It would be handy to also have a property that tool makers could use to expose the name of the token. This is so that users can make a better mental model of how tokens inherit values and where these come from.
You can read more about my "options" or "primitives", and "aliases" proposal here.
In the current spec, tokens can either have actual values - which, to use your terminology, would make them an "option" or "primitive" token - or they can be references to other tokens - often called "alias" tokens.
I believe the 2 kinds are already easy to distinguish for both tools and humans. The rule is: If the token's $value is a string in the form "{path.to.other.token}", then it's an alias token. Otherwise, it's an "option" token and the $value is the actual token value.
Furthermore, the "{path.to.other.token}" value of an alias token clearly identifies which other token it's pointing to.
I'm therefore struggling to understand what additional info a $reference property would contain and how that would make the relationship between alias token and option token clearer than it already is.
@reblim could you perhaps provide an example of how you'd expect $reference to be used? Maybe that'll help me better understand your intent.
A simple example could be that a token tool uses a default and tag to allow alias tokens to select from existing "options" or "aliases". If done this way, the option will use the actual value of the token being referred to, but it would be helpful also to be able to display the actual "name", and perhaps "path" of the original token.
$reference: { $name: String, $path: String, }
A token tool could easily do that today with the current spec though. The path is right there between { and }. The value is the $value property of the object that path points to. Any tool that deals with tokens will need to constantly parse strings between { and } all the time and look up values from those strings. And once it does, it can also get other things besides the $value property, like the $description property for showing in a tooltip or elsewhere. The tool already has all of the information it needs to be able to do all of that.
@TravisSpomer Of course, I mean to use $reference as a property (maybe) strictly populated by tools. But still believe that it would be a convenient property to have access to from other tools, especially design tools like Figma or Sketch.
This comes back to an area where I think the spec is stringly typed when it could be strongly typed.
Currently, alias is determined from a leading and trailing {}. However, the definition could be either a token has a $value or an $alias. The syntax for alias tokens might then disallow a $type field because the type is from the aliased token.
Stronlgy typing the spec could be a great solution to many of the current issues. I really like this from @KyleWpppd the definition could be either a token has a $value or an $alias. The syntax for alias tokens might then disallow a $type field because the type is from the aliased token. what are the arguments against this?
Stronlgy typing the spec could be a great solution to many of the current issues. I really like this from @KyleWpppd
the definition could be either a token has a $value or an $alias. The syntax for alias tokens might then disallow a $type field because the type is from the aliased token.what are the arguments against this?
I don’t think it’s a fair assumption that all token references will be singular direct aliases to another token. I’ve seen dimensional tokens that combine two other dimensional tokens (sum, product, etc), color tokens that may mix an opaque RGB color token with a token for an alpha value. Providing a token that effectively maps to a CSS shadow requires at least two dimension values and color.
As a maintainer of a design system I could definitely see value in understanding reference relationships between tokens, so I could understand the knock-on effects of deprecating, removing, or modifying a token. In so much as a tool was built for the express purpose of managing collections of design tokens and/or themes; that would be an ideal place to surface that data. I think it’s more useful to understand which tokens are depended on by whichever token I was isolating (e.g. if I’m looking at an option token, which alias tokens are referencing it, and perhaps which component tokens are referencing said alias tokens.) As was said previously, the $value field already fully explains which tokens the isolated token references (I suppose a case could be made to reveal second-order references similar to how I mentioned above for the component references of alias tokens).
In any case, token tooling can dynamically calculate these references at interpretation time and reveal them as needed to the user - I’m not sure I see an advantage to including it in a specification that is at least nominally intended to be written by hand. This request seems to clearly meet the non-essential metadata guidance for entries in the $extensions field.
Thank you for this suggestion. The spec editors have reviewed this issue and decided not to add this functionality to the specification.
