From af7e799d7317ef6fa0264c3b927a6df2da1ba157 Mon Sep 17 00:00:00 2001
From: Drew Powers <drew@pow.rs>
Date: Tue, 26 Nov 2024 23:31:19 -0700
Subject: [PATCH] Proposal: add $deprecated property (#255)

* Add $deprecated proposal

* PR feedback

* Remove aliases from examples, improve wording
---
 technical-reports/format/design-token.md | 57 ++++++++++++++++++++++++
 technical-reports/format/groups.md       | 26 +++++++++++
 2 files changed, 83 insertions(+)

diff --git a/technical-reports/format/design-token.md b/technical-reports/format/design-token.md
index c9eb376..9cad3fb 100644
--- a/technical-reports/format/design-token.md
+++ b/technical-reports/format/design-token.md
@@ -178,3 +178,60 @@ Tool vendors are encouraged to publicly share specifications of their extension
 <p class="ednote" title="Extensions section">
   The extensions section is not limited to vendors. All token users can add additional data in this section for their own purposes.
 </p>
+
+### Deprecated
+
+The **`$deprecated`** property MAY be used to mark a token as deprecated, and optionally explain the reason. Reasons to deprecate tokens include but are not limited to the following:
+
+- A future update to the design system will remove this token
+- Removing the token now may break existing support
+- This token is discouraged from future use
+
+<aside class="example">
+
+```json
+{
+  "Button background": {
+    "$value": "#777777",
+    "$type": "color",
+    "$deprecated": true
+  },
+  "Button focus": {
+    "$value": "#70c0ff",
+    "$type": "color",
+    "$deprecated": "Please use the border style for active buttons instead."
+  }
+}
+```
+
+</aside>
+
+| Value    | Explanation                                                 |
+| :------- | :---------------------------------------------------------- |
+| `true`   | This token is deprecated (no explanation provided).         |
+| `String` | This token is deprecated AND this is an explanation.        |
+| `false`  | This token is NOT deprecated (may override group defaults). |
+
+Tool makers MAY augment the string when it contains aliases such as the one given as an example. A tool could potentially resolve the token, and link to docs, code, or render a visual representation of it and link to the new token inside a UI. For example, “Please use {button.activeBorder} instead“ could be output in JS as:
+
+<aside class="example">
+
+```js
+/**
+ * @deprecated Please use {@link file://./my-tokens.js:85 button.activeBorder} instead.
+ */
+```
+
+</aside>
+
+Or
+
+<aside class="example">
+
+```js
+/**
+ * @deprecated Please use {@link https://docs.ds/tokens/#button-activeborder button.activeBorder} instead.
+ */
+```
+
+</aside>
diff --git a/technical-reports/format/groups.md b/technical-reports/format/groups.md
index 1098eb3..3765266 100644
--- a/technical-reports/format/groups.md
+++ b/technical-reports/format/groups.md
@@ -206,6 +206,32 @@ In this example, the "brand" group has 2 extensions: `org.example.tool-a` and `o
 
 </aside>
 
+### Deprecated
+
+The **`$deprecated`** property MAY be used to mark a group as deprecated, which extends to all child tokens within. This property may also optionally give a reason.
+
+<aside class="example">
+
+```json
+{
+  "Button": {
+    "$deprecated": "Please use tokens in the Action group 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.        |
+| `false`  | This token is NOT deprecated (may override group defaults). |
+
 ## Use-cases
 
 ### File authoring & organization