[WIP-02] [Project Solar / Phase 1 / Tokens Pipeline] Add $modes support to tokens pipeline

[didoo]

📌 Summary

This is the implementation PR for adding support to co-located $modes values in the design tokens JSON files, the processing of such values, and the generation of distinct "themed" CSS files in output, with different formats.

This is built on top of #3238

🛠️ Detailed description

In this PR I have:

• refactored the build.ts script
  • re-organized the code by moving the "targets" (what we want to generate in output for the different consumers we serve) to their own getStyleDictionaryConfig.ts file, so there's less noise in the main file, and it's much easier to see what the configurations are and how they're set up
• added a custom pre-processor replace-value-for-mode-${mode} that tricks Style Dictionary (SD) by replacing all the expected $value entries/values with the corresponding $modes[mode] values, before the tokens are processed by SD
• added a custom transform attributes/themeable that adds a themeable: true entry to a token object, if the token itself has a $modes key, or one of its alias references/ancestors has a $modes key
  • there is a special case where, if the aliasing is "composed" (eg. "{foo.bar.baz} {xxx.yyy.zzz}") it's not working; this will be tackled in a separate PR, since it's a very specific code change to make, and it can be done in isolation
• added a custom action generate-extra-theming-files that executes the code of the generateExtraThemingFiles.ts which post-processes the single-theme CSS files generated by SD (under themed-tokens/with-root-selector) and combines them in different formats
  • with-prefers-color-scheme for consumers (eg Boundary) that use only @media(prefers-color-scheme) to control the theme of their application
    • in this case, only Carbon g0 and g100 are available
  • with-css-selectors for consumers that will use the HDS-provided theme switcher or follow the HDS guidance of how to implement theming by themselves (this uses [data-hds-theme=***] and .hds-theme-*** as CSS selectors
    • in this case, all the Carbon g0, g10, g90, g100 are available (in the future this may change, and we may want to expose only g0 and g100 also for this approach
  • with-combined-strategies is a mix of the previous two, where consumers may want to give their end-user the option to choose between light, dark, and auto (system settings via prefers-color-scheme)
    • in this case, all the Carbon g0, g10, g90, g100 are available (in the future this may change, and we may want to expose only g0 and g100 also for this approach
  • with-scss-mixins is unlikely to be used, but it was super east to implement, and it provides a simple way for consumers to include theming in their codebase in an extremely customized way

For testing purposes I have also:

• updated a few design tokens entries (color.palette.neutral-0, color.foreground.primary, and a few typography tokens) adding an extra $modes block of values (some of them, referencing the Carbon tokens extracted by our pipeline from the @carbon/*** packages)
• re-generated the files in output, so that they would contain these themed tokens; in this way I was able to verify that the code was doing what was expecting, and use the "themed" CSS files further down the line in the subsequent PRs to compile "themed" CSS files for our components, and then use them inside the Showcase for demoing the themed HDS components.

🔎 How to review

• check how the $modes are defined in the src JSON files, and see if that makes sense to you as future code maintainer
• look at the logic for the StyleDictionary changes (mainly from the JavaScript/TypeScript perspective; knowing the internals and APIs of StyleDictionary is beyond what's required for the review, it's super-complex and at times I struggle too to understand how it works, since the architectural changes introduced in version 5.0)
• validate the logic that splits the output of the design tokens between "common" and "themed" tokens (splitting in different files, one per mode/theme)
• look at the getStyleDictionaryConfig and see if the code as is makes sense to you, as possible future maintainer, if that's enough understandable on what it does, on how things are named, etc
• look at the generateExtraThemingFiles and see if the code as is makes sense to you, as possible future maintainer, if that's enough understandable on what it does, on how things are named, etc
• check the generated CSS files, in particular the "themed" ones, and see if you think the CSS selectors are correct (we may even consider wrapping them with a :where() to reduce the specificity, something I've seen being done somewhere else with theming files)
• see how these files and the tokens that they contain are used in [WIP-03] [Project Solar / Phase 1 / Themed CSS for HDS components] Rollup configuration and Sass processing for multiple files  #3259 to compile different CSS files for the HDS component and these in turn are used in [WIP-04] [Project Solar / Phase 1 / Showcase] Add support for theming and theme-switching to the showcase #3240 to handle theming in the showcase
• more in general consider the naming used for variables, methods, files, etc (there's a gray zone between what is a theme and what is a mode, that I need help to figure out)

🛠️ How to test

Add more $modes entries to the src JSON tokens (taking inspiration by the existing ones) and then run the pnpm build command, and see how the different values are reflected in the generated CSS token files. Try to test different combinations of aliasing, edge cases you can think of, etc. In particular check that the different theme values are reflected in the corresponding theme files, under the correct CSS selectors, and that the themed and non-themed tokens are correctly split in common and themed files. If you add only $modes values, the "old" tokens should remain unaltered.

🗒️ TODOs

Things that still need to be done before merging

• fix issue with font-size using different units between HDS and Carbon (see comment here)
• decide the naming conventions around themes and modes (what is what, what do we call things, etc)
• understand if the current generation of CSS helpers files is OK as is now or we need to account for the theming of the underlying CSS variables (likely no, but we have to double check, and probably add something to the showcase to make sure we don't cause regression now and in the future)
• understand if we want to wrap them selectors with a :where() to reduce the specificity, something I've seen being done somewhere else with theming files)
• understand if we want to use (not (prefers-color-scheme: dark)) instead of (prefers-color-scheme: 'light') per @KristinLBradley suggestion

Things that still need to be done (in fast-follow-up PRs)

• remove some of the temporary code (left for debugging or to have a baseline when fixing the issue with the outputReferences logic and the themeable transform
• understand if we want to define a custom outputReferences function (in which case, understand which references should be outputted and which shouldn't) or we keep it to false
• resolve the issue with attributes/themeable transformation non working when the alias is composed

🔗 External links

Jira tickets

• Epic: https://hashicorp.atlassian.net/browse/HDS-5193
• Task: https://hashicorp.atlassian.net/browse/HDS-5216

---

👀 Component checklist

• Percy was checked for any visual regression
• A changelog entry was added via Changesets if needed (see templates here)
  • changelogs will be added in the main feature branch

💬 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	Preview	Updated (UTC)
hds-showcase	Ready	Preview	Oct 24, 2025 5:35pm
hds-website	Ready	Preview	Oct 24, 2025 5:35pm