From 9f24807ffad0515156a4a3bf02299c1db2f17217 Mon Sep 17 00:00:00 2001
From: Drew Powers <drew@pow.rs>
Date: Thu, 24 Oct 2024 13:51:41 -0600
Subject: [PATCH] Add $deprecated proposal

---
 technical-reports/format/design-token.md | 33 ++++++++++++++++++++++++
 technical-reports/format/groups.md       | 30 +++++++++++++++++++++
 2 files changed, 63 insertions(+)

diff --git a/technical-reports/format/design-token.md b/technical-reports/format/design-token.md
index c9eb376..cc0a3a9 100644
--- a/technical-reports/format/design-token.md
+++ b/technical-reports/format/design-token.md
@@ -178,3 +178,36 @@ 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 optional **`$deprecated`** property is a boolean or string where tooks MAY specify deprecated tokens. A token MAY be marked deprecated in any of the following scenarios:
+
+- 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 {button.activeBorder} 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). |
diff --git a/technical-reports/format/groups.md b/technical-reports/format/groups.md
index 1098eb3..4921219 100644
--- a/technical-reports/format/groups.md
+++ b/technical-reports/format/groups.md
@@ -206,6 +206,36 @@ In this example, the "brand" group has 2 extensions: `org.example.tool-a` and `o
 
 </aside>
 
+### Deprecated
+
+The optional **`$deprecated`** property is a boolean or string where tooks MAY specify all tokens within the group are deprecated. A token MAY be marked deprecated in any of the following scenarios:
+
+- 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": {
+    "$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.        |
+| `false`  | This token is NOT deprecated (may override group defaults). |
+
 ## Use-cases
 
 ### File authoring & organization