docs(tabs): Added consumer migration guide for swc-tabs by Rajdeepc · Pull Request #6267 · adobe/spectrum-web-components

Rajdeepc · 2026-05-11T14:25:13Z

Description

Adds a consumer-facing migration guide (consumer-migration-guide.mdx) for the swc-tabs component suite, following the same structure established by illustrated-message and other 2nd-gen components.

The guide provides application developers with everything needed to migrate from sp-tabs/sp-tab/sp-tab-panel to swc-tabs/swc-tab/swc-tab-panel.

Motivation and context

Consumers upgrading from Spectrum 1 to Spectrum 2 need clear, scannable documentation on what changed and what to update in their product code. This guide ships alongside the component source so it renders in Storybook at Components/Tabs/Consumer migration guide.

Related issue(s)

Related to feat(tabs): migrate tabs component to 2nd-gen #6183

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

Manual review test cases

Verify the MDX renders correctly in Storybook
1. Run yarn storybook:2nd-gen
2. Navigate to Components > Tabs > Consumer migration guide
3. Confirm all sections render (What changed tables, code blocks, callouts, checklist)
Verify all before/after code examples are accurate
1. Review each code snippet against the actual component API
2. Confirm attribute names (tab-id, accessible-label, keyboard-activation, density) match implementation
3. Confirm removed attributes (auto, compact, quiet, emphasized, size) are correctly listed

Device review

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

Accessibility testing checklist

Keyboard — This is a documentation-only change with no interactive components. No keyboard testing required.
Screen reader — This is a documentation-only change. No screen reader testing required. The guide itself documents accessibility requirements for consumers (e.g. accessible-label usage, aria-label for icon-only tabs).

Made with Cursor

changeset-bot · 2026-05-11T14:25:19Z

⚠️ No Changeset found

Latest commit: db90778

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 · 2026-05-11T14:34:45Z

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

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.

Provides application developers with a complete migration guide from sp-tabs to swc-tabs, covering renamed attributes (value→tab-id, label→accessible-label), new enum properties (keyboard-activation, density), removed APIs, accessibility changes, and public styling hooks. Removes the legacy migration.md (non-standard format, only existed in tabs) in favor of the standardized consumer-migration-guide.mdx pattern used across all 2nd-gen components. Co-authored-by: Cursor <cursoragent@cursor.com>

rubencarvalho · 2026-05-12T10:36:54Z

+import '@spectrum-web-components/tabs/sp-tab-panel.js';
+
+// After (single import registers all three elements)
+import '@adobe/spectrum-wc/tabs';


needs to be updated

rubencarvalho · 2026-05-12T10:38:03Z

+import '@adobe/spectrum-wc/tabs';
+```
+
+> `@adobe/spectrum-wc` is a monolithic package. Importing via subpath (e.g. `@adobe/spectrum-wc/tabs`) loads only that component's bundle.


update like you did on the docs:

@adobe/spectrum-wc is a monolithic package. Importing via subpath (e.g. @adobe/spectrum-wc/components/progress-circle/swc-progress-circle.js) registers and loads only that component's bundle.

rubencarvalho · 2026-05-12T10:38:10Z

+| ----------------------- | -------------------------------------------------------- | -------------------------------------------- |
+| Tag names               | `<sp-tabs>`, `<sp-tab>`, `<sp-tab-panel>`                | `<swc-tabs>`, `<swc-tab>`, `<swc-tab-panel>` |
+| Package                 | `@spectrum-web-components/tabs`                          | `@adobe/spectrum-wc`                         |
+| Import                  | `@spectrum-web-components/tabs/sp-tabs.js` (per element) | `@adobe/spectrum-wc/tabs` (single import)    |


Co-authored-by: Cursor <cursoragent@cursor.com>

5t3ph

Rajdeepc requested a review from a team as a code owner May 11, 2026 14:25

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

Rajdeepc force-pushed the rajdeepc/docs-tabs-consumer-migration-guide branch from 2d9948c to 2d36351 Compare May 11, 2026 14:39

Rajdeepc changed the title ~~[Docs(tabs)] Add consumer migration guide for swc-tabs~~ docs(tabs): Added consumer migration guide for swc-tabs May 12, 2026

Rajdeepc force-pushed the rajdeepc/docs-tabs-consumer-migration-guide branch from 1a42947 to d97a8f1 Compare May 12, 2026 08:47

Rajdeepc force-pushed the rajdeepc/docs-tabs-consumer-migration-guide branch from d97a8f1 to 52007cf Compare May 12, 2026 08:49

Rajdeepc self-assigned this May 12, 2026

Rajdeepc added the Status:Ready for review PR ready for review or re-review. label May 12, 2026

rubencarvalho requested changes May 12, 2026

View reviewed changes

Merge branch 'main' into rajdeepc/docs-tabs-consumer-migration-guide

6079943

Co-authored-by: Cursor <cursoragent@cursor.com>

Rajdeepc force-pushed the rajdeepc/docs-tabs-consumer-migration-guide branch from 758ec83 to 6079943 Compare May 12, 2026 14:17

Rajdeepc requested a review from rubencarvalho May 12, 2026 14:17

chore: resolved merge conflicts

db90778

5t3ph approved these changes May 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(tabs): Added consumer migration guide for swc-tabs#6267

docs(tabs): Added consumer migration guide for swc-tabs#6267
Rajdeepc wants to merge 3 commits into
mainfrom
rajdeepc/docs-tabs-consumer-migration-guide

Rajdeepc commented May 11, 2026

Uh oh!

changeset-bot Bot commented May 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 11, 2026 •

edited

Loading

Uh oh!

rubencarvalho May 12, 2026

Uh oh!

rubencarvalho May 12, 2026

Uh oh!

rubencarvalho May 12, 2026

Uh oh!

5t3ph left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Rajdeepc commented May 11, 2026

Description

Motivation and context

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Reviewer's checklist

Manual review test cases

Device review

Accessibility testing checklist

Uh oh!

changeset-bot Bot commented May 11, 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 11, 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!

rubencarvalho May 12, 2026

Choose a reason for hiding this comment

Uh oh!

rubencarvalho May 12, 2026

Choose a reason for hiding this comment

Uh oh!

rubencarvalho May 12, 2026

Choose a reason for hiding this comment

Uh oh!

5t3ph left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot Bot commented May 11, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading