Comments (9)
I think the $type
alias is to allow for parsers just to know to check an object and its properties. Otherwise how would it know to check for colors? It’d have to assume a token structure (like all colors are under top level color
property).
It also helps explicitly define the type of the token, since you might want to mix tokens to achieve another (like combining opacity number and RGB color to make a RGBA new color). Or for example, if you multiply fontSize
and a spacing
token, what is the type of the result? Might get weird for parsers.
I do think there you have a great idea of not including it every time though. It seems verbose and makes it difficult to manually parse JSON without a tool to strip the noise. Not sure how to practically achieve that without an explicit structure or some other system to accommodate for the inference of types.
Also this issue emphasizes the need for a section of the docs on parsing, and expectations the spec has - to create some consistency between tooling.
from community-group.
I think the
$type
alias is to allow for parsers just to know to check an object and its properties. Otherwise how would it know to check for colors? It’d have to assume a token structure (like all colors are under top levelcolor
property).
Well that’s just the thing though—parsers actually have to validate aliases currently. Aliases have to be non-circular. And non-aliases have to be valid tokens. By just accepting an invalid schema at face-value, the user will get errors with no clear action on how to fix it. So parsers actually do have to scan the alias and know it’s referring to a color anyway, and there’s no way for them to avoid having that work (or they’d be bad, hard-to-use-tools). But I was more interested in exploring whether that’s an error to show to the user “fix this!” or if it just silently works
Also this issue emphasizes the need for a section of the docs on parsing, and expectations the spec has - to create some consistency between tooling.
💯!
from community-group.
The spec lists out the following resolution order:
A token's type can be specified by the optional $type property. If the $type property is not set on a token, then the token's type MUST be determined as follows:
- If the token's value is a reference, then its type is the type of the token being referenced.
- Otherwise, if any of the token's parent groups have a $type property, then the token's type is inherited from the closest parent group with a $type property.
- Otherwise, the token's type is whichever of the basic JSON types (string, number, boolean, object, array or null) its value is.
So, in your examples
{
"color": {
"a": { "$type": "color", "$value": "#336699" },
"b": { "$value": "{color.a}" }
}
This is valid, and color.b
has a type of color
.
{
"color": {
"a": { "$type": "color", "$value": "#336699" },
"b": { "$type": "dimension", "$value": "{color.a}" }
}
This is invalid; the spec says that a token with the type dimension
must be "a string containing a number (either integer or floating-point) followed by either a "px" or "rem" unit". Since {color.a}
doesn't match this, this is an invalid token.
{
"base": {
"$type": "color",
"a": { "$value": "#336699" }
},
"semantic": { "$value": "{base.a}" }
}
This is valid, and semantic
would get resolved to having the type of color
(since base.a
has the type of color
).
The spec is pretty unambiguous about these, though it might need a bit more language to acknowledged that a referenced token might inherit its type, too, either from its group or another reference.
I can’t think of a good reason for even declaring $type on aliases
Yes, almost any type on a token with a value like {base.a}
will result in an invalid token. There's probably some weird edge cases where you can have a token with a fontFamily
type which, according to the spec, would be valid, resulting in css like font-family: '{base.a}'
... but resolving this would probably create substantially more edge cases than it would solve.
from community-group.
There's probably some weird edge cases where you can have a token with a
fontFamily
type which, according to the spec, would be valid, resulting in css likefont-family: '{base.a}'
... but resolving this would probably create substantially more edge cases than it would solve.
Oh I hadn’t even thought of this, but you’re right just evaluating a token’s $type
by parsing its value could lead to many errors. Especially if string
tokens ever were accepted (not that they are in the DTCG now, but mainly thinking of Figma variables’ current implementation where string types can refer to colors or typography values).
The spec is pretty unambiguous about these, though it might need a bit more language to acknowledged that a referenced token might inherit its type, too, either from its group or another reference.
Agreed—I think clarifying this would help. The resolution definition you provided earlier implies this, but doesn’t outright explicate it, and it could be clearer.
Thanks for clarifying! This seems like it’s not really ambiguous, then, how the spec is interpreted. More just a possible documentation TODO of “should alias types get a little more specific regarding this behavior or not”.
from community-group.
We are experiencing 2 simular problems:
- aliases should as state include the type they refer to
- there are not enough types to describe the data
Let's first dive into the aliases, but the second seams related to so I added that in the end.
The aliases would have a solution to include a type in xml I beleive as an attribute can hold the class. But json does not have attribute in its spec. In joson I would like to propose a way to include the type.
{
"background": {
"gradient": {
"value": {
"path": "gradient.default.1",
"type": "color"
},
"type": "reference"
}
}
}
This reads as: "at the path background.gradient.value
there is a reference to a node of type color". This way we can include the type in the json.
My second remark is about the different allowed types in the Design Tokens spec. Could someone refer me to another related issue?
Remark: When writing a parser for a color value, one needs to parse a single color as
color=hex
, a gradient is of formcolors=[(hex, 50%),(hex, 10%),(hex, 30%)]
. This represents a distinctly different schema.
To conclude might I suggest to preferably add more types to the spec but definatly use the json structure to include the reference type that has a path
and a type
as properties?
from community-group.
I thought a lot about the issues you mention @doozMen, and I landed on the same conclusion: the json tree lacks data.
That said, the format specification aims for user-friendliness rather than ease of parsing when tradeoffs like this one shows up. I don't think we'll get the format to host the missing pieces.
BUT, we can still specify a mapping for allowed aliasing matches among tokens:
// Example with Border token
const borderTokenTypeMapping = {
_unionOf: [
{ _tokenType: borderTokenTypeName },
{
_mapOf: {
color: colorTokenTypeMapping,
style: strokeStyleTokenTypeMapping,
width: dimensionTokenTypeMapping,
},
},
],
} satisfies TokenTypesMapping;
Beside this off-initial-topic answer, shouldn't we close this issue?
from community-group.
I’m happy to close the issue, yeah. There might be a TODO on just adding some additional clarification in the documentation, but no spec changes are necessary IMO.
from community-group.
I thought a lot about the issues you mention @doozMen, and I landed on the same conclusion: the json tree lacks data. That said, the format specification aims for user-friendliness rather than ease of parsing when tradeoffs like this one shows up. I don't think we'll get the format to host the missing pieces.
BUT, we can still specify a mapping for allowed aliasing matches among tokens:
// Example with Border token const borderTokenTypeMapping = { _unionOf: [ { _tokenType: borderTokenTypeName }, { _mapOf: { color: colorTokenTypeMapping, style: strokeStyleTokenTypeMapping, width: dimensionTokenTypeMapping, }, }, ], } satisfies TokenTypesMapping;Beside this off-initial-topic answer, shouldn't we close this issue?
Thanks for taking my off-topic suggestion into account. Your suggestion to have a mapping slightly slows down the parsing and at least for me is less readable but if this is possible is there an issue I can track to when this mapping description lands in the spec?
from community-group.
Related Issues (20)
- Specification / recommendation for custom types HOT 4
- Token Operations
- The $ property name prefix should be unnecessary with a well-structured schema HOT 10
- [Discussion]: How to transform composite tokens HOT 5
- Transition token documentation issue HOT 1
- Suggestion: colorList type for DataViz HOT 6
- Most recent edition (07/2023) missing from main page on w3c community group HOT 1
- A comment about history of design tokens HOT 2
- Type: Text alignment HOT 12
- Custom Types / Interpritations HOT 2
- Is there a way to still include boolean and string type functionality? HOT 1
- Be explicit about whether or not empty groups are allowed HOT 5
- [Meta] Do functions/transforms happen before tokens.json (i.e. to generate it)? Or within tokens.json? HOT 4
- Multiple values - Array type HOT 3
- Toughts on the Use of "$" Prefix in the DTCG Token Standard HOT 8
- Are references generally allowed in arrays? HOT 1
- Dimension type expanded unit types HOT 5
- How library and tooling authors do keep track of conformance and changes? HOT 5
- $type: cubicBezier HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from community-group.