Replies: 7 comments 14 replies
-
Feedback point 1: general explanationAre there any areas of the specification that are confusing and/or lacking explanation? Specifically looking at concepts like:
|
Beta Was this translation helpful? Give feedback.
-
Feedback point 2: Sets & modifier structureAre there design systems that would not work with the single-depth array structure? In our testing, we did find that even complex color systems like GitHub Primer work with this, but are there scenarios that aren’t mentioned that aren’t possible? Are there additional examples we could add? {
"tokens": [
{
"type": "set",
"sources": ["foundation.json"]
},
{
"type": "modifier",
"name": "theme",
"context": {
"light": ["themes/light.json"],
"dark": ["themes/dark.json"]
}
}
]
} |
Beta Was this translation helpful? Give feedback.
-
Feedback point 3: inputIn order for this specification to work, this relies on the idea of “inputs,” or an external, in-memory object that requires a tool to use properly. Any examples of modifiers all require an input to work. We’re looking for general feedback here—are there alternatives? Is this specification too tool-reliant? Is there prior art or other suggestions we missed here? |
Beta Was this translation helpful? Give feedback.
-
Alternative: JSON Schema pointersTo make sure the resolver specification is a necessary addition, we’ve also been exploring the idea of JSON Schema pointers (see #298 and #259 for definition and examples) which may achieve the same goals as the resolver spec, and reuse prior art. High-level conceptJSON Schema pointers (sometimes called {
"color": {
"$ref": "foundations.tokens.json#/color",
"text": {
"$value": { "colorSpace": "srgb", "components": [0.2, 0.2, 0.2] }
"$type": "color"
}
}
}In this example, we’re:
Note Some implementations of JSON Schema pointers do not allow local overrides, while some do. DTCG would need to allow overrides, or “merging” like this in order for this proposal to be viable. The contract would be, roughly, any local siblings alongside Practical exampleGitHub Primer’s color themes could be assembled using
Here is what, for example, {
"color": {
// start with `dark.json`, which may also start with an existing set, and only provide overrides
"$ref": "dark.json#/color",
"blue": {
"0": {
"$value": { "colorSpace": "srgb", "components": [0.875, 0.97, 1], "hex": "#dff7ff" },
"$type": "color"
}
// … all color overrides here
}
},
"motion": {
"$ref": "../foundations/motion.json"
},
"size": {
"$ref": "../foundations/size.json"
},
"typography": {
"$ref": "../foundations/typography.json"
}
}
Comparison to the resolver specSo, taking all this into consideration, how does it compare to this proposal?
FeedbackIn a nutshell:
|
Beta Was this translation helpful? Give feedback.
-
Very much the first, as you said 🙂. I don’t speak for all other spec authors but I’d be surprised if all the other authors aren’t thinking this way. Thanks for raising all the other points. I don’t really have a good response other than “this is valuable feedback!” |
Beta Was this translation helpful? Give feedback.
-
Thanks for the info! My concerns echo Russell’s concerns. Due to sandboxing, it’ll be common for a tool to not be able to even see or read the linked files. One solution for that is to place all files inside a ZIP, but we’re now talking about a wildly different format that’s far more complex than what I believe the initial goals for the DTCG spec were. A similar issue is true for downloading files from a web site or web app — that’s typically restricted to a single file per interaction. Tools might also have to deal with cyclic dependencies and limiting recursive traversal, if the proposal allows for that situation to happen.
I like this suggestion. |
Beta Was this translation helpful? Give feedback.
-
I’m not sure what you mean by “sandboxing” or any of the problems mentioned. This proposal and the JSON Schema alternative can/have been implemented already, with multiple files and even remote files, with no issues. Could you talk more about that? |
Beta Was this translation helpful? Give feedback.
-
Yep! Linking/including is very common within code projects, and it can definitely be done. My comment relates to the way modern OSs handle sandboxing and opening files. Let’s assume you’re trying to open a DTCG JSON file that links to another DTCG JSON file in a Mac app. You choose File › Open (NSOpenPanel) and select the first file. The app is only granted permission to read the first file, and not the linked file. The same thing happens when dragging a file to a web browser for a web app. For me, that’s where the tension lies — apps and browsers are only going to be able to see whatever the user has chosen to open, and they can’t see anything else. As “a file format to exchange design tokens between different tools”, that’s a critical point. The app also doesn’t know if the file is missing, or just inaccessible. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for clarifying. Right, like others have raised, this would need a “bundling” step to package everything into a single file. It’s possible with inline tokens, just at the cost of duplication. Which, if this format requires a bundling step, are there improvements that could be made here to avoid this? |
Beta Was this translation helpful? Give feedback.
-
|
In my case, I also need things to be in a single file for easy transference, and my 'themes' are actually modes and multi modal combinations do affect tokens differently, I've been using the last version (before pointers), using extensions to store theming data and groups to denote modes, made it so that the resolver will resolve the default tokens and then programmatically switching the groups to replicate multi modality, but as of now there is no way to support that switching in the spec itself. And I won't insist the spec have a way to support the switching but at least to be able to represent the theming pathways as switchables instead of different tokens would be very helpful. If I were to deconstruct each theme permutation in a file, it would need thousands of files to represent my modes. https://codepen.io/nesquarx/pen/raNPoMd
<details>
<summary>Code Example</summary>
```jsonc
{
"color": {
"$extensions": {
"com.bayer.figma.groupType": "collection",
"com.bayer.figma.defaultMode": "neutral_grey",
"com.bayer.figma.source": "Foundry tokens"
},
"neutral_grey": {
"$extensions": {
"com.bayer.figma.groupType": "mode"
},
"light_l0": {
"$value": {
"colorSpace": "srgb",
"components": [
0.9450980424880981,
0.9450980424880981,
0.9450980424880981
],
"alpha": 1,
"hex": "#f1f1f1"
},
"$type": "color",
"$extensions": {
"com.bayer.figma.scopes": []
},
"$description": ""
}...
</details>
|
Beta Was this translation helpful? Give feedback.
-
|
Hello, I'm the author of Theemo. Thanks for working on this. As I did most of the stuff in the first half of the year for theemo, I come with great experience and research to this topic (I will return the favor of providing links to research and will sprinkle them in). There is basically two fundamentally ways to store tokens:
Read the comparison I did in the Theemo v1 Blog Post: https://gos.si/blog/theemo-v1-0-design-tokens-from-figma-into-css-with-property-light-dark-and-color-functions For writing a spec, actually only the first case is relevant. As the second case will turn tokens from multiple files and merge them into the formerly defined format (and may be a product decision). Yet the spec here focusses mostly around the second idea and therefore in my eyes misses the key point. As a result the spec introduces a lot of new terms: Resolver, Context, Set, Modifier, Input, Resolution, Resolution Logic... and then Resolution (again?), 7-8 words. I think it is wise to split this attempt into two parts:
(I personally do see the (2) as optional but I can see people prefer to design in a given context) I will speak about (1) now, as it actually connects to a couple of points in the spec. Constrained Values for TokensHere is where I refer to the research I made for Theemo and implemented it this year. Let's start with some definitions (as to how I will use them). Theme
Spec: The spec only talks about the metadata part and it is only conditionally with the resolver file when multi file approach is used (as much as I understood - what about single file users?). Example (this can be as part of {
"name": "super-theemo",
"file": "dist/super-theemo.css",
"features": [
{
"name": "color-scheme",
"browserFeature": "color-scheme",
"options": [
"light",
"dark"
]
},
{
"name": "density",
"options": [
"compact",
"comfortable",
"spacious"
],
"defaultOption": "comfortable"
}
]
}I know theme is a heavily overloaded term and many connect it to color-scheme, but nobody also attempted how such an entity/asset is called. So I refer to it as theme, likely not needed for the spec, but easier for making this post understandable. Features
Examples are: Color-Scheme, Color-Contrast, Density, Motion Spec: In the spec this is referred to as a combination of Context, Set and Modifier. But the spec talks about how to "fetch" the value for a constrained value. Similar to how I researched it (the implematation had to slightly mutate the format, but the idea was kept). A token can start with a single value and then support multiple features as the theme develops (building great character). A token is never to be constrained by any UI of what features it supports. Example: {
"text": {
"normal": {
"$value": [
{
"value": "{palette.letters.dark}",
"features": {
"color-scheme": "light"
}
},
{
"value": "{palette.letters.light}",
"features": {
"color-scheme": "dark"
}
}
],
"$description": "",
"$type": "color"
}
}
}This is the sample representation I choose for theemo to store constrained values, I used something to make it work. THIS FORMAT SHOULD BE THE POINT OF DISCUSSION. AppliancesHere I list some appliances of constrained values over contextual token sets:
This is why I think a spec for contextual token sets is at best optional, perhaps not needed. At the end a very good decision to postpone and see how tools adapt to a constrained values format. I can imagine a case though where people have contextual token files and want to feed them into style-dictionary (this totally makes sense). ConclusionThat's it. From 7 words: Resolver, Context, Set, Modifier, Input, Resolution, Resolution Logic, down to 1-3 (Feature + Constrained Value + Metadata, depending on how you count). Much less (confusing), more precise, more to the point. Research based. Other use-cases are possible in a second effort. Start with constrained values! |
Beta Was this translation helpful? Give feedback.
-
|
PS. I'm happy to help out and get my hands dirty writing this or jump into a call (I'm free from 22th sept onwards). |
Beta Was this translation helpful? Give feedback.
-
|
Writing comments here as a review the spec:
Overall, I think it's fine. Personally, I'm happy to see a mechanism that allows a person to separate the concept of "light" from the concept of "dark". I think there's room for considering new names for some of the concepts. I'm thinking about the choice/option scheme that has been used for tokens in the past being helpful here: {
"tokens": [
{
"type": "context",
"choice": "theme",
"options": {
"light": ["themes/light.json"],
"dark": ["themes/dark.json"]
},
"default": "light"
}
]
}In this way, the resolve needs to make a choice on which theme to select from the given options. I think this is arguably more understandable than modifier & input, unless there's plans for further enhancements here. Also, in looking at the example, I don't think I would have put {
"contexts": [{
"choice": "theme",
"options": { ... } /* these have { tokens } */
}]
}A larger question I have is how we'd expect to support the concept of something like "Visa, Chinese, dark, critical" in this ecosystem? Each one of these may affect the final value of the tokens used within the UI. It's possible that is outside the scope of this, but still curious if it has been considered. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for input! Just answering a couple questions for now, will put more thought into the other things raised.
Yes! In closed schemas, there’s no need for
Many token setups won’t have all overrides contained in a single file. This allows people to have, say, color overrides separate from typography and spacing. Or they can even re-apply files again if they really need something to “win” in certain contexts. For those that don’t need it, the array can be a single item. But for many folks this is necessary based on their existing token structure. It just allows for fewer restrictions without adding any complexity. |
Beta Was this translation helpful? Give feedback.
-
|
Ah ok, I was under the impression that the As for the array of file paths. Are you saying that when one of these is chosen, it will have the ability to collect several files together? As in, if I want to share typography tokens across light and dark modes, I can declare those tokens similarly between the light and dark arrays? |
Beta Was this translation helpful? Give feedback.
-
|
@ddamato for versioning, we're using a form of calVer instead of semver; we don't have a formal definition of major/minor/point releases, and the bikeshedding it would take to align on that meant it's a lot easier to just use dates for now. If we want to switch to semver at a future date it's a lot easier to go in that direction than to pull an Apple and jump from 18 to 26 😬 |
Beta Was this translation helpful? Give feedback.
-
|
I'm not so sure about the ease of switching. We went from semver to a similar calver-like system in our repo and because the versions now start with 2025, returning to a semver system would cause things like 2027.3.1, which now looks like a mix of calver and semver. I'd think a major reason why you'd consider something like calver is if you had regular releases on a known interval. If the releases are expected to be more sporadic, as is the case often, then semver probably makes sense. Though I do agree the amount of time wasted determining if something was a major or minor is non-zero. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
This is our first-ever Request for Comment (RFC): a possible addition to support Modes & Theming (#210)! We’ll incorporate feedback up until Fri, Sep 19 at which point we’ll close the RFC. Post-closing, we’ll still listen to any feedback as well (but it may or may not affect the final specification).
Summary
The Resolver module is a proposal that allows for different contexts to exist, such as light & dark mode, theming, and other scenarios where you need alternate token values. Up until now, the DTCG specification has left implementing this up to consumers, with no official solution. This would change that.
Links
How to participate
Beta Was this translation helpful? Give feedback.
All reactions