docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap #5729

marissahuysentruyt · 2025-09-15T20:58:26Z

Description

Creates AI-generated migration documentation to analyze component differences to guide SWC migration to S2, with human vetting. The documentation serves as a bridge between the migrated Spectrum 2 CSS work and the corresponding web components, in order to help engineers understand what needs to be implemented, updated, or aligned between the two systems to guide the development of 2nd generation web components.

This batch is for the following components: Checkbox, Radio, Switch, Field group

Motivation and context

Clear development roadmap: Provides comprehensive feature gap analysis for building 2nd generation web components
Implementation requirements: Identifies all features and capabilities that need to be implemented to match Spectrum 2 CSS and design specs
Breaking change transparency: Establishes implementation requirements and design changes that may lead to breaking changes and/or API changes for the next major version
Adoption planning: Enables developers and consuming teams to plan for 2nd gen web component adoption and understand migration effort required

Related issue(s)

SWC-1217

Screenshots (if appropriate)

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
~~I have added automated tests to cover my changes.~~
~~I have included a well-written changeset if my change needs to be published.~~
I have included updated documentation if my change required it.

Reviewer's checklist

Includes a Github Issue with appropriate flag or Jira ticket number without a link
~~Includes thoughtfully written changeset if changes suggested include patch, minor, or major features~~
~~Automated tests cover all use cases and follow best practices for writing~~
~~Validated on all supported browsers~~
~~All VRTs are approved before the author can update Golden Hash~~

Manual review test cases

Testing Checklist

Field group: Confirm all selectors, mods, and attributes are documented; Verify "No structural differences" statements for CSS; Verify label positioning gap and missing container and class callouts
Checkbox: Confirm all selectors, mods, and attributes are documented; Verify "No missing features" & "No structural differences" statements for CSS
Radio: Confirm all selectors, mods, and attributes are documented; Verify "No missing features" & "No structural differences" statements for CSS
Switch: Confirm all selectors, mods, and attributes are documented; Verify "No missing features" & "No structural differences" statements for CSS

Documentation Quality

All files follow template structure with proper collapsible sections
CSS => SWC mapping tables use correct status values
Summary sections are concise and actionable
No broken markdown syntax

Cross-Reference Accuracy

CSS selectors match actual metadata.json files for S2
SWC attributes match actual TypeScript source files
DOM structure comparisons match template files
Implementation gaps are complete and accurate

changeset-bot · 2025-09-15T20:58:30Z

⚠️ No Changeset found

Latest commit: 68b3d3a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2025-09-15T21:00:53Z

📚 Branch Preview

🔍 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-5729

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

github-actions · 2025-09-15T21:06:56Z

Tachometer results

Currently, no packages are changed by this PR...

marissahuysentruyt · 2025-09-18T18:55:53Z

migration-roadmap/checkbox.md

+|                                                                                             | `name` attribute                                     | Missing from CSS |
+|                                                                                             | `tabindex` attribute                                 | Missing from CSS |
+|                                                                                             | `autofocus` attribute                                | Missing from CSS |


Are these something we think is worth mentioning? Would CSS ever come back and implement these attributes?

marissahuysentruyt · 2025-09-18T18:58:17Z

migration-roadmap/checkbox.md

+### CSS => SWC implementation gaps
+
+**New for S2:**
+The checkbox component in Spectrum 2 has the new down state (active) perspective shift applied. Additionally, the checkbox CSS was expanded to ensure coverage of a variety of interactive and variant states: hover, focus-visible, hover+disabled, checked+disabled, focus-visible+checked+hover, indeterminate+invalid, invalid+focused, disabled+read-only, etc.


I think the down state was the "biggest" thing that was added to checkbox. If I remember correctly, there's some open questions still about whether or not the invalid checkbox has a red border, or if we rely on negative help text only.

Anyways, is the down state and expansion of testing worth mentioning at all? The down state is mainly CSS, but we do use JS to calculate those properties for some components. The testing bit...I think I'm on the side of removing it.

Let's definitely mention invalid checkbox as a consideration, even if it ends up not changing, it's probably valuable to call out as we migrate, especially if we work in squads where design is involved as with app frame side nav.

Otherwise, I think the CSS-specific stuff (notes about improved test coverage, things that are present in SWC but missing in CSS) aren't really very valuable, and they probably wouldn't be missed if taken out.

marissahuysentruyt · 2025-09-18T18:59:43Z

migration-roadmap/radio.md

+| `.spectrum-Radio-label`                                                                              | Default slot content                     | Implemented      |
+| `.spectrum-Radio-label:lang(ja)`, `.spectrum-Radio-label:lang(ko)`, `.spectrum-Radio-label:lang(zh)` | Language-specific styling                | Implemented      |
+| `.spectrum-Radio.is-readOnly`                                                                        | `readonly` attribute                     | Implemented      |
+|                                                                                                      | `invalid` attribute                      | Missing from CSS |


This is similar to the checkbox, where I think instead of putting invalid on the radio, we pass that arg/property to the help text instead. So radio itself doesn't really have an invalid state- the radio group has an invalid state that is shown via negative help text.

rise-erpelding

This is a pretty straightforward set of components! Just a few tiny comments here and then I think this one will be good to go!

rise-erpelding · 2025-09-19T19:50:45Z

migration-roadmap/checkbox.md

+### CSS => SWC implementation gaps
+
+**New for S2:**
+The checkbox component in Spectrum 2 has the new down state (active) perspective shift applied. Additionally, the checkbox CSS was expanded to ensure coverage of a variety of interactive and variant states: hover, focus-visible, hover+disabled, checked+disabled, focus-visible+checked+hover, indeterminate+invalid, invalid+focused, disabled+read-only, etc.


Let's definitely mention invalid checkbox as a consideration, even if it ends up not changing, it's probably valuable to call out as we migrate, especially if we work in squads where design is involved as with app frame side nav.

Otherwise, I think the CSS-specific stuff (notes about improved test coverage, things that are present in SWC but missing in CSS) aren't really very valuable, and they probably wouldn't be missed if taken out.

rise-erpelding · 2025-09-19T20:01:29Z

migration-roadmap/field-group.md

+<div class="group" role="presentation">
+    <slot @slotchange="handleSlotchange"></slot>
+</div>
+<!-- Help text rendered via renderHelpText() method -->


I like the way this is done!

rise-erpelding · 2025-09-19T20:07:55Z

migration-roadmap/field-group.md

+| `.spectrum-FieldGroup--sidelabel`  | Layout variant                       | Missing from WC                |
+| `.spectrum-FieldGroup--toplabel`   | Layout variant                       | Missing from WC                |
+| `.spectrum-FieldGroupInputLayout`  | Internal layout container            | Missing from WC                |
+| `.spectrum-FieldGroup-item`        | Individual field item classes        | Missing from WC                |


I've been leaving the comment on all the PRs that we should include some kind of quick comment on why it's missing from WC like

Suggested change

| `.spectrum-FieldGroup-item` | Individual field item classes | Missing from WC |

| Missing from WC (new for Spectrum 2) |

But I feel like in this case it's a little bit more complicated than that. The side label and top label I think is more of an implementation gap and we could note that, but for the layout classes, I can't think of a quick way to explain that in the table.

rise-erpelding · 2025-09-19T20:09:08Z

migration-roadmap/field-group.md

+- `.spectrum-FieldGroupInputLayout` wrapper container is not generated by the web component.
+- `.spectrum-FieldGroup-item` classes are not automatically applied to slotted elements.


Maybe just a smidge more explanation on why SWC might want to incorporate these, I'm assuming we have these to make the layout work properly.

marissahuysentruyt added 4 commits September 11, 2025 15:17

docs(checkbox): migration roadmap

15f6d23

docs(fieldgroup): migration roadmap

796514f

docs(radio): migration roadmap

480ab56

docs(switch): migration roadmap

572eb9b

marissahuysentruyt self-assigned this Sep 15, 2025

marissahuysentruyt changed the title ~~Marissahuysentruyt/swc 1217 switch radio checkbox~~ docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap Sep 16, 2025

marissahuysentruyt force-pushed the marissahuysentruyt/swc-1217-switch-radio-checkbox branch from 0d65ef2 to 8178de2 Compare September 17, 2025 21:58

docs: updates checkbox roadmap

5382143

marissahuysentruyt force-pushed the marissahuysentruyt/swc-1217-switch-radio-checkbox branch from aa004aa to a62d03f Compare September 18, 2025 18:39

marissahuysentruyt added 3 commits September 18, 2025 14:44

docs: updates field group roadmap

7e19c27

docs: updates radio roadmap

7e64b64

docs: update switch road map

68b3d3a

marissahuysentruyt force-pushed the marissahuysentruyt/swc-1217-switch-radio-checkbox branch from a62d03f to 68b3d3a Compare September 18, 2025 18:44

marissahuysentruyt commented Sep 18, 2025

View reviewed changes

marissahuysentruyt marked this pull request as ready for review September 18, 2025 19:07

marissahuysentruyt requested a review from a team as a code owner September 18, 2025 19:07

rise-erpelding reviewed Sep 19, 2025

View reviewed changes

marissahuysentruyt added Documentation ready-for-review labels Sep 19, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap #5729

docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap #5729

marissahuysentruyt commented Sep 15, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Sep 15, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Sep 15, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Sep 15, 2025

Uh oh!

marissahuysentruyt Sep 18, 2025

Uh oh!

marissahuysentruyt Sep 18, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

marissahuysentruyt Sep 18, 2025

Uh oh!

rise-erpelding left a comment

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

Uh oh!

	\| `.spectrum-FieldGroup-item` \| Individual field item classes \| Missing from WC \|
	\| Missing from WC (new for Spectrum 2) \|

		- `.spectrum-FieldGroupInputLayout` wrapper container is not generated by the web component.
		- `.spectrum-FieldGroup-item` classes are not automatically applied to slotted elements.

docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap #5729

Are you sure you want to change the base?

docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap #5729

Conversation

marissahuysentruyt commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Reviewer's checklist

Manual review test cases

Testing Checklist

Documentation Quality

Cross-Reference Accuracy

Uh oh!

changeset-bot bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview

🔍 Visual Regression Test Results

Uh oh!

github-actions bot commented Sep 15, 2025

Tachometer results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rise-erpelding left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marissahuysentruyt commented Sep 15, 2025 •

edited

Loading

changeset-bot bot commented Sep 15, 2025 •

edited

Loading

github-actions bot commented Sep 15, 2025 •

edited

Loading