[community-group] Pull Request: Proposal: add $deprecated property

drwpow has just submitted a new pull request for https://github.com/design-tokens/community-group:

== Proposal: add $deprecated property ==
## Summary

This adds a new `$deprecated` property for both tokens and groups [as suggested by @romainmenke](https://github.com/design-tokens/community-group/issues/118).

## 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](https://jsdoc.app/tags-deprecated) that is well-known and well-used
- Style dictionary also [has this concept](https://github.com/design-tokens/community-group/issues/118#issuecomment-2277926212) 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](https://github.com/design-tokens/community-group/issues/161) 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](https://jsdoc.app/tags-deprecated).
- 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, and it also introduces validation complexity considering all the permutations of all values together and which are valid or invalid
- The object syntax (e.g. `$deprecated.deprecated` / `$deprecated.message`) wasn’t proposed here because it adds more boilerplate for simpler usecases.
- A more complex [status object](https://github.com/design-tokens/community-group/issues/161) 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](https://semver.org/). 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.

See https://github.com/design-tokens/community-group/pull/255


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Thursday, 24 October 2024 20:07:17 UTC