Comments (10)
I'll mention that I appreciate the $
prefix to quickly identify the values visually, as in reading the file manually. I think all of the points above make sense for systems identifying the non-prefixed key. However for folks authoring these files by hand, the $
helps filter what needs to be changed faster while scanning the file with your eyes.
from community-group.
There shouldn't be a set of reserved words anyway, because you shouldn't ever mix user-defined keys with schema-defined keys. And you should only need key/value objects with user-defined keys in specific places, like a group of tokens.
from community-group.
I understand the goals you have for using the prefix, but the prefix really isn't necessary to reach them:
- Consistency Across the Specification: If you drop the
$
prefix, you'll have the consistency of... not using a prefix. I don't think adding one or not creates consistency. The only inconsistency would be if you used prefixes in some places and not in other. To be clear about what I'm proposing: it's that you don't use prefixes anywhere because they're unnecessary. - Collision Prevention: The standard way to avoid collisions with user-defined keys in JSON schemas is to define a separate object that's entirely user-defined - a general key/value object. As the schema evolves, it evolves within the objects that hold the schema-defined keys. The example I showed above has this quality: there is no object with both schema-defined and user-defined keys.
- *Clear Token vs. Nested Group Differentiation: I would argue that the current schema which has some keys belong to the schema and some to the user-defined data is less clear, and having a nested key/value object for nested tokens would be more clear.
I think the style of schema I'm advocating here is by far the more common and plain way to design a JSON schema. Again, I've never seen a schema like this one where all the keys are prefixed and I immediately found it exceedingly odd. I was thinking there had to be an exceptional reason for it, but the reason you give are all not actually problems with the more common JSON schema design.
from community-group.
Your observations on the Design Token Schema standard are insightful. Drawing from the W3C Design Tokens standard you provided:
-
Consistency Across the Specification: One of the key takeaways from the spec is the drive for consistency. The
$
prefix consistently differentiates official properties from user-defined token names. This can help improve clarity and comprehension, especially when parsing these tokens. -
Collision Prevention: The
$
prefix is a neat solution to avoid potential naming clashes. It ensures that as the spec evolves, new properties can be introduced without running into naming conflicts with user-defined token names. -
Clear Token vs. Nested Group Differentiation: The spec's use of the
$
prefix also simplifies the distinction between tokens and nested groups. This clear demarcation aids in reducing the complexity of parsing logic.
However, I do resonate with your points about the inherent complexity introduced by the $
prefix. Striking the right balance between a robust standard and user-friendliness is challenging. Your feedback highlights some areas where the spec might improve to be more intuitive.
Thanks for sparking this conversation! It's discussions like these that help the community grow and refine its understanding.
from community-group.
I can agree with @justinfagnani
- There shouldn't be any case like a group with the name
value
. In my view, it's a wrong JSON file. I mean it's also possible if someone will call a group$value
.
{
"value": {
"description": "This is an example of a group containing a nested group",
"tokens": {
"subgroup_of_tokens": {
"token_1_name": {
"type": "color",
"value": "#aabbcc"
},
"token_2_name": {
"type": "color",
"value": "#ddeeff"
}
}
}
}
}
- even then, there shouldn't be any collisions because each
token
object contains atype
property, so I can check ifvalue.type
exists.
It's good to add $
to each declared property name, in theory. But it would be helpful to see why it's needed on real examples.
from community-group.
@ddamato wouldn't this be true of any JSON file format? Why don't they all use prefixes?
from community-group.
Maybe because they aren't often authored by hand? Hard to speak on behalf of others. Like I said, I think your points are otherwise solid.
from community-group.
I've always kind of assumed that "looks like existing popular token JSON formats" was an unspoken goal of this format. This is how Amazon's Style Dictionary and the Tokens Studio plugin for Figma do things (or at least did last time I looked), so that's what we started with. A reserved prefix character $
seems a lot better to me than having a random set of words like value
be reserved (and not being able to extend that reserved list in the future), and for quick hand-editing, this format is pretty decent. The alternative of having every other node be tokens
would be pretty obnoxious to read and type, but for sure it would make it a lot easier to code for.
(To clarify, that's my response to "why is this file format so weird." I would have personally preferred something like a tokens
property myself too, but it feels way too late for that and not in line with the goals.)
from community-group.
I saw a few arguments pro "hand-editing" or "manual" editing/searching.
But in my view, people don't search by the $value
word (by a generic property name). If in a JSON I need to change the button-secondary-background
value, I'll search button-secondary-background
and then I'll look for a value
property.
from community-group.
I saw a few arguments pro "hand-editing" or "manual" editing/searching. But in my view, people don't search by the
$value
word (by a generic property name). If in a JSON I need to change thebutton-secondary-background
value, I'll searchbutton-secondary-background
and then I'll look for avalue
property.
That's true, perhaps I'm thinking in terms of the file being overwhelming in some instances. Where if someone new needed to visit this, I could tell them: you don't need to edit anything except for entries that begin with $
. Sure, they'll look for button-secondary-background
but that may have additional unstructured data in there. I think the $
does a good job identifying what's important. After all, we're just trying to overload the button-secondary-background: #0000ff
assignment with more data.
from community-group.
Related Issues (20)
- Provide "outline" token category HOT 4
- Consider using type: "$alias" for explicity
- Define how far design tokens are expected to be interoperable. HOT 1
- Remove REM/EM from specification? HOT 25
- Error in Font Weight example in spec?
- Standardizing the Handoff - Conceptual HOT 10
- Extensible Types HOT 2
- grid type HOT 6
- Specification / recommendation for custom types HOT 4
- Token Operations
- [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 8
- Custom Types / Interpritations
- 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 4
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.