[04-Part2] [Project Solar / Phase 1 / Showcase] Add support for theming and theme-switching to the showcase

[didoo]

Important

This PR is the same as #3240 but because it was accidentally closed, we need to continue the review process in this second PR.

📌 Summary

This PR contains multiple pieces of the "theming" puzzle:

HDS Components:

• implementation of an hdsTheming service
• implementation of a (temporary) HdsThemeSwitcher component
• implementation of a "headless" HdsThemeContext component

Showcase

• updated the showcase to support light/dark themes, to go hand-in-hand with the HDS "carbonized" light/dark themes
• the implementation of a shwTheming service and set of showcase controls to switch theming (and theming options) plus the CSS file linked in the application
• the implementation of a "Foundations > Theming" showcase page, plus a frameless demo page (with HDS theme switcher instances, contextual theming demos, and dark HDS components) to demonstrate how theming applies to different HDS components and a mock application in general

This is based on top of #3259

🛠️ Detailed description

The first commits are a direct porting of previous showcase theming explorations (squashed):

• 🧪 [Spike] Get theming “support” in the Showcase app - First scrappy iteration #2589
• 🧪 [Spike] Theming “support” in HDS and Showcase - Aggregated #2611
• 🧪 [Spike] Theming “support” in HDS and Showcase - Designers' playground #2608

After the initial cherry picking of code, there's been a lot of back and forth / refactorings, with different attempts in reaching an implementation that could (hopefully) withstand how different teams may want to adopt theming in their codebases. For this reason, the bulk of the work has been around finding the right "location" for the different pieces of logic, the different concerns: what goes into the HDS theming service vs the SHW theming service; how theming preferences are expressed in the UI and controlled by the user; how consumers decisions are reflected and stored and passed over between HDS/SHW services and components; how a user would use the theming controls (including a showcase user/developer/designer) and how a consumer would allow that user to interact with the application.

It's impossible to describe in detail all the code changes and implementations introduced in this PR, you have to look at diff in code, the showcase application, the "how to review" and "how to test" sections below, and try to get a general picture of what went into this PR.

👉 👉 👉 Preview: theming page

🔎 How to review

This is a quite large PR (we may consider splitting it). I would suggest to look at a piece of code/logic (eg. HDS theming service), see how this interacts with the rest of the code (in HDS and/or in the showcase), and in parallel I would try to see in the showcase application how this logic is reflected in the UI, and try to interact with it to see what happens.

The "logical" order in which I would look at things is this:

• start to look at the hdsTheming service and the HdsThemeSwitcher and HdsThemeContext components under packages/components
• move on to the shwTheming service under showCase and see how it's an extension of the hdsTheming
• look at the ShwThemeSwitcher controls (component and sub-components) and see how they're using internally both the hdsTheming and shwTheming services, how the "current" theming options are reflected in the services and in the controls values/states, what happens when a control value is updated/applied, etc
• see how the showcase has now a small set of themed CSS variables for its colors, so it can respond to the theming changes in the controls/switchers (and how the "static" color values have been replaced across the existing pages/components)
• look at the foundations/theming showcase page, and its sections
  • the first one is a showcase of the HdsThemSwitcher component
  • the second section is used to test how "contextual theming" (applying a theme at "local" level via a class or data attribute) works, even when nested
  • the third section shows how the HDS "themed" components work (at the moment we have not decided yet how they will be handled in a themed application, but for now at least we have them collected in a single place)
  • the last section links to a frameless demo of a mock application with a collection of the most common HDS components
• see how some of the "Mock" components and pages had to be updated, to accomodate for changes to the AppSideNav (where we've added a theme switcher) and to add even more "mock" UI elements to test with theming
• look at the temporary files in the public/assets/styles/@hashicorp/ folder, in particular the CSS selectors, and see if they make sense

🛠️ How to test

Launch the showcase application locally, then visit the "Foundations > Theming" page. Here play with the controls in the top right of the page, and see how changing them impacts the page:

• try to change the theming (you have multiple option groups and options, corresponding to the different way the consumers may want to adopt/use the HDS theming
• try to change theming via the HDS theme switcher and see how this is reflected in the SHW controls
• open the advanced options settings and see how setting/applying them see
• look at the local storage in the devtools, and see how the values get updated when the different options are chosen/set
• look at the different sections of the theming page and see how theming and theming options apply (or don't) to them
• try to apply different themes to other showcase page (in this case, since the theming tokens are only partially defined, don't expect proper theming switch, the component will look broken)

If you want to double check how the tokens and their values are applied depending on the chosen theme/options, you can update the colors in the temporary/testing CSS files under the public/assets/styles/@hashicorp/ folder (see the CSS variables under the added these to test theming in the showcase comment)

🔗 External links

Jira tickets:

• https://hashicorp.atlassian.net/browse/HDS-5518
• https://hashicorp.atlassian.net/browse/HDS-5532

---

👀 Component checklist

• Percy was checked for any visual regression
  • both the visual regressions highlighted by Percy are expected, since we haven't rebased on main yet to avoid having issues in testing with the (breaking) version 5.0+ in the consumers' codebases
• 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	Nov 28, 2025 1:46pm
hds-website	Ready	Preview	Nov 28, 2025 1:46pm

[Copilot]

Pull request overview

This PR implements comprehensive theming support for the Helios Design System, including theme switching capabilities in both the HDS components library and the showcase application. The changes enable light/dark theme support with multiple implementation options (CSS selectors, system preferences) and provide developer tools for testing and demonstrating theming functionality.

Key Changes

• Added hdsTheming service for managing theme state and options
• Implemented HdsThemeSwitcher and HdsThemeContext components for theme control
• Created showcase-specific theming infrastructure with shwTheming service and controls
• Added a dedicated "Foundations > Theming" showcase page with demos and examples

Reviewed changes

Copilot reviewed 68 out of 70 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
packages/components/src/services/hds-theming.ts	Core theming service managing theme state and localStorage persistence
packages/components/src/components/hds/theme-switcher/index.ts	Theme switcher dropdown component implementation
packages/components/src/components/hds/theme-context/index.ts	Headless component for applying contextual themes
showcase/app/services/shw-theming.ts	Showcase theming service extending HDS theming
showcase/app/components/shw/theme-switcher/index.gts	Showcase theme switcher with advanced options
showcase/app/index.html	HTML head updates for multiple stylesheet support
showcase/app/styles/showcase-theming/index.scss	Showcase-specific themed color variables
showcase/public/assets/styles/@hashicorp/themed-tokens/	Temporary CSS files for testing different theming approaches