chore(button-group): 2nd-gen migration plan by Rajdeepc · Pull Request #6333 · adobe/spectrum-web-components

Rajdeepc · 2026-05-25T06:24:28Z

Summary

Created the Phase 1 migration plan for button-group (1st-gen → 2nd-gen), documenting the full API surface, breaking changes, 2nd-gen API decisions, architecture, and testing plan
Included Figma S2 Desktop reference screenshot capturing design properties and variants
Registered the migration plan in the components README navigation

Motivation

This is the planning ticket (SWC-2073) for the button-group 2nd-gen migration epic (SWC-2071). The plan must be reviewed and approved before any implementation work begins.

What this covers

1st-gen API documented

Properties: vertical (boolean), size (s/m/l/xl via SizedMixin)
Single default slot for sp-button children
Size propagation to slotted buttons
CSS token-based flex layout

2nd-gen API decisions

Breaking: vertical → orientation property ("horizontal" | "vertical") aligned with React Spectrum S2
A11y required: Add role="group" and aria-orientation (missing in 1st-gen)
New: disabled attribute for group-level disable propagation
Default size: Introduce "m" as default (1st-gen had no default)

Architecture

Core/SWC split following Badge migration reference pattern
Core: validation, ARIA management, size/disabled propagation
SWC: rendering (slot), CSS, element registration, stories, tests

Open questions requiring team input

Q1: Should XL size be supported? (Figma shows it; React S2 limits to S/M/L)
Q2: Should overflow behavior (auto-switch to vertical) be MVP or deferred?
Q3: Should align property be MVP or additive?

Related issues

Epic: SWC-2071
This ticket: SWC-2073
Accessibility recommendations: SWC-2072
Implementation: SWC-2074

References

Test plan

Migration plan reviewed by at least one other engineer
Open questions (Q1–Q3) discussed and resolved
Verify all links in the plan resolve correctly
Confirm Figma reference screenshot is visible

- document 1st-gen API surface (vertical, size, slot, CSS tokens) - define 2nd-gen API decisions aligned with React Spectrum S2 and Figma - identify breaking change: vertical boolean replaced by orientation property - capture accessibility requirements from migration analysis (role=group, aria-orientation, no roving tabindex) - include Figma S2 Desktop reference screenshot - flag open questions for XL size support and overflow behavior scope - register migration plan in components README navigation Epic: SWC-2071 Ref: SWC-2073 Co-authored-by: Cursor <cursoragent@cursor.com>

changeset-bot · 2026-05-25T06:24:32Z

⚠️ No Changeset found

Latest commit: 3778527

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

- binary assets should not be committed to the repository Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-05-25T06:32:37Z

📚 Branch Preview Links

🔍 First Generation 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-6333

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.

5t3ph · 2026-05-26T15:04:59Z

+- **Add `role="group"` and `aria-orientation`** on the host for WCAG compliance (1st-gen is missing this).
+- **Add `align` property** for button alignment (start/center/end); matches React S2.
+- **Propagate disabled state** from group to children via an optional `disabled` attribute.
+- **Overflow behavior (auto-switch to vertical)** is documented in React S2 but is not in the Figma design spec; flagged as an open question and out of scope for MVP unless decided otherwise.


I was hoping this could be achieved with flex layout and maybe some kind of container query, but it seems it would need ResizeObserver for the most dependable switch, unless regular flex wrapping would be acceptable vs. the all-at-once orientation switch. Since we aren't controlling arrow key navigation, regular flex wrapping may be an acceptable starting point?

5t3ph · 2026-05-26T15:06:42Z

+Button group is a simple layout and semantics wrapper for related button actions. The 1st-gen implementation is minimal (flexbox container with size propagation), making the migration straightforward. The core changes are:
+
+- **Rename `vertical` boolean to `orientation` property** (aligns with React Spectrum S2 and Figma); this is the only consumer-facing breaking change.
+- **Add `role="group"` and `aria-orientation`** on the host for WCAG compliance (1st-gen is missing this).


Since we are not coupling focus group type of behaviors, I don't think aria-orientation makes sense to include since it is intended to convey direction of arrow key navigation, which the component will not be enforcing. I know it was in the a11y plan, but I think it was an oversight after that plan was updated to remove inclusion of focus group.

5t3ph · 2026-05-26T15:14:28Z

+
+### Most blocking open questions
+
+- Q1 in [Design](#design): Should XL size be supported in 2nd-gen? Figma shows it but React S2 limits to S/M/L.


This is incorrect, React also has XL. Also is stands to reason it should support any sizes Button supports since the "group" doesn't resize, it just passes off the size to each Button.

5t3ph · 2026-05-26T15:22:07Z

+
+| #   | Item | Blocking? | Status | Owner |
+| --- | ---- | --------- | ------ | ----- |
+| **Q1** | Should `size="xl"` be supported in 2nd-gen? Figma S2 Desktop shows XL but React S2 limits to S/M/L. The spectrum-css `spectrum-two` branch only defines spacing for default and sizeS; no dedicated XL token. **Recommendation:** Align with React S2 (S/M/L only) and treat XL as additive/deferred. | Yes — affects type definition and test matrix | Open | Design + implementation |


As noted earlier, React does have XL. Size S uses an 8px gap and the rest use a 12px gap, so the same token as used for M-L can also be used for XL.

- Remove aria-orientation: not valid on role="group" since button-group does not implement focus group / arrow-key navigation - Resolve Q1: XL is supported by React S2 and uses same 12px gap token as M/L; mark as confirmed in type definition - Update Q2: incorporate feedback that regular flex wrapping may be an acceptable starting point; mark as deferred from MVP Co-authored-by: Cursor <cursoragent@cursor.com>

…c-2073

5t3ph

…c-2073

Rajdeepc requested a review from a team as a code owner May 25, 2026 06:24

Rajdeepc self-assigned this May 25, 2026

Rajdeepc added Status:Ready for review PR ready for review or re-review. 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. labels May 25, 2026

fix(button-group): remove figma screenshot from repo

c34a62a

- binary assets should not be committed to the repository Co-authored-by: Cursor <cursoragent@cursor.com>

Rajdeepc changed the title ~~[Button Group] 2nd-gen migration plan~~ chore(button-group): 2nd-gen migration plan May 25, 2026

Rajdeepc added the Component:Documentation Issues or PRs involving changes to docs or docs website. Component prefix is for Jira integration. label May 25, 2026

5t3ph reviewed May 26, 2026

View reviewed changes

cdransf approved these changes May 26, 2026

View reviewed changes

pfulton assigned cdransf and 5t3ph May 28, 2026

caseyisonit added the Status:Addressing feedback PR owner is addressing review comments and will change label back to "Ready for review" when ready. label May 28, 2026

Rajdeepc requested a review from 5t3ph May 29, 2026 04:29

Merge branch 'main' into rajdeepc/docs-button-group-migration-plan-sw…

17dd339

…c-2073

5t3ph approved these changes May 29, 2026

View reviewed changes

Merge branch 'main' into rajdeepc/docs-button-group-migration-plan-sw…

3778527

…c-2073

Rajdeepc merged commit a1d2ec7 into main Jun 1, 2026
29 checks passed

Rajdeepc deleted the rajdeepc/docs-button-group-migration-plan-swc-2073 branch June 1, 2026 06:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(button-group): 2nd-gen migration plan#6333

chore(button-group): 2nd-gen migration plan#6333
Rajdeepc merged 5 commits into
mainfrom
rajdeepc/docs-button-group-migration-plan-swc-2073

Rajdeepc commented May 25, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented May 25, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 25, 2026 •

edited

Loading

Uh oh!

5t3ph May 26, 2026

Uh oh!

5t3ph May 26, 2026

Uh oh!

5t3ph May 26, 2026

Uh oh!

5t3ph May 26, 2026

Uh oh!

5t3ph left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		### Most blocking open questions

		- Q1 in [Design](#design): Should XL size be supported in 2nd-gen? Figma shows it but React S2 limits to S/M/L.

Conversation

Rajdeepc commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

What this covers

1st-gen API documented

2nd-gen API decisions

Architecture

Open questions requiring team input

Related issues

References

Test plan

Uh oh!

changeset-bot Bot commented May 25, 2026 • 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 May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

Uh oh!

5t3ph May 26, 2026

Choose a reason for hiding this comment

Uh oh!

5t3ph May 26, 2026

Choose a reason for hiding this comment

Uh oh!

5t3ph May 26, 2026

Choose a reason for hiding this comment

Uh oh!

5t3ph May 26, 2026

Choose a reason for hiding this comment

Uh oh!

5t3ph left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Rajdeepc commented May 25, 2026 •

edited

Loading

changeset-bot Bot commented May 25, 2026 •

edited

Loading

github-actions Bot commented May 25, 2026 •

edited

Loading