Define how to handle different versions of the specification

[romainmenke]

This specification should assume that there is a large ecosystem of tools and a large body of static token files.

Tools can be well maintained or not and can be up to date with the latest specification or they might not be.

A single organisation using design tokens might depend on dozens of tools all which will can be in different states.

Users might not always be aware of all the other tools used in an organisation.
Users might not be aware of the exact state of all the tools.
Users will not have the ability to influence the tools in use and their state.

Knowing what is supported, what will work from A to Z will be non-trivial in a relatively large org once the specification has been through a few updates.

At the moment I could not find anything specific about this in the current specification.

[romainmenke]

Token files can also be kept static for years after initial creation with tool X.
At some point someone might request an update and the file might be outdated and tool X might no longer exist.

Other comparable tools might only support the latest version of the specification.

Should old files like these be expected to work in up to date tools or not at all?

[lauthieb]

@romainmenke, good point 👍

It could be nice to have a kind of manifest.json as we can see in several tools like Figma. (example: https://github.com/six7/figma-tokens/blob/main/manifest.json with "api": "1.0.0") that specifies which Design Tokens specification version this tool/plugin/app is currently following.

[TravisSpomer]

For identifying which version of the spec a file is following, the top-level $schema property could be useful—there's a short discussion on that topic over in #107.

[lauthieb]

@TravisSpomer oh yes, absolutely 🙌

[romainmenke]

It could be nice to have a kind of manifest.json as we can see in several tools like Figma.

For identifying which version of the spec a file is following, the top-level $schema property could be useful—there's a short discussion on that topic over in #107.

This helps for a single person with a single file and a single tool.
Then you simple open it and the tool can display a warning or the person can compare the versions.

It is however not really the point of my question here :)

Either the specification embraces backwards/forwards compatibility principles or it doesn't.
This requires careful thought with each part of the specification.

CSS for examples has very nice compatibility features:

• You can open a very modern CSS file in IE8 and IE8 won't crash. It will even be able to handle a lot of the contents.
• A CSS file created for IE8 will also work just fine in latest Chrome today.

But the downside is that mistakes in the specification are there forever.
So you can't just wave concerns away with "we will fix it in a next version of the specification"

Compared to the web design tokens will also have the downside of being mostly private files.
You can not scrape 10 million sites and analyse them with Big Query to check if a spec change would be breaking.

Defining upfront how the spec will evolve is important because it will have such a big impact on the ecosystem around the spec.

[danosek]

How do we define upfront how the spec will evolve? In my opinion being in IT for more than a decade, maintaining absolute backwards compatibility is hard. I would aim for "loose" backwards compatibility as long as possible. When a reason for new major spec is needed, let's

1. Declare "version 3.0 is not compatible with 2.8 and older"
2. Show the benefits
3. Document the changes so anyone can reflect them in their tools
4. (Nice-to-have) Publish a translation tool for .tokens.json files so everyone could update them

[romainmenke]

@danosek I am assuming that everyone knows or can research how to do breaking changes, that is not really the point here :)

Maintaining absolute backwards compat is indeed hard, but not impossible.

More important however is declaring the intent.
Does this community group and the spec have the ambition of strong backwards/forwards compat?