Can groups be a property?

[romainmenke]

https://design-tokens.github.io/community-group/format/#groups-versus-composite-tokens https://design-tokens.github.io/community-group/format/#groups

Groups are meaningless for the design tokens themselves and complicate the overal design of the file format.

Can these be a property ($group)?

Some extra bits have been added on top of groups that are purely sugar like inferred types. But token files should be generated by programs and not written by hand. Sugary things should be avoided if they complicate the overal design.

---

The current design is also prone to misuse. For example here : https://github.com/tokencss/tokencss Where groups are used to determine meta data about tokens.

[donnavitan]

Hello @romainmenke,

As a designer, grouping design tokens is very meaningful and can vary from one design system to another, can be organized differently from one design tool to another.

1. Could you further clarify what you mean when stating that groups are meaningless for design tokens?
2. How does it complicate the design of the file format?
3. How would adding a group property per token be more beneficial than grouping a set of tokens? If using a group property, how would you nest or group a group of tokens?

And I'd like to better understand what you mean by sugary things.

[romainmenke]

As a designer, grouping design tokens is very meaningful and can vary from one design system to another, can be organized differently from one design tool to another.

Absolutely agree with this. This issue does not question the value of grouping itself.

---

@donnavitan wrote :

Could you further clarify what you mean when stating that groups are meaningless for design tokens?

This is part of the spec : https://design-tokens.github.io/community-group/format/#groups

Groups are arbitrary and tools SHOULD NOT use them to infer the type or purpose of design tokens.

Groups are meaningless not for designers but for the tokens themselves in the current specification.

---

@donnavitan wrote :

How does it complicate the design of the file format?

A nested file format is more complicated that a flat format.

For example :

{
    "token uno": {
        "$value": "token value 1"
    },
    "token group": {
        "token dos": {
            "$value": "token value 2"
        },
        "nested token group": {
            "token tres": {
                "$value": "token value 3"
            },
            "Token cuatro": {
                "$value": "token value 4"
            }
        }
    }
}

vs.

{
    "token uno": {
        "$value": "token value 1"
    },
    "token dos": {
        "$value": "token value 2",
        "$group": "token group"
    },
    "token tres": {
        "$value": "token value 3",
        "$group": "token group.nested token group"
    },
    "Token cuatro": {
        "$value": "token value 4",
        "$group": "token group.nested token group"
    }
}

---

@donnavitan wrote :

How would adding a group property per token be more beneficial than grouping a set of tokens? If using a group property, how would you nest or group a group of tokens?

Currently a dot separator is used to make grouped values addressable. The same can be used for groups.

---

@donnavitan wrote :

And I'd like to better understand what you mean by sugary things.

https://design-tokens.github.io/community-group/format/#type-0

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.

This is syntax sugar. It only benefits manually writing a tokens file while complicating both generating and consuming a tokens file.

[TravisSpomer]

I think it's unreasonable to assume that tokens files will only be generated or edited by machines. I wouldn't be surprised at all if token files ended up being generated by hand the majority of the time, especially in the first couple of years while the number of spec-compliant token tools is zero or very few.

For a flat list to work, the token name would have to include the full group name, not as a separate property.

{
  "token uno": { "$value": "token value 1" },
  "token group.token dos": { "$value": "token value 2" },
  "token group.nested token group.token tres": { "$value": "token value 3" }
}

Otherwise, you'd have conflicts in every token file that had two tokens with the same name in two different groups, which would be... probably almost every token file. (For example, token uno versus token group.token uno couldn't be specified in your proposed format, right?)

And true, that would be easier to parse, but also considerably more cumbersome to write, and the number of people writing code to parse tokens is likely very low compared to the number of people writing token files, so that seems like a bad tradeoff to me. It also closes off various potential future features like aliasing or extending groups.

[romainmenke]

@TravisSpomer wrote :

I think it's unreasonable to assume that tokens files will only be generated or edited by machines. I wouldn't be surprised at all if token files ended up being generated by hand the majority of the time, especially in the first couple of years while the number of spec-compliant token tools is zero or very few.

https://design-tokens.github.io/community-group/format/#introduction

While many tools now offer APIs to access design tokens or the ability to export design tokens as a file, these are all tool-specific. The burden is therefore on design system teams to create and maintain their own, bespoke "glue" code or workflows. Furthermore, if teams want to migrate to different tools, they will need to update those integrations.

This specification aims to facilitate better interoperability between tools and thus lower the work design system teams need to do to integrate them by defining a standard file format for expressing design token data.

This specification targets tools which is why it makes sense to me to focus on that. This will ease adoption and reduce the time persons have to manually interact with token files.

Giving up short term convenience for long term simplicity.

---

@TravisSpomer wrote :

For a flat list to work, the token name would have to include the full group name, not as a separate property.

Correct. Forget about that bit. So it can actually be simplified further like your example. No $group property is needed to express groups.

But if hierarchy is encoded in the name it would make much more sense to use a / as a separator.

Working with paths is well supported in any programming language. URL has a well defined spec and encoding/decoding path components is also supported.

{
    "token%20uno": {
        "$value": "token value 1"
    },
    "token%20group/token%20dos": {
        "$value": "token value 2"
    },
    "token%20group/nested%20token%20group/token%2Ftres": {
        "$value": "token value 3"
    }
}

---

@TravisSpomer wrote :

It also closes off various potential future features like aliasing or extending groups.

This is perfectly possible without a nested structure :

{
    "token uno": {
        "$value": "token value 1"
    },
    "token group.token dos": {
        "$value": "token value 2"
    },
    "token group.nested token group.token tres": {
        "$value": "token value 3"
    },
    "token group.nested token group b": {
        "$type": "group",
        "$extends": "token group.nested token group"
    },
    "token group.nested token group b.token cuatro": {
        "$value": "token value 4"
    }
}

---

@TravisSpomer wrote :

And true, that would be easier to parse, but also considerably more cumbersome to write

If writing the group and name as a single string for each token is considerably more cumbersome the entire way to address tokens should be revisited.

see : https://github.com/design-tokens/community-group/issues/119

Design tokens will be referenced in code much more than they will be written in token files. And the issue is enlarged in programming contexts as the name/id format is not strict enough.

[romainmenke]

Although there is some complexity with the current approach to grouping it does not make implementations harder by a significant degree and should not harm adoption.

The benefits of having the parallel between grouping in design tools and grouping in JSON is worth it.