[WIP-05] [Project Solar / Phase 1 / Showcase] Scaffolding of the showcase pages for the carbonization of the HDS components

[didoo]

📌 Summary

This PR is the initial scaffolding of the showcase pages that will be used for the dry-run migrations (and subsequent actual migration) of the HDS components (as in theming/re-skinning).

This PR is based on top of #3240.

🛠️ Detailed description

In this PR I have:

• introduced a new <ShwCarbonizationComparisonGrid> component, used to showcase an HDS component with different themes applied (HDS standard + the four Carbon themes g0/g10/g90/g100) next to the equivalent Carbon web components for that specific variant/state.
• added a set of "carbonized" showcase pages, dedicated to showing all the (meaningful) variants/states of a foundation or component, and compare them with the expected look&feel of the original equivalent Carbon component
  • Note: in this early phase, they are intentionally left as single file, even if they're quite long; later when we have a better idea of what we want to do and we start to see emerging patterns, we can decide what should be the final implementation for these pages
• updated the showcase/app/index.html file to include the scripts (and the hiding styles for the not-yet-loaded web components)

🔎 How to review

Note

This is not the final implementation, there will be likely things we will want to change/update, once we start to work on the dry-run migrations; these changes will likely be done in follow-up PRs.

Check the different carbonized pages and how they've been implemented (also their organization as single file .gts components):

• Foundations > Color
• Foundations > Typography
• Foundations > Focus Ring
• Components > Badge
• Components > Badge Count
• Components > Button
• Components > Form / TextInput
• Components > SegmentedGroup

Review the implementation of the <ShwCarbonizationComparisonGrid> component, and see if the API is clear to you; look also at how it's used across the "carbonized" showcase pages

Review how the Carbon Web components are instantiated in the code, and how Carbon theming is applied to them

Note: at the moment there's an open conversation about how to use the cds-icon web component in an Ember app, that has not been resolved yet, so we're using the HdsIcon component instead

👉 👉 👉 Previews:

• Index
• Carbonization > Color
• Carbonization > Typography
• Carbonization > Focus-ring
• Carbonization > Badge
• Carbonization > BadgeCount
• Carbonization > Button
• Carbonization > Form::TextInput
• Carbonization > SegmentedGroup

🛠️ How to test

Note

At the moment the HDS component look the same for the different themes, because the underlying design tokens are all the same; once we start the dry-run migrations (in a follow-up PR) they will start to (should) look more and more like the equivalent Carbon web components shown below

Open the different "carbonized" pages and see how the HDS components are rendered, and how the Carbon Web components are rendered

🗒️ TODOs

• ask help to the Carbon team to
  • understand what to do with the icons (how to use directly the Carbon icons)
  • understand how to consume the Carbon Web Components, without having to manually include the compiled files in the showcase/app/index.html file, but importing and instantiating them using the npm packages/dependencies.

🔗 External links

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

---

👀 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 21, 2025 5:43pm
hds-website	Ready	Preview	Oct 21, 2025 5:43pm

[Copilot]

Pull Request Overview

This PR scaffolds showcase pages for the carbonization (theming/re-skinning) of HDS components. It introduces infrastructure to compare HDS components with different Carbon themes against their equivalent Carbon web components, supporting the dry-run migration phase.

Key changes:

• Introduces a new <ShwCarbonizationComparisonGrid> component for side-by-side theme comparisons
• Adds carbonization showcase pages for foundations (Color, Typography, Focus Ring) and components (Badge, BadgeCount, Button, Form/TextInput, SegmentedGroup)
• Integrates Carbon Web Components via CDN and sets up Carbon theming infrastructure

Reviewed Changes

Copilot reviewed 36 out of 44 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
showcase/package.json	Adds Carbon dependencies (@carbon/grid, @carbon/layout, @carbon/themes, @carbon/type, @carbon/web-components, @ibm/plex)
showcase/app/index.html	Integrates Carbon Web Components via CDN scripts and theming stylesheets
showcase/app/router.ts	Adds routes for carbonization pages under foundations and components
showcase/app/templates/index.hbs	Adds navigation links to carbonization pages
showcase/app/components/shw/carbonization/comparison-grid/index.gts	Implements main comparison grid component for displaying themed variations
showcase/app/components/shw/carbonization/comparison-grid/item.gts	Implements individual grid item with theme-specific styling
showcase/app/components/page-foundations/color/carbonization.gts	Showcases color tokens across themes
showcase/app/components/page-foundations/typography/carbonization.gts	Showcases typography styles across themes
showcase/app/components/page-foundations/focus-ring/carbonization.gts	Showcases focus ring styles across themes
showcase/app/components/page-components/badge/carbonization.gts	Showcases Badge component variations
showcase/app/components/page-components/badge-count/carbonization.gts	Showcases BadgeCount component variations
showcase/app/components/page-components/button/carbonization.gts	Showcases Button component variations
showcase/app/components/page-components/form/text-input/carbonization.gts	Showcases TextInput component variations
showcase/app/components/page-components/segmented-group/carbonization.gts	Showcases SegmentedGroup component variations
showcase/app/styles/app.scss	Imports carbonization-related SCSS modules
showcase/app/styles/showcase-components/carbonization/*.scss	Adds styling for carbonization components and theming

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[dchyun]

Overall think the approach works really well. The new comparison grid set up is nice from an API standpoint, and the layout will make it easy to pick things up in visual regression testing. Just have some more minor feedback, and comments on specific pages.

[dchyun]

[Issue] When the global showcase theme is not set to a CSS selector option, the theming classes for each theme example are not being applied, because the CSS file that contains their styling is not being loaded.

We may have to have some encapsulation for these carbonization pages that isolates them from the broader theming being set in the showcase. We would have to load the css selector theming files always on these pages for these theme example to pick up the right tokens.

Ideally these theme examples should not change at all depending on the broader global theme set, and should be isolated examples.

Using standard HDS themeing

Using css selector HDS theming

[dchyun]

[Nit] Because these labels are inside the element where the theming classes are applied, they are getting themed as well even though they are outside of the item-content. Ideally all the labels should be the same across the theme examples. If those theming classes could be moved to only apply to the item-content that would fix it.

[dchyun]

Suggested change

	class="hds-typography-{{style}} hds-font-weight-{{weight}}"
	class="hds-typography-{{style}} hds-font-weight-{{weight}} hds-foreground-primary"

[Suggestion] Setting the text color here to an HDS token instead of the showcase default theme, makes the examples more isolated from any theming that happens on the showcase level. You could have the situation where the background of the example is fixed at a value specific to that theme, but the text is changing color based on the showcase global theme.

[dchyun]

Note: If this class is added, currently it's still getting overridden by the showcase theme text due to the body.page-foundations-typography p[class^=hds-] selector so some tweaks would be needed there as well.

[dchyun]

Suggested change

	--content-background-color: var(--token-color-surface-primary);
	--content-background-color: #fff;

[Suggestion] I would make this hard-coded. When set to the hds variable, if that hds variable updates to some other themed value based on the global showcase theme set, then the background of the theme example updates as well. Ideally it should be static and not change.