Style-dictionary: Discussion: Deprecating Tokens

[dbanksdesign]

Would it be useful to have support for a 'deprecated' flag on tokens? I'm thinking we could support this in 2 ways:

1. If you reference a deprecated token, style dictionary will either fail or show a warning in the console depending on the log level.
2. If the format language supports it, add whatever deprecated annotation to that format so users of the output files can see warnings/errors in their code environments.

Thoughts @didoo, @shaunbent?

[didoo]

In general, I would prefer to add it as an example in the documentation/examples than add it as a feature. My thinking is: if the tool can already do something without too much effort, don't add complexity to the tool just for the sake of abstracting it. In other words: do we need really need it as a feature of SD, or can be "just" another example to add to the documentation?
Here @davixyz suggested looking at https://github.com/zeit/next.js/tree/canary/examples for inspiration, and since then that's been my beacon: imagine having so many examples, that cover almost every case, while keeping the actual code as lean and simple as possible (avoiding feature bloat, and reducing the things that need to be maintained, refactored, etc).

That said, a couple of things that I'm not sure:

• why _"style dictionary will either fail or show a warning in the console depending on the log level"_? Why fail? A value can be deprecated, but not yet replaced; also, imagine having a deprecated token, referring to another "alias" deprecated token: in that case you still need the second token, you're not ready yet to replace it. So you should add an option in the config to say if it should fail or just warn?
• _"users of the output files can see warnings/errors in their code environments"_: what do you have in mind? I can imagine adding comments in the output files, when a token is deprecated, but how to trigger errors/warnings in the consumers? I mean, in a "standard" way?

[shaunbent]

After thinking about this some more I think I am inclined to agree with @didoo that I am not sure if we need to specifically implement anything here. I think suitable documentation/examples would be good enough. I have found myself recently digging around in the advanced examples a lot for inspiration.

style dictionary will either fail or show a warning in the console depending on the log level

I am not sure what values console warnings would provide here, as Cristiano suggests deprecated values are valid things. In my use case the only people who would see the warnings would be the maintainers of our tokens library (i.e. Me) as we package up the output and distribute that.

users of the output files can see warnings/errors in their code environments

This one I really unclear about. I know this should be possible for mobile platforms but I am not sure how we'd go about this for things like Sass/LESS where the values are essentially a flat list of key/value pairs.

[dbanksdesign]

Thank you @didoo and @shaunbent for your thoughts. It sounds like deprecating tokens is not something that should be handled in style dictionary itself. Failing the build is a bit overkill, because as you pointed out a deprecated token is still valid. I dug into 'deprecated' flags a bit more and you are right there aren't many standard deprecation flags in languages, most notably web ones like JS, CSS, Sass, LESS.

I like Cristiano's suggestion of just having an example codebase that shows how you could 'deprecate' tokens is great. Should we close this issue?

[didoo]

@dbanksdesign @shaunbent I have made a PR (#256) with an advanced example that shows how to do tokens deprecation. If you can think of other ways, let me know and I'll add them to the example.

[chazzmoney]

Since the discussion is now mostly finished, I'll drop my 2 cents and muddy the waters.

We could add in a deprecation note in comments that we insert into the files we generate.

Deprecating tokens seems both inevitable and a bad plan. Half of the point of SD is to make it easy to change styles without changing code. Maybe we should talk about how we enable folks to manage tokens completely within SD so that "deprecation" happens within this zone and doesn't get passed outside of it?

[didoo]

@chazzmoney good point. let me think about it. I'll get back to you ASAP

[nickwynja]

We've started to explore handling deprecations too. In this case, we haven't done anything other than mention it in the token file. FWIW, @clepore and I tried to follow the existing comment and attributes conventions in this case:

https://github.com/infor-design/design-system/blob/faa87914b82ec12193598ea03055c347e00430fe/design-tokens/theme-soho/theme.json#L59-L67

[chazzmoney]

Just want to check back in with folks.

We have two quite similar solutions, #256 and the one by @nickwynja

I can merge #256, or we can modify it to match Nick's, or we could spend some time discussing the deeper issues around supporting token management. Whatever we do, Id suggest we keep moving on this and get it to resolution. Thoughts?

[clepore]

My personal take is that #256 is a better "baked in" option with output for the deprecations. @nickwynja and I utilized the attributes and were going to do something similar in our own code.

My vote is to go ahead and merge #256 if there are no other objections 👍. We'll definitely convert to it when we can.

[chazzmoney]

Fixed in #256