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

[rise-erpelding]

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.

• CSS Storybook (Legacy)
• CSS Spectrum 2 Preview (this is the preview of what's on the spectrum-two branch)
• CSS Metadata.json in spectrum-two
• SWC Docs site
• SWC Storybook

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]

⚠️ No Changeset found

Latest commit: e398958

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]

📚 Branch Preview

• Documentation Site
• Storybook

🔍 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:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

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]

Tachometer results

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

[cdransf]

Nit: should we remove this line break? ✨

[rise-erpelding]

Can you elaborate? Like should it be:

**Missing from WC:** None. All CSS selectors have corresponding web component implementations.

or:

**Missing from WC:**
None. All CSS selectors have corresponding web component implementations.

or:

**Missing from WC:**
None. All CSS selectors have corresponding web component implementations.

[cdransf]

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

[cdransf]

Same nit here ✨

[cdransf]

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]

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?

[rise-erpelding]

🤷‍♀️ Maybe just to alias it? It seems like a legacy thing. Noting it in implementation gaps as well.

    /**
     * Style this button to be less obvious
     */
    @property({ type: Boolean })
    public set quiet(quiet: boolean) {
        this.treatment = quiet ? 'outline' : 'fill';
    }

[marissahuysentruyt]

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]

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

[marissahuysentruyt]

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

[rise-erpelding]

I thought it was a nice callout too! I'm hoping we didn't miss this with any of the other components we've already done.

[marissahuysentruyt]

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

[marissahuysentruyt]

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

[marissahuysentruyt]

Looks great! All of my comments look to be addressed- thank you!