🧪 [SPIKE] [Project Solar / Phase 1 / Engineering Follow-ups] Fix issues with outputReferences and isThemeable

[didoo]

🚨 DO NOT MERGE 🚨

Note

If this PR is informally approved, I'll open a proper one with a cleaner commit history to make proper formal review easier.

📌 Summary

This (spike) PR has been quite a rabbit hole to go down into, exploring the StyleDictionary APIs and codebase to understand exactly how to change our logic to achieve a reliable way to do two fundamental things in the processing of themed tokens:

1. understand which token could have its references (aliases) rendered in output (as CSS var() values)
2. understand if and where a token should be saved, if in the "common" CSS file (shared between all the available modes) or in the "themed" CSS files (split by modes: default + cds-g0/10/90/100)

These two things are strictly intertwined. And together with 1) the existence of private tokens that should referenced by their value, not aliased, and 2) the fact that there are some custom transforms applied to the values themselves, some of which are "transitive", made the whole logic really hard to grasp and make sure worked as expected (and could not rely on the existing APIs for references because they're only approximate and in many cases didn't work for us, so we had to pivot to using custom helpers, which was... an interesting journey to do.

Anyway, apparently everything works as I think should, so I am going to open the draft PR for initial review; once we're happy with its overarching architecture/logic, I'll open a proper PR with a clear history to make the final/proper review eaiser.

🔎 How to review

Tip

Don't look at the commit history (unless you want to go down the same rabbit hole I went into).

It's not probably worth it to look a the diffs for the files under the packages/tokens/dist/products/ and showcase/public/assets/styles/@hashicorp/ folders, since the tokens in output have now been sorted alphabethically, plus due to the change in the processing logic some of them have been moved from the "themed" to the "common" and vice-versa.

Focus instead on the changes to the files under the build folder, which contain all the meaningful changes to the logic of how we generate "themed" tokens. And remember, there will be a proper PR opened instead of this one.

🛠️ How to test

There are different ways in which it would be great to stress test this approach. For all of them I suggest you checkout the PR's branch and play with the code in your local environment.

Test tokens

This is the simplest one, that I suggest to start with, to familiarize yourself with the changes introduces and the logic behind it. In the file packages/tokens/scripts/build-parts/getStyleDictionaryConfig.ts uncomment the two src/test/**/*.json entries (and comment the three below it), then run pnpm build. This will use the tokens found in the packages/tokens/src/test/test.json file and generate the CSS files in output. The first block of tokens follow the schema included below, and the second block have been added later to test more use cases I was finding. Can you think of any other combination of tokens that is not covered? If so, add them to the test files and regenerate the CSS files in output and see if the location ("common" vs "themed") and values (static vs var() alias) of the newly added tokens are correct and where/how you would expect them.

Production tokens

This actually is more complex to play with, because there are a lot of tokens with different formats/values, and they have been moved around when comparing the generated files with the ones in the main feature branch #3237. If you want, you can try (or can try to think of ways of how we could reliably test this more complex set of tokens).

[Note: among the many test I did, I compared the merged "common" + "themed" files between the old and the new output, and all the tokens are the same, except for their values (some have been replaced with aliases var() instead of static values, which means we've not lost any token in the new filtering logic; here are the files if you want to see the outcome: Archive.zip]

📸 Screenshots

This is the initial schema that I used to prepare a set of test tokens to validate different combinations of token formats (private, with aliases/references, with theming, etc)

Later I added more test tokens, including some from the HDS set that were not working with the changes I was making. The final set used for testing can be found in packages/tokens/src/test/test.json

🔗 External links

Jira tickets:

• https://hashicorp.atlassian.net/browse/HDS-5669
• https://hashicorp.atlassian.net/browse/HDS-5667
• https://hashicorp.atlassian.net/browse/HDS-5726

Figma file used to brainstorm possible tokens combinations (in case we need it in the future): https://www.figma.com/design/BDq7Atokyf5Aq9pA5rIaYd/Untitled?m=auto&t=z4fx1cp1BcpzE6Ti-6

StyleDictionary API documentation:

• https://styledictionary.com/reference/api/

---

👀 Component checklist

• Percy was checked for any visual regression

💬 Please consider using conventional comments when reviewing this PR.

📋 PCI review checklist

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.
• If applicable, I've worked with GRC to document the impact of any changes to security controls.
  Examples of changes to controls include access controls, encryption, logging, etc.
• If applicable, I've worked with GRC to ensure compliance due to a significant change to the in-scope PCI environment.
  Examples include changes to operating systems, ports, protocols, services, cryptography-related components, PII processing code, etc.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
hds-showcase	Ready	Preview	Dec 18, 2025 9:49pm
hds-website	Ready	Preview	Dec 18, 2025 9:49pm