$deprecated property? #118
Comments
kaelig
added
the
Needs Feedback/Review
|
Why not a I can see this being useful to describe a token throughout the entirety of its lifespan (not just during deprecation). Could start with just a few supported values...
crude, partial JSON Schema doc to illustrate my idea... {
"$schema": "http://json-schema.org/draft-07/schema",
"$id": "token",
"type": "object",
"properties": {
"$value": {},
"$type": { "type": "string" },
"$extensions": { "type": "object" },
"$state": {
"type": "string",
"default": "stable",
"enum": [
"experimental",
"stable",
"deprecated"
]
}
},
"required": ["$value"]
} |
|
I like this! But it will only work as long as no two statuses need to be assigned at the same time.
Something can be both deprecated and experimental. |
|
I think having a In our implementation, we have a
Our tooling leverages this along with a For example, a {
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. |
|
For communication in long-running projects, We also use a Re: encoding something like |
I agree. Standardising around a set states will be required as this in turn makes it possible for tools to hook into these. Some of these might be problematic for the standard :
Ideally these states are unambiguous so that it's easy for everyone to agree on what a state means and how it should be applied. |
|
Those are correct observations. Also, Not proposing this be adopted verbatim, sharing as an example 👍 |
|
To me, deprecation seems like a fairly standard part of the software lifecycle. I would suggest a With an object, For example The |
This I do not really follow :) This would just be a vanity alias in this case if the spec only allows A I do agree that an object might be better than a simple flag as this allows for future additions. {
"Button background": {
"$type": "...",
"$value": "...",
"$description": "Bright pink background for buttons.\nThis has been deprecated.\nSee : <some link> for more info."
"$deprecated": {
"$value": true,
"$future-thing": "..."
}
}
}For now I think it would be best to keep this a bit more simple and keep Any extra API will also need corresponding UI in design tools so that people can enter data and will also need to be surfaced by all tools that consume tokens. |
The argument is for The specifics within
A description and a deprecation notice are separate concepts, IMO. Consider For those examples, the deprecation message is separate from the implementation. IMO, a separate deprecation message lends toward a better version control history. |
True. So to summarise we have expanded from a need to set a
|
The reason for One possibility to allow simplicity is for If |
|
Having Having a deprecation message in isolation of the token description also makes sense, but I wonder if using 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, 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 Example{
"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}"
}
}
}
}
Alternatively, you could just isolate transform vs documentation metadata within {
"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": {
"transform": {
// if language supports it, define by reference, not by value
// (Sass) $grey: $gray;
// (JS) const grey = gray;
// etc.
"retainAlias": true
},
"docs": {
// 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}"
}
}
}
}
}
}
|
|
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? {
"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": "[email protected]"
}
},
{
"$state": "created",
"$timestamp": "20220128093348",
"$author": {
"$name": "Dan Donald",
"$email": "[email protected]"
}
}]
}
}
}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 see a connection with this issue : #157 This change log could include changes made by tools. At the same time I wonder if tracking changes should be done externally? Someone can make a service to provide something similar for design tokens. If a change log should be part of the specification I still think it should be separate from the deprecated/state property. A change log should encompass all aspects of a token (including deprecated/state). |
|
Sure, happy to! I guess the issue is that as you can write the proposed format by hand, as well as using any number of tools Git may or may not be a part of the workflow or only have a partial view of the history. I'll split it out and see what people think |
|
Given that there are much better and more mature tools to accomplish changelog / history / audit trails, I'd highly recommend against trying to wedge it into the spec. Additionally, that information provides no useful data for transforming the token itself and only adds bloat to the JSON. |
|
What is the current state of this idea? I do think at least having a Style dictionary currently encourages the use of I think the idea of @CITguy is pretty solid: "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}"
}This at least covers all cases that I have come across. |
I’m actually going through this issue, and a few others, where there’s been demonstrated interest and it’s not too controversial of a topic (not like color and modes/transforms at least) and creating proposals to make final decisions on. I’m working on some minor changes to |
@drwpow any news in this? |
Thanks for the ping. We ended up postponing a few meetings, but are picking back up this week. Will put together a PR for this. What happens when you promise a date 😅 |
|
A proposal has been added here: #255. Would love thoughts / feedback! And yes this is only for the |
|
This has been accepted and merged! Closing 🙂 |
|
Thank you for working on this 🙇 |
When a specific design token should no longer be used the current schema only gives the option to remove it.
This can easily block consumption of future changes until all uses have caught up with the removal.
This is a communication issue.
Design token files will eventually have breaking content changes.
This can be partly handled by using a distribution method that supports some form of versioning.
That would allow consumers to stay on a version they are compatible with until they are ready to update. This is outside the scope of my request.
Having a
$deprecatedfield would allow tools to give warnings and guidance about upcoming changes.{ "Button background": { "$value": "#777777", "$description": "The background color for buttons in their normal state.", "$deprecated": "Button styles have been moved to a separate design tokens file. Import 'buttons.tokens'" } }The text was updated successfully, but these errors were encountered: