docs(button, buttongroup, actionbutton, actiongroup): component analysis #5788

rise-erpelding · 2025-10-06T19:57:09Z

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 components: Button, Button Group, Action Button, Action 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-1220

Screenshots (if appropriate)

N/A - Documentation only

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

Resources that might help when reviewing

Note: These urls are set for the button component.

Manual review test cases

Documentation Quality

Recommendation: It's probably easier to check out the files with proper markdown formatting. While you can change the display from source diff to rich diff within the PR, I prefer to look through the files on the branch

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
SWC attributes match actual TypeScript source files
DOM structure comparisons match template files
Implementation gaps are complete and accurate

Device review

Did it pass in Desktop?
Did it pass in (emulated) Mobile?
Did it pass in (emulated) iPad?

changeset-bot · 2025-10-06T19:57:13Z

⚠️ No Changeset found

Latest commit: 35c5f39

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-10-06T19:59:10Z

📚 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-5788

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-10-06T20:02:19Z

Tachometer results

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

cdransf · 2025-10-07T17:05:24Z

migration-roadmap/action-button.md

+### CSS => SWC implementation gaps
+
+**Missing from WC:**
+None. All CSS selectors have corresponding web component implementations.


Nit: should we remove this line break? ✨

cdransf

Looks good! Just a few nits (feel free to ignore them 😅) ✨

cdransf · 2025-10-07T17:06:54Z

migration-roadmap/action-group.md

+
+### CSS => SWC implementation gaps
+
+**Missing from WC:**


Same nit here ✨

cdransf · 2025-10-07T17:11:30Z

migration-roadmap/button.md

+```diff
+--- Legacy (CSS main branch)
+++ Spectrum 2 (CSS spectrum-two branch)
+@@ -1,18 +1,18 @@


Do we need this diff artifact? ✨

marissahuysentruyt

Nice work on this! I think the only real "changes" necessary would be a correction in the progress circle size modifier class in the Button.md file, and maybe double checking the active attribute for button as well.

The rest of my comments are either non-blocking or just questions!

marissahuysentruyt · 2025-10-08T17:53:08Z

migration-roadmap/button.md

-</button>
-```
+- `treatment` (values: `fill`, `outline`) - defaults to `fill`
+- `quiet` - boolean property that maps to `treatment` (when true, sets `treatment="outline"`)


I find this really strange to have a quiet property that just maps to a different property. Not that this is anything we can do about this now, but I do wonder why we even have this. Maybe something extends Button (that I can't find very quickly) and that thing needs quiet?

marissahuysentruyt · 2025-10-08T18:06:47Z

migration-roadmap/button.md

-    </div>
-</button>
-```
+- `icon-only` - indicates button contains only an icon without visible label


I guess I thought the button could be icon-only by just supplying an icon in the icon slot, but I see icon-only in the SWC storybook, along with the boolean binding in ButtonBase.

Speaking of ButtonBase- is there any particular migration things we would need to mention specifically for that file? That seems like it might be out-of-scope for us, but I was just curious.

marissahuysentruyt · 2025-10-08T18:09:15Z

migration-roadmap/button.md

-| `a.spectrum-Button`             | Link variant                  | Missing from WC  |
-| -                               | `pending-label` attribute     | Missing from CSS |
-| -                               | `quiet` property (deprecated) | Missing from CSS |
+- `disabled` - disables the button


There might also be an active state. That could potentially be for the link behaviors, though.

marissahuysentruyt · 2025-10-08T18:17:07Z

migration-roadmap/button.md

+    <span class="spectrum-Button-label">Label</span>

-### Action Items for Web Component Maintainers
+    <!-- Icon can also appear after label when iconAfterLabel is true -->


🤯 I didn't even know this arg existed. It's not in our story args!

marissahuysentruyt · 2025-10-08T18:20:29Z

migration-roadmap/button.md

-**Required Additions:**
+    <!-- Progress Circle (when isPending is true) -->
+    <div
+        class="spectrum-ProgressCircle spectrum-ProgressCircle--sizeS spectrum-ProgressCircle--indeterminate"


Looks like main uses .spectrum-ProgressCircle--small instead of a nice t-shirt size.

marissahuysentruyt · 2025-10-08T20:30:46Z

migration-roadmap/action-group.md

+
+```html
+<div class="spectrum-ActionGroup spectrum-ActionGroup--sizeM">
+    <button class="spectrum-ActionButton spectrum-ActionGroup-item">...</button>


This may be unnecessary, but should we show that the t-shirt size of the action group trickles down to the individual action buttons at all?

Both the CSS and SWC components already do this, so I'm good with leaving it off as it is, too.

marissahuysentruyt · 2025-10-08T20:32:09Z

migration-roadmap/action-group.md

+```
+
+</details>
+


I think I left a similar comment with button group- did we want to be super clear that CSS had no structural changes?

marissahuysentruyt · 2025-10-08T20:33:47Z

migration-roadmap/action-group.md

+| `.spectrum-ActionGroup--justified .spectrum-ActionGroup-item`                                                           | Slotted buttons when `justified`       | Implemented |
+| `.spectrum-ActionGroup:not(.spectrum-ActionGroup--vertical, .spectrum-ActionGroup--compact) .spectrum-ActionGroup-item` | Slotted buttons in regular mode        | Implemented |
+
+**Note:** In CSS templates, `.spectrum-ActionGroup-item` is applied as a class to each child button. In SWC, the group uses `::slotted(*)` to style slotted action buttons without adding an additional class.


Nice! This note is a really great reminder. ❤️

marissahuysentruyt · 2025-10-08T20:59:22Z

migration-roadmap/action-button.md

+| `.spectrum-ActionButton--sizeL`  | `size="l"`                      | Implemented |
+| `.spectrum-ActionButton--sizeXL` | `size="xl"`                     | Implemented |
+
+#### Variants and treatments


Love the attribute column here! This is what I was thinking of when I made that other comment in button! 😍

marissahuysentruyt · 2025-10-08T21:00:55Z

migration-roadmap/action-button.md

+#### WC-only attributes
+
+| SWC attribute | CSS equivalent | Notes                                         |
+| ------------- | -------------- | --------------------------------------------- |
+| `toggles`     | N/A            | Manages selected state automatically on click |
+| `value`       | N/A            | Used for identification in action groups      |
+| `role`        | N/A            | Dynamic ARIA role management                  |


This is a great idea- I might have to steal it 😊

rise-erpelding added 4 commits October 6, 2025 11:38

docs: button component analysis

4a6f1c4

docs: button group component analysis

43ab0da

docs: action button component analysis

6d169b0

docs: action button group component analysis

35c5f39

rise-erpelding self-assigned this Oct 6, 2025

rise-erpelding added Documentation 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. labels Oct 6, 2025

rise-erpelding changed the base branch from main to 2nd-gen-component-analysis October 6, 2025 19:57

rise-erpelding changed the title ~~Rise erpelding/swc 1220 buttons migration docs~~ docs(button, buttongroup, actionbutton, actiongroup): component analysis Oct 6, 2025

rise-erpelding added the ready-for-review label Oct 6, 2025

rise-erpelding marked this pull request as ready for review October 6, 2025 19:59

rise-erpelding requested a review from a team as a code owner October 6, 2025 19:59

cdransf reviewed Oct 7, 2025

View reviewed changes

cdransf approved these changes Oct 7, 2025

View reviewed changes

marissahuysentruyt requested changes Oct 8, 2025

View reviewed changes

		```

		</details>

docs(button, buttongroup, actionbutton, actiongroup): component analysis #5788

Are you sure you want to change the base?

docs(button, buttongroup, actionbutton, actiongroup): component analysis #5788

Conversation

rise-erpelding commented Oct 6, 2025 • edited by marissahuysentruyt 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

Resources that might help when reviewing

Manual review test cases

Documentation Quality

Cross-Reference Accuracy

Device review

Uh oh!

changeset-bot bot commented Oct 6, 2025

⚠️ No Changeset found

Uh oh!

github-actions bot commented Oct 6, 2025

📚 Branch Preview

🔍 Visual Regression Test Results

Uh oh!

github-actions bot commented Oct 6, 2025

Tachometer results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cdransf 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!

marissahuysentruyt 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!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rise-erpelding commented Oct 6, 2025 •

edited by marissahuysentruyt

Loading