Re: [community-group] $deprecated property? (#118)

Having `$deprecated` be an object makes sense, but I'd argue that a `$value` prop seems both redundant and conflicts with the definition of a Token.  If `$deprecated` is _present_, it's assumed to be truthy, so there's no need for a `$value` that would always be set to `true`.  Tokens are defined as JSON objects containing a `$value` property, so it'd be confusing if seen within deprecation metadata.

Having a deprecation message in isolation of the token description also makes sense, but I wonder if using `$description` would overload the term.  I'd be more inclined to use `$message`, but this is just my personal opinion.

Lastly, I agree that there should be some degree of flexibility in allowing additional metadata for various use cases (e.g., documenting a potential replacement).  However, `$extensions` within `$deprecated` seems overloaded.  The way I interpreted the spec in regards to extension metadata seems like it's focused more on providing information on how to transform a token _value_, rather than how to document token _metadata_.  `$deprecated` provides _documentation_ metadata, not _transformation_ metadata (regardless of its presence, it won't affect the transformed value of a token).  

If the problem is the need to isolate transformation metadata (i.e., extensions) from documentation metadata, why not be explicit about it and have a `$docs` or `$info` Token property as a sibling to `$extensions`?

## Example

```javascript
{
  "gray": {
    "$value": "#808080",
    "$description": "Neutral 50% Gray"
  },
  "grey": {
    "$value": "{gray}",
    "$description": "An optional description of the token, 'grey'.",

    // Transformation metadata (free-form props)
    // This data is used specifically to configure how to transform a token's value.
    "$extensions": {
      "com.foo.bar": {
        // if language supports it, define by reference, not by value
        //  (Sass) $grey: $gray;
        //  (JS) const grey = gray;
        //  etc.
        "retainAlias": true
      }
    },

    // Documentation metadata (free-form props)
    // This data has no affect on transformed value.
    "$info": {
      // Might be preferred, to keep all docs-specific data organized within a single object.
      // Overrides #/grey/$description
      "description": "Optional description of token 'grey'.",

      /* Deprecation Examples */
      // FORMAT 1: boolean
      // (Answers nothing other than "Is it deprecated?")
      "deprecated": true,
      // FORMAT 2: string
      // (Extends format 1, by providing a human-readable message about the deprecation)
      "deprecated": "'grey' has been deprecated.",
      // FORMAT 3: object
      // (Further extends format 2 by providing a "next of kin" replacement.)
      "deprecated": {
        "message": "'grey' has been deprecated.",
        // An alias is necessary in order to document the resolved, token name based on the transformation language.
        "replacement": "{gray}"
      }
    }
  }
}
```

* You might argue that properties of `#/grey/$info` could just be properties of `#/grey/$extensions/com.foo.bar`, but at least this format clearly separates transformation vs documentation metadata.


-- 
GitHub Notification of comment by CITguy
Please view or discuss this issue at https://github.com/design-tokens/community-group/issues/118#issuecomment-1185933635 using your GitHub account


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

Received on Friday, 15 July 2022 21:00:49 UTC