From 5376d1457606efe4b0ba290b86f624fbddf56730 Mon Sep 17 00:00:00 2001 From: Drew Powers Date: Thu, 24 Oct 2024 13:51:41 -0600 Subject: [PATCH 1/3] 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

The extensions section is not limited to vendors. All token users can add additional data in this section for their own purposes.

+ +### 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 + + + +| 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 +### 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 + + + +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 From c132b494ecf85bad42aebf508e9d4a47e06eca33 Mon Sep 17 00:00:00 2001 From: Drew Powers Date: Thu, 24 Oct 2024 17:01:23 -0600 Subject: [PATCH 2/3] PR feedback --- technical-reports/format/design-token.md | 2 +- technical-reports/format/groups.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/technical-reports/format/design-token.md b/technical-reports/format/design-token.md index cc0a3a9..0f9672e 100644 --- a/technical-reports/format/design-token.md +++ b/technical-reports/format/design-token.md @@ -181,7 +181,7 @@ Tool vendors are encouraged to publicly share specifications of their extension ### 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: +The optional **`$deprecated`** property is a boolean or string where tools 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 diff --git a/technical-reports/format/groups.md b/technical-reports/format/groups.md index 4921219..58010c0 100644 --- a/technical-reports/format/groups.md +++ b/technical-reports/format/groups.md @@ -208,7 +208,7 @@ In this example, the "brand" group has 2 extensions: `org.example.tool-a` and `o ### 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: +The optional **`$deprecated`** property is a boolean or string where tools 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 From b60ae035ea21b0638d5bcf274c53600ba3b960ff Mon Sep 17 00:00:00 2001 From: Drew Powers Date: Tue, 26 Nov 2024 23:27:26 -0700 Subject: [PATCH 3/3] Remove aliases from examples, improve wording --- technical-reports/format/design-token.md | 28 ++++++++++++++++++++++-- technical-reports/format/groups.md | 8 ++----- 2 files changed, 28 insertions(+), 8 deletions(-) diff --git a/technical-reports/format/design-token.md b/technical-reports/format/design-token.md index 0f9672e..9cad3fb 100644 --- a/technical-reports/format/design-token.md +++ b/technical-reports/format/design-token.md @@ -181,7 +181,7 @@ Tool vendors are encouraged to publicly share specifications of their extension ### Deprecated -The optional **`$deprecated`** property is a boolean or string where tools MAY specify deprecated tokens. A token MAY be marked deprecated in any of the following scenarios: +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 @@ -199,7 +199,7 @@ The optional **`$deprecated`** property is a boolean or string where tools MAY s "Button focus": { "$value": "#70c0ff", "$type": "color", - "$deprecated": "Please use {button.activeBorder} instead." + "$deprecated": "Please use the border style for active buttons instead." } } ``` @@ -211,3 +211,27 @@ The optional **`$deprecated`** property is a boolean or string where tools MAY s | `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: + + + +Or + + diff --git a/technical-reports/format/groups.md b/technical-reports/format/groups.md index 58010c0..3765266 100644 --- a/technical-reports/format/groups.md +++ b/technical-reports/format/groups.md @@ -208,18 +208,14 @@ In this example, the "brand" group has 2 extensions: `org.example.tool-a` and `o ### Deprecated -The optional **`$deprecated`** property is a boolean or string where tools 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 +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.