Design tokens pipeline - Upgrade `StyleDictionary` to version `4.2.0` #2560

didoo · 2024-11-14T15:15:46Z

📌 Summary

While working on the exploration of extending coverage of component-level design tokens in our codebase (https://hashicorp.atlassian.net/browse/HDS-3915) and how this effort would connect with the implementation of theming in our system, I have decided that it was time to upgrade

🛠️ Detailed description

In this PR I have:

updated style-dictionary dev-dependency to 4.2.0 (latest)
run the migration codemod npx codemod styledictionary/4/migration-recipe (see: https://styledictionary.com/version-4/migration/)
- in reality the codemod didn't do much, and in a couple of cases actually messed up the code
updated package.json file to be "type": "module” per StyleDictionary guide (see: https://styledictionary.com/version-4/migration/#es-modules-instead-of-commonjs)
updated the build script in the package.json file to use tsx instead of tsc
- I have seen this used in this way in other StyleDictionary 4 repos (here and here)
replaced lodash dev-dependency with lodash-es (compatible with ES Modules)
updated tsconfig.json to make the Node.js application run and build correctly
updated build.ts script and other sub-scripts to follow the new StyleDictionary APIs
- in the process I have fixed all the TS issues raised by the linter
run yarn build with the new version of StyleDictonary (see below about the changes introduced in this operation)

Changes in the generated files:

While there are difference in the generated output files, these are not meaningful because:

the header has changed, now there is no more a “Generated on” date
the hex value of one tokena has been changed from #fff to #ffffff (probably due to a new version of the tinycolor dependency)
the order of some tokens in the generated files has change, but I think it’s because of the async nature of the new StyleDictionary code and/or how the files are read from the filesystem in a recursive way (before child folders were read before child files, now it seems the order is child files and then child folders)

In any case, to be 100% sure I compared the old vs the new files with the tokens sorted alphabetically, and the only differences were the one described above, so I don't see problems with the changes introduced (just a re-ordering)

💻 How to test it

pull the branch spike-styledictionary-update-v4
yarn install
cd packages/tokens
yarn build

At this point, you should see the script run, execute successfully, but no output files should be changed.

Now try to update one or more token values, run again the yarn build script, and you should see the output generated with the new updated values.

🤔 Things to discuss

Should we have a changelog associated with this PR? technically the generated files have changed, but practically they haven't. Maybe just a patch bump, just in case?

🔗 External links

Jira ticket: https://hashicorp.atlassian.net/browse/HDS-4170

👀 Component checklist

Percy was checked for any visual regression
A changelog entry was added via Changesets if needed (see templates here)

💬 Please consider using conventional comments when reviewing this PR.

npx codemod styledictionary/4/migration-recipe see: https://styledictionary.com/version-4/migration/

…ary guide see: https://styledictionary.com/version-4/migration/#es-modules-instead-of-commonjs

… `tsc` I have seen this used in this way in other StyleDictionary 4 repos: - https://github.com/navikt/aksel/blob/c5f46e60ad20a9b67723ddc930df1b9be8d8d3a6/%40navikt/core/tokens/package.json - https://github.com/digital-go-jp/design-tokens/blob/431d2bacc7f5ca58ce4a456f02137cf87d8d0a11/package.json#L31

… Modules)

… correctly

…leDictionary APIs and in the process fix all the TS issues raised by the linter

there is a diff in code, but it’s not meaningful because: - the header has changed, now there is no more a “Generated on” date - the hex value of one tokena has been changed from `#fff` to `#ffffff` (probably due to a new version of the `tinycolor` dependency) - the order of some tokens in the generated files has change, but I think it’s because of the async nature of the new StyleDictionary code and/or how the files are read from the filesystem in a recursive way (before child folders were read before child files, now it seems the order is child files and then child folders) (to be 100% sure I compared the old vs the new file with the tokens sorted alphabetically, and the only differences were the one described above, so it should OK as is now too)

vercel · 2024-11-14T15:15:51Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
hds-showcase	✅ Ready (Inspect)	Visit Preview	Nov 14, 2024 3:15pm
hds-website	✅ Ready (Inspect)	Visit Preview	Nov 14, 2024 3:15pm

didoo · 2024-11-14T15:17:09Z

packages/tokens/dist/cloud-email/helpers/color.css

@@ -1,6 +1,5 @@
 /**
- * Do not edit directly
- * Generated on Fri, 20 Sep 2024 19:02:21 GMT
+ * Do not edit directly, this file was auto-generated.


This change is because in StyleDictionary the header (this comment at the top of the files) now doesn't contain anymore the date in which it's been generated; this will lead to less noise in the diffs)

didoo · 2024-11-14T15:17:57Z

packages/tokens/dist/cloud-email/helpers/elevation.css

 .hds-elevation-inset { box-shadow: inset 0px 1px 2px 1px #656a761a); }
 .hds-elevation-low { box-shadow: 0px 1px 1px 0px #656a760d, 0px 2px 2px 0px #656a760d); }
 .hds-elevation-mid { box-shadow: 0px 2px 3px 0px #656a761a, 0px 8px 16px -10px #656a7633); }
+.hds-elevation-high { box-shadow: 0px 2px 3px 0px #656a7626, 0px 16px 16px -10px #656a7633); }


For some reasons, these properties are re-ordered when the new style dictionary package is used.

didoo · 2024-11-14T15:19:15Z

packages/tokens/dist/devdot/css/tokens.css

@@ -195,6 +194,47 @@
  --token-surface-overlay-box-shadow: 0 0 0 1px #3b3d4540, 0px 2px 3px 0px #3b3d4540, 0px 12px 24px 0px #3b3d4559;
  --token-focus-ring-action-box-shadow: inset 0 0 0 1px #0c56e9, 0 0 0 3px #5990ff;
  --token-focus-ring-critical-box-shadow: inset 0 0 0 1px #c00005, 0 0 0 3px #dd7578;
+  --token-app-header-height: 60px;


For some reasons, these properties are re-ordered when the new style dictionary package is used.

In any case, to be 100% sure, I've compared the old vs the new version of these files, sorting the tokens alphabetically, and the only difference is the order in which they're declared (no other meaningful differences)

didoo · 2024-11-14T15:19:57Z

packages/tokens/dist/devdot/css/tokens.css

@@ -320,7 +319,7 @@
  --token-side-nav-body-list-item-content-spacing-horizontal: 8px;
  --token-side-nav-body-list-item-border-radius: 5px;
  --token-side-nav-color-foreground-primary: #dedfe3;
-  --token-side-nav-color-foreground-strong: #fff;
+  --token-side-nav-color-foreground-strong: #ffffff;


I think this is due to the new tinycolor package version.

didoo · 2024-11-14T15:22:00Z

packages/tokens/scripts/build-parts/generateTypographyHelpers.ts

-            declarations.push(`font-family: ${valueFontFamily};`);
-            declarations.push(`font-size: ${valueFontSize};`);
-            declarations.push(`line-height: ${valueLineHeight};`);
+            if (outputCssVars) {


I had to make this change to satisfy the TS linter

didoo · 2024-11-14T15:24:13Z

packages/tokens/scripts/build.ts

-StyleDictionaryPackage.registerTransform({
-    name: 'time/seconds', // notice: the name is an override of an existing predefined method
+StyleDictionary.registerTransform({
+    name: 'time/sec',


apparently overriding existing/official transform names does not work anymore (the output value was incorrect) so I had to change it to a custom transform name.

didoo · 2024-11-14T15:24:59Z

packages/tokens/scripts/build.ts

@@ -268,13 +276,14 @@ console.log('\n==============================================');
 console.log(`\nCleaning up dist folder`);
 fs.emptyDirSync(distFolder);

-Object.keys(targets).forEach(target => {
-    const StyleDictionary = StyleDictionaryPackage.extend(getStyleDictionaryConfig({ target }));
+for (const target of Object.keys(targets)) {


now that StyleDictionary has become an async method, we can't use anymore the forEach loop.

didoo · 2024-11-14T15:25:47Z

packages/tokens/tsconfig.json

@Dhaulagiri @alex-ju can you check that the changes I made to this file make sense (based on your experience/knowledge)? thanks

didoo · 2024-11-14T15:26:56Z

packages/tokens/package.json

@@ -16,26 +16,28 @@
  },
  "license": "MPL-2.0",
  "author": "HashiCorp Design Systems <[email protected]>",
+  "type": "module",


@Dhaulagiri @alex-ju unless I changed this to be a "type": "module" the script didn't work as expected (it was throwing errors in the compilation/execution of the script)

didoo · 2024-11-14T15:28:19Z

packages/tokens/package.json

  "scripts": {
    "typecheck": "yarn tsc --noEmit",
    "lint": "yarn eslint --quiet --ext .js,.ts",
-    "build": "ts-node --transpile-only ./scripts/build"
+    "build": "tsx ./scripts/build"


@Dhaulagiri @alex-ju this is the way I managed to get it working (I took "inspiration" from here and here). If you know otherwise or have better idea, please come forward :)

didoo added 8 commits November 13, 2024 11:16

updated style-dictionary dev-dependency to 4.2.0 (latest)

ebe3b76

run the migration codemod

27f4242

npx codemod styledictionary/4/migration-recipe see: https://styledictionary.com/version-4/migration/

updated package.json file to be "type": "module” per StyleDiction…

e08f103

…ary guide see: https://styledictionary.com/version-4/migration/#es-modules-instead-of-commonjs

replaced lodash dev-dependency with lodash-es (compatible with ES…

2102185

… Modules)

updated tsconfig.json to make the Node.js application run and build…

68ce2aa

… correctly

updated build.ts script and other sub-scripts to follow the new Sty…

d31731c

…leDictionary APIs and in the process fix all the TS issues raised by the linter

hashibot-hds added the packages/tokens label Nov 14, 2024

didoo requested review from alex-ju and Dhaulagiri November 14, 2024 15:16

didoo commented Nov 15, 2024

View reviewed changes

didoo marked this pull request as ready for review November 15, 2024 09:09

didoo requested a review from a team as a code owner November 15, 2024 09:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Design tokens pipeline - Upgrade `StyleDictionary` to version `4.2.0` #2560

Design tokens pipeline - Upgrade `StyleDictionary` to version `4.2.0` #2560

didoo commented Nov 14, 2024 •

edited

Loading

vercel bot commented Nov 14, 2024

didoo Nov 14, 2024

didoo Nov 14, 2024

didoo Nov 14, 2024

didoo Nov 14, 2024

didoo Nov 14, 2024

didoo Nov 14, 2024

didoo Nov 14, 2024

didoo Nov 14, 2024

didoo Nov 14, 2024

didoo Nov 14, 2024

Design tokens pipeline - Upgrade StyleDictionary to version 4.2.0 #2560

Are you sure you want to change the base?

Design tokens pipeline - Upgrade StyleDictionary to version 4.2.0 #2560

Conversation

didoo commented Nov 14, 2024 • edited Loading

📌 Summary

🛠️ Detailed description

Changes in the generated files:

💻 How to test it

🤔 Things to discuss

🔗 External links

👀 Component checklist

vercel bot commented Nov 14, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Design tokens pipeline - Upgrade `StyleDictionary` to version `4.2.0` #2560

Design tokens pipeline - Upgrade `StyleDictionary` to version `4.2.0` #2560

didoo commented Nov 14, 2024 •

edited

Loading