Proposal: add $deprecated property

[drwpow]

Summary

This adds a new $deprecated property for both tokens and groups as suggested by @romainmenke.

Reasoning

This PR basically accepts #118 as-proposed (the original proposal), while taking into account feedback from followup comments.

Pros

• This mirrors prior art like JSDoc deprecation that is well-known and well-used
• Style dictionary also has this concept and it makes sense to codify in the spec
• This seemed to have fairly-universal support (only disagreements were minor syntax differences, but that also spawned a separate proposal that can be evaluated independently)

Cons

• Expanding $deprecated in the future would be a breaking change
• What constitutes “deprecation” is a little ambiguous in the spec as-written. But the hope is that it’s no more ambiguous than using this exact term elsewhere.
• What “deprecation” means is up to tools to decide (e.g. whether or not to generate output from those tokens, and/or throw warnings/errors)

Alternatives

• Adding a pair property (e.g. $deprecated / $deprecatedMessage) isn’t a design pattern that currently exists in the spec. Pair properties can also be antipatterns as they introduce validation complexity (e.g. what if $deprecatedMessage is set but $deprecated isn’t—is that valid or invalid? and if valid, what behavior is inferred?)
• The object syntax (e.g. $deprecated.deprecated / $deprecated.message) wasn’t proposed here because it adds unnecessary boilerplate.
• A more complex status object would be a separate proposal because that encroaches on opinionated versioning (and versioning won’t map 1:1 to existing tokens)
  • This proposal assumes that any implementation of status/versioning won’t conflict with $deprecated. Or in areas where they potentially overlap, will be complementary rather than conflicting.
  • In other words, acceptance of this does NOT mean refusal of the Status Object proposal

Notes

• This assumes aliases may be deprecated too (even if the tokens they point to don’t). Should this be outlined explicitly?
• It is the author’s opinion that deprecation is not directly related to versioning. Versioning is a more complex opinion on what constitutes “breaking changes” from non-, e.g. semver. Though versioning may include deprecation and/or removal of tokens, it’s so much more. Conversely, the act of deprecation is common enough it affects every design system, even those that may not have defined versioning strategies. So whether or not this spec defines an opinionated versioning strategy, shouldn’t affect this proposal.

[netlify]

✅ Deploy Preview for dtcg-tr ready!

Name	Link
🔨 Latest commit	b60ae03
🔍 Latest deploy log	https://app.netlify.com/sites/dtcg-tr/deploys/6746bc471b5cbe0008518c61
😎 Deploy Preview	https://deploy-preview-255--dtcg-tr.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[drwpow]

cc @c1rrus any nitpicking of language here would be greatly appreciated 🙏. Happy to rephrase this to match the existing language (or if you wanted to do a pass on it that would be fine, too!)

[romainmenke]

Thank you. LGTM 👍

[c1rrus]

Spotted a couple of teeny typos. But otherwise this looks good. Happy to approve once they get fixed.

[c1rrus]

Nice one. Thanks for doing this @drwpow!

[drwpow]

Thanks! Will give other editors a chance to review and leave feedback over the next week or 2. If there’s no objection, we’ll merge!

But also, based on the other recent proposals, generally the editors express the same opinions found in the comments, so the fact it’s being proposed in the first place is usually positive 🙂

[nesquarx]

To confirm, there is neither a necessity nor a spec-defined way to confirm or extract an alternate token suggestion inside the deprecated tag, toolmakers can make their own assumptions on if and how to programmatically determine it?

…

On Fri, 1 Nov 2024 at 01:31, Kaelig Deloumeau-Prigent < ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In technical-reports/format/groups.md <#255 (comment)> : > + "Button": { + "$deprecated": "Please use {action.*} tokens instead.", + "Foreground": { "$value": "#202020", "$type": "color" }, + "Background": { "$value": "#ffffff", "$type": "color" } + } +} +``` + +</aside> + +In the context of a group, adding `$deprecated` will apply to all tokens within that group, unless a token explicitly sets a value of `false`. Any value provided by a token will override the group default. + +| Value | Explanation | +| :------- | :---------------------------------------------------------- | +| `true` | This token is deprecated (no explanation provided). | +| `String` | This token is deprecated AND this is an explanation. | Perhaps it would be useful to mention that tool makers MAY augment the string when it contains aliases such as the one given as an example: Please use {button.activeBorder} instead — Reply to this email directly, view it on GitHub <#255 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEKS36AFBRW2TZODLTREIVLZ6KEBLAVCNFSM6AAAAABQR27HUKVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDIMBYHE3TEMBVHE> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[lukasoppermann]

@drwpow good to merge?

[drwpow]

@drwpow good to merge?

Almost! We had been waiting to see if one group had feedback. Will ping them again and if not, will merge!

[drwpow]

To confirm, there is neither a necessity nor a spec-defined way to confirm or extract an alternate token suggestion inside the deprecated tag, toolmakers can make their own assumptions on if and how to programmatically determine it?

Correct. Updated the wording per @kaelig’s suggestion to describe this a bit more. By default we don’t have aliases in the examples anymore outside the section that describes “it’s up to tools to determine how they do/don’t handle parsing the $deprecated string.

[drwpow]

We’ve waited for additional parties to give input / feedback but haven’t gotten any pushback or corrections. Merging!