{
  "$type": "site.standard.document",
  "content": {
    "$type": "site.standard.content.markdown",
    "text": "In [my design system playground](https://system.damato.design), one of my small goals was to have the ability to import a design token identically between CSS and JavaScript. Here’s an example of the developer experience I was expecting and succeed in making: to use `tokens.$action_primary_backgroundColor` as a value reference in both `.scss` and `.js` files identically.\n\n### Writing (S)CSS.\n\n```\n@use '../tokens.module';\n\nbutton:where([data-priority=\"primary\"]) {\n    background-color: tokens.$action_primary_backgroundColor;\n}\n```\n\n### Writing JS(X).\n\n```\nimport tokens from './_tokens.module.scss';\n\nfunction PrimaryButton(props) {\n  return (\n    <button\n        {...props}\n        style={{ \n            backgroundColor: tokens.$action_primary_backgroundColor\n        }}/>\n  );\n}\n```\n\nThe important part is that the intention of using the background color for primary buttons is shared between the CSS and the JavaScript. `tokens.$action_primary_backgroundColor` is identical between these examples while being applied in different languages. This method helps reduce the context switching between writing CSS and writing JS to get the expected styling value.\n\n## Working source\n\nI’ll cut to the chase, the following is a `_tokens.module.scss` file that all the components have access to. [Here’s the file I use in my system.](https://github.com/damato-design/system/blob/main/src/components/_tokens.module.scss) You’ll want to generate this file based on how you create and manage tokens in your system. You should expect many, many more entries in this file than what is shown below. This example is only supporting `tokens.$some_token` between `.scss` and `.js` files.\n\n```\n/** For .scss, $some_token does not need to match the --some_token  */\n$some_token: var(--some_token);\n\n/** For .js, the #{'$some_token'} needs match $some_token */\n:export {\n    #{'$some_token'}: $some_token;\n}\n```\n\n## Prerequisites\n\nAs you might tell, there are some requirements to this in order for the DX to work well.\n\n-   You’ll need to ensure that the CSS custom property `--some_token` has a value and is present on each page such that `var(--some_token)` is later resolved. You could opt to *not* use a CSS custom property here if the value don’t change. However, if you have or plan to have dark mode in your system, then you don’t want to hardcode the values here.\n-   You’ll need to be using [CSS modules](https://github.com/css-modules/css-modules) to get the JS import working, using the `:export` pseudo selector. Most JS frameworks support CSS modules with minimal configuration. The word `module` in the file name is required for the CSS Modules processing to pick this up as a CSS Module, so it can be imported into `.js` files.\n-   You’ll need to be using [SCSS](https://sass-lang.com/) to get the `@use` and `$` variable syntax working in your `.scss` files. The leading `_` in the file name `_tokens.module.scss` is required for the `@use` syntax to work. This will expose a `tokens` key in the SCSS [based on the file name](https://sass-lang.com/documentation/at-rules/use/). In other words, to get the `tokens.` syntax in your files, your file name should start with `_tokens.`.\n\n## Required characters\n\nThere’s lots of token naming constructions out there that delimit the sections of the token. For this to work, the underscore (`_`) is one of the only characters that will work between (S)CSS and JS.\n\n-   The dot delimiter (`.`) will not be valid in `.scss` files.\n-   The hyphen delimiter (`-`) will not be valid in `.js` files.\n\nWhen you generate the `_tokens.module.scss` file, you’ll want to convert any delimiter to an underscore. As an example, if you have a token `button.primary.backgroundColor`, you’ll want to prepare that as `button_primary_backgroundColor` to be used in source files. This makes the name usable between `.scss` and `.js` files in an identical way.\n\nThe leading `$` is expected for the SCSS ecosystem to be used as a variable. This is carried over into the JS ecosystem for consistency.\n\nYou can review the source of my system to find additional details:\n\n-   [How I curate tokens with values in `.yaml`.](https://github.com/damato-design/system/blob/main/src/modes/_system.yml)\n-   [How I transform tokens to `_tokens.module.scss`.](https://github.com/damato-design/system/blob/main/scripts/generate-module.js)",
    "version": "1.0"
  },
  "description": "Exploring a way to make token importing similar in different contexts.",
  "path": "/posts/interoperable-tokens",
  "publishedAt": "2025-01-16T00:00:00.000Z",
  "site": "https://blog.damato.design",
  "tags": [
    "tokens",
    "css",
    "naming"
  ],
  "textContent": "In my design system playground, one of my small goals was to have the ability to import a design token identically between CSS and JavaScript. Here’s an example of the developer experience I was expecting and succeed in making: to use  as a value reference in both  and  files identically.\n\nWriting (S)CSS.\n\nWriting JS(X).\n\nThe important part is that the intention of using the background color for primary buttons is shared between the CSS and the JavaScript.  is identical between these examples while being applied in different languages. This method helps reduce the context switching between writing CSS and writing JS to get the expected styling value.\n\nWorking source\n\nI’ll cut to the chase, the following is a  file that all the components have access to. Here’s the file I use in my system. You’ll want to generate this file based on how you create and manage tokens in your system. You should expect many, many more entries in this file than what is shown below. This example is only supporting  between  and  files.\n\nPrerequisites\n\nAs you might tell, there are some requirements to this in order for the DX to work well.\nYou’ll need to ensure that the CSS custom property  has a value and is present on each page such that  is later resolved. You could opt to not use a CSS custom property here if the value don’t change. However, if you have or plan to have dark mode in your system, then you don’t want to hardcode the values here.\nYou’ll need to be using CSS modules to get the JS import working, using the  pseudo selector. Most JS frameworks support CSS modules with minimal configuration. The word  in the file name is required for the CSS Modules processing to pick this up as a CSS Module, so it can be imported into  files.\nYou’ll need to be using SCSS to get the  and  variable syntax working in your  files. The leading  in the file name  is required for the  syntax to work. This will expose a  key in the SCSS based on the file name. In other words, to get the  syntax in your files, your file name should start with .\n\nRequired characters\n\nThere’s lots of token naming constructions out there that delimit the sections of the token. For this to work, the underscore () is one of the only characters that will work between (S)CSS and JS.\nThe dot delimiter () will not be valid in  files.\nThe hyphen delimiter () will not be valid in  files.\n\nWhen you generate the  file, you’ll want to convert any delimiter to an underscore. As an example, if you have a token , you’ll want to prepare that as  to be used in source files. This makes the name usable between  and  files in an identical way.\n\nThe leading  is expected for the SCSS ecosystem to be used as a variable. This is carried over into the JS ecosystem for consistency.\n\nYou can review the source of my system to find additional details:\nHow I curate tokens with values in .\nHow I transform tokens to .",
  "title": "Interoperable tokens",
  "updatedAt": "2026-06-10T01:51:47.483Z"
}