Proposal: add $deprecated property

drwpow commented 4 weeks ago

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[bot] commented 4 weeks ago

Deploy Preview for dtcg-tr ready!

Name	Link
Latest commit	3fd459b78f7826ae01893226d3ae6dd26773b309
Latest deploy log	https://app.netlify.com/sites/dtcg-tr/deploys/671ad1c8b88c2e0008764d36
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 commented 4 weeks ago

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 commented 2 weeks ago

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 https://github.com/design-tokens/community-group/pull/255#discussion_r1825099010 :

"Button": {

"$deprecated": "Please use {action.*} tokens instead.",

"Foreground": { "$value": "#202020", "$type": "color" },

"Background": { "$value": "#ffffff", "$type": "color" }

} +} +```

+

+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 https://github.com/design-tokens/community-group/pull/255#pullrequestreview-2408972059, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEKS36AFBRW2TZODLTREIVLZ6KEBLAVCNFSM6AAAAABQR27HUKVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDIMBYHE3TEMBVHE . You are receiving this because you are subscribed to this thread.Message ID: @.***>

lukasoppermann commented 1 day ago

@drwpow good to merge?

drwpow commented 1 day ago

@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!

design-tokens / community-group