{
"$type": "site.standard.document",
"content": {
"$type": "site.standard.content.markdown",
"text": "The design systems community was buzzing a few days ago with the announcement of version 2 of the Salesforce Lightning Design System (SLDS). [I shared the link to the new documentation on LinkedIn](https://www.linkedin.com/posts/fauxserious_lightning-design-system-2-activity-7298413367847780352-c46N) and the engagement has been significant.\n\nAs someone who has visited dozens of design system documentation sites, there’s certain things I tend to look for when perusing the content. One of those things is how the team handles design tokens. Design tokens are a fundamental feature of what we do, because this unlocks the ability to update the presentation of an experience with less friction. In fact, the term design tokens originated from SLDS many years ago.\n\nThat’s why it was so surprising to not find a page dedicated to design tokens in the new version. The term design tokens is mostly absent from the site, except for this quote found on the front page.\n\n> SLDS 2 prioritizes CSS custom properties as the visual language and decreases the usage of design tokens.\n> \n> — [SLDS 2](https://www.lightningdesignsystem.com/2e1ef8501/p/85bd85-lightning-design-system-2)\n\n\n\nI aimed to find out.\n\n## The problem they’re solving\n\nConversations sparked at the LinkedIn post as well as within the Design Systems Slack where I first saw the link. Alan Weibel, UX Architect at Salesforce, was responding in both places. In all of the discussion, his response to Brad Frost made things more clear.\n\n> …I think it depends on how you define design tokens.\n> \n> If the definition is design tokens are variables (tokens) for design system values, then yes, styling hooks are the same and come with a name-value pair.\n> \n> If that definition comes with expectations of the specifications in W3C drafts or common implementations of design tokens, then it is not the same. They’re a completely different format that is web first, non-web second.\n> \n> — [Alan Weibel, Salesforce UX Architect](https://www.linkedin.com/feed/update/urn:li:activity:7298413367847780352?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7298413367847780352%2C7298461710372270080%29&replyUrn=urn%3Ali%3Acomment%3A%28activity%3A7298413367847780352%2C7298742749405622273%29&dashCommentUrn=urn%3Ali%3Afsd_comment%3A%287298461710372270080%2Curn%3Ali%3Aactivity%3A7298413367847780352%29&dashReplyUrn=urn%3Ali%3Afsd_comment%3A%287298742749405622273%2Curn%3Ali%3Aactivity%3A7298413367847780352%29)\n\nThis highlighted the issue. The team at Salesforce has considered the use of the word “design tokens” to strictly mean the artifacts coming from the [DTCG](https://www.designtokens.org/) work. Meanwhile, the community has more commonly considered design tokens to simply be the name-value pairing for design purposes. In other words, at Salesforce “design tokens” equals DTCG specification while outside of Salesforce “design tokens” equals name-value pairings.\n\nSo they’ve decided to explicitly distance themselves from the evolving specification but that still doesn’t answer the question of “why?” Here’s another quote from Alan, this time from the Design Systems Slack:\n\n> Design tokens are very helpful for a lot of teams. They just aren’t super helpful for Salesforce. It was an extra step to create tokens to be used across multiple frameworks when 99% of Salesforce is on a single platform—the web. *Even our native mobile apps use webviews inside of the native wrapper.*\n> \n> We ended up using a web standard, CSS custom properties, as the name/value pair instead of design tokens. These style hooks are a lot easier to manage in both code and tooling. If folks need this CSS for a non-web application, then they can use the THEO tool.\n> \n> In the end, people still get name/value pairs for all the frameworks but it’s less complex and easier to manage for our platform\n> \n> — [Alan Weibel, Salesforce UX Architect](https://design-systems.slack.com/archives/C576NLX2A/p1740160012109289?thread_ts=1740077164.460439&cid=C576NLX2A)\n\nThere’s a few notes that I take away from this:\n\n- It was easier for the team to write CSS Custom Properties instead of requiring a process to turn non-CSS into CSS.\n- They opted for a solid web standard over the more tumultuous DTCG specification.\n- The team now focused primarily on the web, so supporting other platforms was considered overkill.\n- If some team needs to transform the CSS into non-CSS, they had an answer for that need using [THEO](https://github.com/salesforce-ux/theo).\n\n## How to fix this\n\nThe community had a very similar response to [Figma’s variables](https://www.youtube.com/watch?v=1ONxxlJnvdM). When the new feature was announced at Config in 2023, the slide showed the word “design tokens” crossed out. Certainly meant to cause a stir amongst the crowd before announcing variables which work very similar in concept. The team made a conscious decision to not name them design tokens but why? Jacob Miller answers that question in the Design Systems Slack:\n\n> …If we tailor-made a solution for design tokens, we’d end up with disparate systems for a bunch of other features that have similar requirements, such as translation strings or conditional prototyping logic.\n> \n> Rather than do that, we wanted two things: A more unified experience, and more alignment with code. In the same way that you can use css variables to implement design tokens, we wanted that with Figma as well.\n> \n> — [Jacob Miller, Figma Product Manager](https://design-systems.slack.com/archives/C56V07C4U/p1687366044434609?thread_ts=1687364523.348789&cid=C56V07C4U)\n\n[I wrote about why they were different](/posts/spicy-specifications/) when variables were first released, along with other design token metadata options at the time.\n\nThe difference between Salesforce and Figma is that [Figma has documentation which speaks about design tokens](https://help.figma.com/hc/en-us/articles/18490793776023-Update-1-Tokens-variables-and-styles) and how to implement them within their ecosystem. This makes it easier for folks expecting design tokens to be supported and how to transition those folks into the specific changes within Figma to do similar things.\n\nThis is where the decision for the public documentation of the SLDS breaks down. The lack of design tokens or a path for transitioning makes it hard for folks expecting to see the concept. SLDS does have name-value pairs in a similar way to how most of us think of design tokens, they’ve just renamed the concept to [Styling Hooks](https://www.lightningdesignsystem.com/2e1ef8501/p/319e5f-styling-hooks). This is the same as naming your carousel component “Fred”. It might work for your internal team, but cause friction for anyone coming at it for the first time, externally or internally.\n\nI’d recommend that the SLDS team explain in their public documentation how folks looking for design tokens can transition to styling hooks. At best, define “design tokens” more generally as the community currently does or make mention in [their blog post](https://www.salesforce.com/blog/what-are-styling-hooks/) that the DTCG was too complex for their needs at this time.\n\n## A form of protest\n\nUltimately, I agree with Salesforce’s decision to avoid the DTCG specification at this time. I’m a highly critical of the current direction. It is my opinion that it is scope-creeping into territories that will make it difficult for it to ever be finished.\n\nFor example, the DTCG specification originally defined a color in this way:\n\n```\n{\n \"colors\": {\n \"color-red-500\": {\n \"$type\": \"color\",\n \"$value\": \"rgba(180, 216, 167, .75)\",\n }\n }\n}\n```\n\nIn the example, the `$value` is a string. The newer specification is [in the process of defining color](https://github.com/design-tokens/community-group/pull/257) in this way:\n\n```\n{\n \"Acid green\": {\n \"$type\": \"color\",\n \"$value\": {\n \"$hex\": \"#00ff66\",\n \"$colorSpace\": {\n \"name\": \"srgb\",\n \"$components\": [180, 216, 167],\n \"$alpha\": 0.75\n }\n }\n }\n}\n```\n\nAmong other critisms I have, seeing color defined in this way highlights why Salesforce finds “design tokens” too complicated for their customers. **Defining all of the individual parts of a color in a structured object is tedious.** It is clear that the community group is less focused on making the file human-manageable at this point and expecting tools to help with the translation. I’m afraid this begins vendor lock-in where you might only be able to edit design tokens from tools. Salesforce Styling Hooks largely avoids the tooling needed to take the DTCG specification into their primary format for the web.\n\nI’ve spoken to Kaelig Deloumeau-Prigent, one of the co-chairs for the DTCG about the direction to this more complex object. The main reason seems to be the difficulty in parsing strings. His example explains that the CSS `rgb()` color function is an example of the complexity because it takes several different kinds of syntax which any consuming application would need to support. Standarizing the format for systems to injest makes it easier. I contest that this makes it easier for the machines, not for the humans authoring tokens.\n\nI am biased in this area as the creator of [Token Operations](https://github.com/ddamato/token-operations). While [folks could argue](https://github.com/ddamato/token-operations/issues/1) that the operations themselves are less accessible for human maintainers, the benefit is that those operations are for the machines but repeatable and sharable. The intention is for a single complex operation to be tucked away from human authors using those operations.\n\nI think a compromise in this area would be best. Where string concatenation could be added into the specification. Such that you could separate parts of the value meant to be concatenated for different platforms, but make it easier to author for humans. Based on my examples in [the DTCG issue](https://github.com/design-tokens/community-group/issues/224), string concatenation would solve much of the problems that Token Operations would handle otherwise. This would allow for the original simplified construction while allowing for more complicated multi-platform values to exist. This would also finish the specification much faster by avoiding all of the complexities that might come from every individual `$type`. Admittedly, this doesn’t solve for a zero-tooling ecosystem that Salesforce might have targetted, but I believe it would make it more accessible to those with minimal tooling.\n\n## Being intentional\n\nOver the years, I’ve avoided the word “semantic token” to describe the middle tier due to [my strict definition](/posts/truly-semantic/) in favor of the word “[intent](https://blog.damato.design/posts/tokens-as-intents/)”. I continue to refer to this as a *type* of design token to keep the concept connected. Where I work today, the word “design token” is rarely used in favor of “intents” which also delivers that strict definition. Where variables could be named and assigned anything, the criteria for similar as “intent” is more systematic and helps maintain a consistent construction and presentation as a result. No one asks “where are design tokens?” because *they are* design tokens.\n\nIt’s ok for design systems to be different, right? 😉",
"version": "1.0"
},
"coverImage": {
"$type": "blob",
"ref": {
"$link": "bafkreibo7fzb4m4f53pniglgv4gqqyate2r3vgtbkjs3plp274hqznynyy"
},
"mimeType": "image/png",
"size": 240570
},
"description": "The importance of disclosing the reasons behind decisions.",
"path": "/posts/avoiding-tokens",
"publishedAt": "2025-02-24T00:00:00.000Z",
"site": "https://blog.damato.design",
"tags": [
"tokens",
"css"
],
"textContent": "The design systems community was buzzing a few days ago with the announcement of version 2 of the Salesforce Lightning Design System (SLDS). I shared the link to the new documentation on LinkedIn and the engagement has been significant.\n\nAs someone who has visited dozens of design system documentation sites, there’s certain things I tend to look for when perusing the content. One of those things is how the team handles design tokens. Design tokens are a fundamental feature of what we do, because this unlocks the ability to update the presentation of an experience with less friction. In fact, the term design tokens originated from SLDS many years ago.\n\nThat’s why it was so surprising to not find a page dedicated to design tokens in the new version. The term design tokens is mostly absent from the site, except for this quote found on the front page.\n\nSLDS 2 prioritizes CSS custom properties as the visual language and decreases the usage of design tokens.\n— SLDS 2\n\nI aimed to find out.\n\nThe problem they’re solving\n\nConversations sparked at the LinkedIn post as well as within the Design Systems Slack where I first saw the link. Alan Weibel, UX Architect at Salesforce, was responding in both places. In all of the discussion, his response to Brad Frost made things more clear.\n\n…I think it depends on how you define design tokens.\nIf the definition is design tokens are variables (tokens) for design system values, then yes, styling hooks are the same and come with a name-value pair.\nIf that definition comes with expectations of the specifications in W3C drafts or common implementations of design tokens, then it is not the same. They’re a completely different format that is web first, non-web second.\n— Alan Weibel, Salesforce UX Architect\n\nThis highlighted the issue. The team at Salesforce has considered the use of the word “design tokens” to strictly mean the artifacts coming from the DTCG work. Meanwhile, the community has more commonly considered design tokens to simply be the name-value pairing for design purposes. In other words, at Salesforce “design tokens” equals DTCG specification while outside of Salesforce “design tokens” equals name-value pairings.\n\nSo they’ve decided to explicitly distance themselves from the evolving specification but that still doesn’t answer the question of “why?” Here’s another quote from Alan, this time from the Design Systems Slack:\n\nDesign tokens are very helpful for a lot of teams. They just aren’t super helpful for Salesforce. It was an extra step to create tokens to be used across multiple frameworks when 99% of Salesforce is on a single platform—the web. Even our native mobile apps use webviews inside of the native wrapper.\nWe ended up using a web standard, CSS custom properties, as the name/value pair instead of design tokens. These style hooks are a lot easier to manage in both code and tooling. If folks need this CSS for a non-web application, then they can use the THEO tool.\nIn the end, people still get name/value pairs for all the frameworks but it’s less complex and easier to manage for our platform\n— Alan Weibel, Salesforce UX Architect\n\nThere’s a few notes that I take away from this:\nIt was easier for the team to write CSS Custom Properties instead of requiring a process to turn non-CSS into CSS.\nThey opted for a solid web standard over the more tumultuous DTCG specification.\nThe team now focused primarily on the web, so supporting other platforms was considered overkill.\nIf some team needs to transform the CSS into non-CSS, they had an answer for that need using THEO.\n\nHow to fix this\n\nThe community had a very similar response to Figma’s variables. When the new feature was announced at Config in 2023, the slide showed the word “design tokens” crossed out. Certainly meant to cause a stir amongst the crowd before announcing variables which work very similar in concept. The team made a conscious decision to not name them design tokens but why? Jacob Miller answers that question in the Design Systems Slack:\n\n…If we tailor-made a solution for design tokens, we’d end up with disparate systems for a bunch of other features that have similar requirements, such as translation strings or conditional prototyping logic.\nRather than do that, we wanted two things: A more unified experience, and more alignment with code. In the same way that you can use css variables to implement design tokens, we wanted that with Figma as well.\n— Jacob Miller, Figma Product Manager\n\nI wrote about why they were different when variables were first released, along with other design token metadata options at the time.\n\nThe difference between Salesforce and Figma is that Figma has documentation which speaks about design tokens and how to implement them within their ecosystem. This makes it easier for folks expecting design tokens to be supported and how to transition those folks into the specific changes within Figma to do similar things.\n\nThis is where the decision for the public documentation of the SLDS breaks down. The lack of design tokens or a path for transitioning makes it hard for folks expecting to see the concept. SLDS does have name-value pairs in a similar way to how most of us think of design tokens, they’ve just renamed the concept to Styling Hooks. This is the same as naming your carousel component “Fred”. It might work for your internal team, but cause friction for anyone coming at it for the first time, externally or internally.\n\nI’d recommend that the SLDS team explain in their public documentation how folks looking for design tokens can transition to styling hooks. At best, define “design tokens” more generally as the community currently does or make mention in their blog post that the DTCG was too complex for their needs at this time.\n\nA form of protest\n\nUltimately, I agree with Salesforce’s decision to avoid the DTCG specification at this time. I’m a highly critical of the current direction. It is my opinion that it is scope-creeping into territories that will make it difficult for it to ever be finished.\n\nFor example, the DTCG specification originally defined a color in this way:\n\nIn the example, the is a string. The newer specification is in the process of defining color in this way:\n\nAmong other critisms I have, seeing color defined in this way highlights why Salesforce finds “design tokens” too complicated for their customers. Defining all of the individual parts of a color in a structured object is tedious. It is clear that the community group is less focused on making the file human-manageable at this point and expecting tools to help with the translation. I’m afraid this begins vendor lock-in where you might only be able to edit design tokens from tools. Salesforce Styling Hooks largely avoids the tooling needed to take the DTCG specification into their primary format for the web.\n\nI’ve spoken to Kaelig Deloumeau-Prigent, one of the co-chairs for the DTCG about the direction to this more complex object. The main reason seems to be the difficulty in parsing strings. His example explains that the CSS color function is an example of the complexity because it takes several different kinds of syntax which any consuming application would need to support. Standarizing the format for systems to injest makes it easier. I contest that this makes it easier for the machines, not for the humans authoring tokens.\n\nI am biased in this area as the creator of Token Operations. While folks could argue that the operations themselves are less accessible for human maintainers, the benefit is that those operations are for the machines but repeatable and sharable. The intention is for a single complex operation to be tucked away from human authors using those operations.\n\nI think a compromise in this area would be best. Where string concatenation could be added into the specification. Such that you could separate parts of the value meant to be concatenated for different platforms, but make it easier to author for humans. Based on my examples in the DTCG issue, string concatenation would solve much of the problems that Token Operations would handle otherwise. This would allow for the original simplified construction while allowing for more complicated multi-platform values to exist. This would also finish the specification much faster by avoiding all of the complexities that might come from every individual . Admittedly, this doesn’t solve for a zero-tooling ecosystem that Salesforce might have targetted, but I believe it would make it more accessible to those with minimal tooling.\n\nBeing intentional\n\nOver the years, I’ve avoided the word “semantic token” to describe the middle tier due to my strict definition in favor of the word “intent”. I continue to refer to this as a type of design token to keep the concept connected. Where I work today, the word “design token” is rarely used in favor of “intents” which also delivers that strict definition. Where variables could be named and assigned anything, the criteria for similar as “intent” is more systematic and helps maintain a consistent construction and presentation as a result. No one asks “where are design tokens?” because they are design tokens.\n\nIt’s ok for design systems to be different, right? 😉",
"title": "Avoiding tokens",
"updatedAt": "2026-06-13T19:13:45.673Z"
}