[WIP-03] [Project Solar / Phase 1 / Themed CSS for HDS components] Rollup configuration and Sass processing for multiple files

[didoo]

📌 Summary

This is built on top of #3239 and is based on the initial spike done by @alex-ju in #3235

🛠️ Detailed description

In this PR I have:

• re-organized the components' Sass files architecture to split the common part in a separate file, and add two new Sass files that include theming via CSS selectors or via prefers-color-scheme
• update the Rollup configuration to process multiple Sass files and generate distinct CSS files in output:
  • design-system-components.css - current file for HDS components
  • design-system-components-theming-with-css-selectors.css - new file for theming via CSS selectors
  • design-system-components-theming-with-prefers-color-scheme.css - new file for theming via prefers-color-scheme

Then, after discussion and agreement with @alex-ju, I have moved also the existing compilation of the design-system-components.scss and design-system-power-select-overrides.scss files to our custom plugin, so we can remove rollup-plugin-scss as dev-dependency

• in the new configuration, the design-system-power-select-overrides.scss is not only copied in the dist folder, but also compiled to .css (and a .map file is generated)

💬 To discuss/decide

• would it make sense to have a "normal" CSS compiled for the "old" components, as is now, made of the "standard" non-themed files, and instead of compiling three different compiled "themed" CSS file, have only one for the components Scss code (it doesn't need the tokens CSS to compile!) and consumers import the "themed" CSS file they want, depending on which type of theming implementation they want to use
  • Per Copilot review: "Using @use with a .css file extension is invalid in Sass. The @use rule should import .scss files, not .css files. Either change the file extension to .scss or use @import instead.
    • - @use "products/css/themed-tokens/with-prefers-color-scheme/tokens.css";
    • + @import "products/css/themed-tokens/with-prefers-color-scheme/tokens.css";

🔎 How to review

You can look at the single commits, to see the sequence of steps and understand the explorations and thinking behind the PR, or you can look directly at the files, checking how the Scss files have been organized, how the Rollup plugin function has been implemented, and how the path for the include declarations have been updated to make it more obvious where a file was coming from.

🛠️ How to test

Check out the branch, delete the dist folder under packages/components, run the command pnpm build or pnpm start, and see how different files are copied/generated under packages/components/dist/styles/@hashicorp (source Scss files, compiled CSS files, map files)

You can also go one step further, and update (or add) some design tokens with $modes values, run the pnpm build command in the packages/tokens folder, and then run the command pnpm build in the packages/components folder and see how the tokens changes are reflected in the generated CSS files for the components (if only $modes are changed, the file packages/components/dist/styles/@hashicorp/design-system-components.css should remain untouched.

🔗 External links

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

---

👀 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	Preview	Updated (UTC)
hds-showcase	Ready	Preview	Oct 15, 2025 2:48pm
hds-website	Ready	Preview	Oct 15, 2025 2:48pm

[Copilot]

Pull Request Overview

This PR reorganizes the Sass architecture for the Helios Design System components to support theming capabilities. It creates a foundation for generating multiple CSS builds with different theming strategies while maintaining the existing component functionality.

Key changes:

• Reorganizes Sass files to separate common components from theming-specific configurations
• Updates Rollup configuration to support multiple CSS output files with custom SCSS compilation
• Creates new themed CSS variants using CSS selectors and prefers-color-scheme approaches

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/components/src/styles/components/index.scss	New centralized index file importing all component SCSS files
packages/components/src/styles/@hashicorp/design-system-components.scss	Refactored to use new components index and updated token paths
packages/components/src/styles/@hashicorp/design-system-components-theming-with-prefers-color-scheme.scss	New themed variant using prefers-color-scheme media queries
packages/components/src/styles/@hashicorp/design-system-components-theming-with-css-selectors.scss	New themed variant using CSS selectors
packages/components/rollup.config.mjs	Updated with custom SCSS compilation function and multiple output configurations

[Copilot]

Pull Request Overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[dchyun]

Have some general discussion comments around the structure of the css files, but overall the rollup is looking good to me. Did a test of adding new modes and all files were updated as expected.

[dchyun]

[Question] Will we be creating files here for the with-root-selector css tokens themes as well?

[dchyun]

[Note] I think these can stay as "common" and don't need to be changed based on the theme. All of the helper classes reference a CSS variable of the same name as the class (mostly). If the variables they reference are themed there shouldn't be any need to make any update to the classes themselves.

The one exception is the font weight classes which are hard coded, but this could be updated

.hds-font-weight-regular { font-weight: 400; }
.hds-font-weight-medium { font-weight: 500; }
.hds-font-weight-semibold { font-weight: 600; }
.hds-font-weight-bold { font-weight: 700; }

[dchyun]

would it make sense to have a "normal" CSS compiled for the "old" components, as is now, made of the "standard" non-themed files, and instead of compiling three different compiled "themed" CSS file, have only one for the components Scss code

[Discussion topic] I agree with your idea. I prefer there to be an "old" hds theme files that matches what exists today, and then separate theme and component style files that could be the future of how things work.

Theming use cases

To come to this opinion first I tried to lay out all the possible use cases a consumer would have for using themes both now and in the future

As a consumer I would like to...

• Use the original HDS theme only
  • I would prefer to import one file it is today, and not have to change my code to use one for themes and one for components
• Use all themes and switch between them
  • Combined strategy
  • CSS selectors
• Use prefers colors mode
  • Use the default themes selected by the HDS team for light and dark
  • Customize which themes are set for each(?)
• Use only one theme (either from Carbon or HDS)
• Use some themes but not all

Proposed CSS file structure

If we keep the component styles and theme style separate it would improve flexibility of how consumers use the themes. They would know they always have to import the component styles, but could manage what themes they're using with more control.

This would be helpful with new projects if they are going to be built with Carbon. A team would just have to grab the component css and the root selector carbon theme css and be good to go. Maybe it could be helpful for teams wanting to use some of the themes, but not all as well.

I would still like to keep around the existing design-system-components.css that contains both the tokens and components combined so teams aren't forced into any changes, but this could be removed eventually.

This would be my proposed CSS files structure:

• Themes
  • Root selector
    • Hds
    • Cds-g0
    • Cds-g10
    • Cds-g90
    • Cds-g100
    • Unknown future theme
  • Prefers color sceme
    • Fixed at having cds-g0 for light and cds-g100 for dark
  • Combined strategies
    • Fixed at having cds-g0 for light and cds-g100 for dark
• components.css
  • Only contains components styles
• design-system-components.css
  • Legacy file that contains both HDS root tokens and component styles
  • Could be removed in the future

[KristinLBradley]

I agree with the idea of having separate "normal"/"old" CSS and themed files. I like Dylan's proposal for separating and structuring these files.

I think it's best if we plan things from an "opt-in" approach (at least to start) for consumers, in which, if they do nothing, they get what they have today. Otherwise, they have to take an explicit action to include and use themes as makes sense for their product without having to include too much unnecessary code.

[dchyun]

(this comment has some overlap with the pipeline pr)

[Suggestion][Discussion] For the combined-strategies and css-selector theming approaches, it would be beneficial to have one shared tokens file and separate files for each theme's css selector, similar to how root-selector is done. Each file for a theme would contain only it's css selector tokens.

My basis for this idea is that it's most likely that the majority of tokens are themed, and the number of shared tokens is fairly small. It's also possible we add more component tokens in the future which would also need to be themed.

Based on the assumption that the majority of our tokens will be themed, that means for every theme there will be a high number of variables within these theme selector classes. That could bloat the size of this one file by a fair amount. It's also a possibility that new themes could be added in the future (maybe it's unlikely idk how Carbon handles those things). For every theme added we would be increasing the size of this file by a good amount.

There's also the use case that a consumer does not want all the themes. Maybe they only want g10 and g100. But if they want to use the css selector method they would need to bring in the tokens for those other themes if they use this file.

If we split up these selectors so there was one file for each, a consumer could choose to import in only the ones they need, and we could limit the length of these files.

[KristinLBradley]

I like the idea of splitting of the files to reduce duplication and unnecessary code for consumers.