[community-group] Status object: simplified audit/decision history (#161)

hereinthehive has just created a new issue for https://github.com/design-tokens/community-group:

== Status object: simplified audit/decision history ==
This is something I'd been thinking about before joining. A state/status object feels extensible and more descriptive. I'd also argue that the deleted state is valid as you might want to capture _why_ a value was deleted.

With concepts like this, perhaps we're touching on whether tokens should have their own version of an ADR so there's an audit/history around choices/decisions made?

```tsx
{
  "colors": {
    "action": {
      "$value": "#ff0000",
      "$type": "color",
      "$status": [{
        "$state": "deprecated",
        "$description": "We'll be replacing this soon, please check out how the replacement value works for you",
        "$value": "#00ff00",
        "$timestamp": "20220707111111",
        "$note": "We changed the color based on user research",
        "$toolstamp": "Figma",
        "$author": {
          "$name": "Dan Donald",
          "$email": "dan@zeroheight.com"
        }
      },
      {
        "$state": "created",
        "$timestamp": "20220128093348",
        "$author": {
          "$name": "Dan Donald",
          "$email": "dan@zeroheight.com"
        }
      }]
    }
  }
}
```
The rationale here is that as tokens when used to their full potential are a real business asset, it's useful to know when and why a decision was made. Seeing a simple history allows us to have context for a value but also allow any given tool to write to it and have that shared understanding in a way we haven't to date. Arguably the notion of 'toolstamp' is a naive way of suggesting there should be a reference to what tool was used as part of the audit.

Really curious to hear your thoughts!

> I think having a `$state` property will be really beneficial to the spec as well.
> 
> In our implementation, we have a `state` property that can take one of the following states:
> 
> `Experimental → Active → Deprecated → Sunset → Deleted`
> 
> * **Experimental**: For introducing tokens for internal validation and trail purposes
> * **Active**: This token is currently actively being used. Tooling will help to ensure tokens are used.
> * **Deprecated**: This token has been flagged for future deletion and should no longer be used.
> * **Sunset**: This token has been marked for upcoming deletion and strictly should not be used.
> * **Deleted (hard)**: This token has been fully removed from the tokens API
> 
> Our tooling leverages this along with a `replacement` property to perform automatic or controlled migrations via tooling such as `eslint`, `stylelint`, `figma` etc.
> 
> For example, a `deprecated` token with a `replacement` can be warned against and autofixed by eslint. A `sunset` token will produce an error and can be autofixed and so on.
> 
> ```tsx
> {
>   link: {
>     pressed: {
>       attributes: {
>         group: 'color',
>         state: 'deleted',
>         replacement: 'color.link.pressed',
>         description: 'Use for links in a pressed state',
>       },
>   },
> }
> ```
> 
> We've had to build these tools ourselves, but the great thing about having an industry-wide spec like this one is that both community and proprietary tooling can leverage this concept to make token lifecycles a standard and consistent behaviour. Particularly helpful for the maintenance and evolution of tokens over time.

_Originally posted by @hereinthehive in https://github.com/design-tokens/community-group/issues/118#issuecomment-1196516422_

Please view or discuss this issue at https://github.com/design-tokens/community-group/issues/161 using your GitHub account


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

Received on Wednesday, 27 July 2022 10:18:48 UTC