docs: add consumer migration guides for S2 components by cdransf · Pull Request #6169 · adobe/spectrum-web-components

cdransf · 2026-04-10T17:37:53Z

Description

Adds migration.md files for 7 components in 2nd-gen/packages/swc/components/, following the pattern established
by the avatar migration guide:

asset — tag/package rename, CSS vars removed (token-based), shadow DOM class changes
badge — tag/package rename, CSS var rename, new subtle/outline attributes, 5 new color variants
divider — tag/package rename, CSS var rename, shadow DOM structure change
icon — tag/package rename, name/src attributes removed, xxs/xxl sizes removed, slot-only SVG
progress-circle — tag/package rename, CSS var rename, static-color="black" added, SVG rendering change
status-light — tag/package rename, disabled removed, accent variant removed, 5 new color variants
typography — class prefix .spectrum-* → .swc-*, light/uppercase/strong-emphasized removed, new Title variant
and prose container

Each guide includes: installation steps, quick reference table, per-change before/after examples, new features,
and accessibility notes. Follows the same per-component structure proposed in draft #6145.

Motivation and context

Application developers migrating from 1st-gen to 2nd-gen need practical, consumer-focused guidance that goes
beyond internal implementation analysis. These docs cover the day-to-day upgrade path: what to search for, what
to change, and how to validate the result.

Related issue(s)

SWC-1675
related: feat(.ai): add consumer migration skill #6145 (draft — consumer migration skill)

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed the Accessibility Practices for this feature, see: Aria
Practices
I have added automated tests to cover my changes.
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

Each migration guide is accurate and complete
a. Open any migration.md in 2nd-gen/packages/swc/components/[component]/
b. Follow the "Update your code" steps using a real sp-[component] usage as input
c. Expect the before/after examples to produce a working swc-[component] with no regressions
Breaking changes are clearly surfaced
a. Review the icon and status-light guides specifically — these have the most significant removals (name/src
on icon, disabled/accent on status-light)
b. Confirm the guidance is actionable and the "After" examples are valid 2nd-gen markup

changeset-bot · 2026-04-10T17:38:00Z

⚠️ No Changeset found

Latest commit: 22aad87

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-04-10T17:43:33Z

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

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.

rubencarvalho · 2026-04-14T12:42:24Z

This is looking really good! Could we somehow add a "template" / or instructions to the migration guide, so all future components use this format too?

rubencarvalho · 2026-04-14T12:53:03Z

This is looking really good! Could we somehow add a "template" / or instructions to the migration guide, so all future components use this format too?
I wonder if we could surface these in the prod Storybook (customer facing). If we do, we can have a dedicated PR for it (doesn't need to be here). cc: @caseyisonit

cdransf · 2026-04-14T21:50:44Z

This is looking really good! Could we somehow add a "template" / or instructions to the migration guide, so all future components use this format too? I wonder if we could surface these in the prod Storybook (customer facing). If we do, we can have a dedicated PR for it (doesn't need to be here). cc: @caseyisonit

Added a skill and consumer docs for that here 40e15d1 ✨

rise-erpelding

This is wonderful! I don't have a whole lot that I think needs to change, but several questions about things that we might have missed in POC work so far.

rise-erpelding · 2026-04-21T21:00:39Z

+| CSS custom properties | `--mod-badge-*`                                          | `--swc-badge-*`                                                      |
+| Slots                 | `default` (label), `icon`                                | `default` (label), `icon` — unchanged                                |
+
+---


I came over here to say that maybe we should mention that the default variant for badge has been changed to "neutral"...

But that seems a bit misleading because that's not the variant that I see if I remove the variant attribute. (It's also in conflict with the variant that gets set in the base class).

Wondering if we should make a few changes to make the default to neutral actually work?

For this one:

Changed the default in Badge.base.ts to neutral

Removed the redundant @property declaration in Badge.ts and then cleaned up the imports

Added a Default variant row in the migration.md and a ### Default variant section with before/after examples

At runtime the subclass override won (which is why our test passed as well), but removing the attribute would set the property to null rather than the default and you'd get a mismatch. ✨

rise-erpelding

Nothing blocking for me!

I left a comment about how do reason about which mods to include and which not, I'd love to hear others share their thoughts as we determine what a good consumer guide looks like.

@todo

* docs(badge): update rendering-and-styling migration analysis Clarify that fixed positioning is documented in design system guidance and note new S2 badge variants (notification, indicator) tracked in SWC-1831. * feat(badge): add no-label CSS class when label slot is empty Add `swc-Badge--no-label` class via classMap when the default slot has no text content, enabling CSS targeting of icon-only badges. * fix(badge): updates padding block tokens and icon-only gap * feat(badge): support for swc-icon internal * feat(badge): icon only accessibility examples * fix(badge): size types passing into swc-icon * docs(badge): adds todo for missing variants * fix(badge): dynamically passes size to slotted icon * test(badge): anatomy test checks for children elements previously, we were checking for text content when the badge icon slot was just accepting strings. Now the anatomy story is using the swc-icon internal component, so it never has text content (it's got HTML). the badge test now checks for children.length instead. * fix(badge): disabled text control for icon-slot * fix(badge): a11y roles for icon only badges * fix(badge): inline padding - adds new --swc-badge-padding-inline-start custom prop to control the inline padding start of a badge. it changes when there's an icon + label vs. just the text label - also fixes the gap property so that we just redefine the custom prop for the badge gap instead * docs(badge): add todo for icon only badge size story * docs(rules): update docs on template vs custom html rendering * docs: badge examples updated * fix(badge): correct fallbacks for sized badge padding Without this fallback, the start padding on a badge without an icon would always resolve to the 75-scale token regardless of size, because --swc-badge-padding-inline-start was never set in the size override blocks. Adding --swc-badge-padding-inline as an intermediate fallback means size overrides propagate to both sides automatically, while the :has() rules can still override --swc-badge-padding-inline-start for the icon case. * revert(badge): medium stays default size; neutral is default variant * test(badge): update new default assertions * docs(badge): adds @todo to default sizing discrepancy comment * fix(badge): reduce selector specificity and refactor private padding tokens * fix(badge): padding block properties corrected * docs: correct updated css style guides with badge examples * docs: fix typo * docs(badge): use different badge variants per design docs * docs(badge): adds tickets to todo comments

…ions

…track in forced colors

….mdx Co-authored-by: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com>

@todo

* feat(badge): ensure visual s2 fidelity (#6114) * docs(badge): update rendering-and-styling migration analysis Clarify that fixed positioning is documented in design system guidance and note new S2 badge variants (notification, indicator) tracked in SWC-1831. * feat(badge): add no-label CSS class when label slot is empty Add `swc-Badge--no-label` class via classMap when the default slot has no text content, enabling CSS targeting of icon-only badges. * fix(badge): updates padding block tokens and icon-only gap * feat(badge): support for swc-icon internal * feat(badge): icon only accessibility examples * fix(badge): size types passing into swc-icon * docs(badge): adds todo for missing variants * fix(badge): dynamically passes size to slotted icon * test(badge): anatomy test checks for children elements previously, we were checking for text content when the badge icon slot was just accepting strings. Now the anatomy story is using the swc-icon internal component, so it never has text content (it's got HTML). the badge test now checks for children.length instead. * fix(badge): disabled text control for icon-slot * fix(badge): a11y roles for icon only badges * fix(badge): inline padding - adds new --swc-badge-padding-inline-start custom prop to control the inline padding start of a badge. it changes when there's an icon + label vs. just the text label - also fixes the gap property so that we just redefine the custom prop for the badge gap instead * docs(badge): add todo for icon only badge size story * docs(rules): update docs on template vs custom html rendering * docs: badge examples updated * fix(badge): correct fallbacks for sized badge padding Without this fallback, the start padding on a badge without an icon would always resolve to the 75-scale token regardless of size, because --swc-badge-padding-inline-start was never set in the size override blocks. Adding --swc-badge-padding-inline as an intermediate fallback means size overrides propagate to both sides automatically, while the :has() rules can still override --swc-badge-padding-inline-start for the icon case. * revert(badge): medium stays default size; neutral is default variant * test(badge): update new default assertions * docs(badge): adds @todo to default sizing discrepancy comment * fix(badge): reduce selector specificity and refactor private padding tokens * fix(badge): padding block properties corrected * docs: correct updated css style guides with badge examples * docs: fix typo * docs(badge): use different badge variants per design docs * docs(badge): adds tickets to todo comments * docs: add consumer migration guides for 7 S2 components * docs: additional migration refinements * docs: migration css info refinement * docs: a11y updates for migration docs * chore(migration-guides): add ai skill and contributor docs for migrations * chore(migration-guides): add @cssprop to doc blocks * chore(migration-guides): address pr feedback * chore(migration-guides): fix badge tests * chore(migration-guides): refactor using migration skill * fix(migration-docs): remove deprecated files * fix(migration-docs): remove deprecated ai skill reference * fix(migration-docs): address pr feedback * chore(storybook): update preview nav for new accessibility analysis docs * fix(migration-docs): update progress circle docs * fix(migration-docs): address missing properties to badge table * fix(migration-docs): revert application of Canvas to progress circle track in forced colors * fix(migration-docs): consistently rename status light properties * Update 2nd-gen/packages/swc/components/badge/consumer-migration-guide.mdx Co-authored-by: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com> * fix(migration-docs): badge fallbacks and consistency * chore(migration-docs): add missing mods --------- Co-authored-by: Marissa Huysentruyt <69602589+marissahuysentruyt@users.noreply.github.com> Co-authored-by: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com>

cdransf self-assigned this Apr 10, 2026

cdransf added the Status:WIP PR is a work in progress or draft label Apr 10, 2026

cdransf force-pushed the cdransf/migration-guides branch 4 times, most recently from 461b6f8 to d4220ba Compare April 10, 2026 23:14

rubencarvalho reviewed Apr 14, 2026

View reviewed changes

Comment thread 2nd-gen/packages/swc/components/badge/migration.md Outdated

cdransf force-pushed the cdransf/migration-guides branch 2 times, most recently from 74024f7 to f7b8252 Compare April 14, 2026 18:53

cdransf added Status:Ready for review PR ready for review or re-review. Spectrum 2 Issues related to Spectrum 2 and removed Status:WIP PR is a work in progress or draft labels Apr 14, 2026

cdransf requested a review from caseyisonit April 14, 2026 18:53

cdransf marked this pull request as ready for review April 14, 2026 18:53

cdransf requested a review from a team as a code owner April 14, 2026 18:53

cdransf changed the base branch from main to swc-1668/poc-components April 14, 2026 20:41

cdransf force-pushed the cdransf/migration-guides branch from 45cca69 to 40e15d1 Compare April 14, 2026 20:43

cdransf force-pushed the cdransf/migration-guides branch from 1202c75 to 8dff857 Compare April 14, 2026 21:50

cdransf requested a review from rubencarvalho April 14, 2026 21:50

cdransf force-pushed the cdransf/migration-guides branch 2 times, most recently from ccd3f17 to 68f80d5 Compare April 17, 2026 23:35

rise-erpelding mentioned this pull request Apr 21, 2026

[SWC-1668] feat: migrate poc components to full-fidelity production #6122

Open

41 tasks

rise-erpelding reviewed Apr 21, 2026

View reviewed changes

cdransf force-pushed the cdransf/migration-guides branch from 249610b to df883d4 Compare April 21, 2026 23:13

cdransf requested a review from rise-erpelding April 21, 2026 23:30

cdransf force-pushed the swc-1668/poc-components branch from b86942e to b35b50a Compare April 24, 2026 23:39

cdransf force-pushed the cdransf/migration-guides branch from 5ceef34 to 446a0bc Compare April 24, 2026 23:52

rubencarvalho added the High priority PR review PR is a high priority and should be reviewed ASAP label Apr 27, 2026

rise-erpelding approved these changes Apr 27, 2026

View reviewed changes

Comment thread 2nd-gen/packages/swc/components/badge/consumer-migration-guide.mdx Outdated

cdransf force-pushed the swc-1668/poc-components branch from b35b50a to 122f981 Compare April 27, 2026 15:15

marissahuysentruyt and others added 19 commits April 27, 2026 08:15

docs: add consumer migration guides for 7 S2 components

cb838d9

docs: additional migration refinements

d2b1e3c

docs: migration css info refinement

50438d4

docs: a11y updates for migration docs

c03cf25

chore(migration-guides): add ai skill and contributor docs for migrat…

6fa90cf

…ions

chore(migration-guides): add @cssprop to doc blocks

c2f0474

chore(migration-guides): address pr feedback

e206b3b

chore(migration-guides): fix badge tests

6df7d86

chore(migration-guides): refactor using migration skill

5fdbd05

fix(migration-docs): remove deprecated files

143d1a9

fix(migration-docs): remove deprecated ai skill reference

6efb94a

fix(migration-docs): address pr feedback

3f29cfc

chore(storybook): update preview nav for new accessibility analysis docs

6866979

fix(migration-docs): update progress circle docs

3530830

fix(migration-docs): address missing properties to badge table

ca6095d

fix(migration-docs): revert application of Canvas to progress circle …

9212379

…track in forced colors

fix(migration-docs): consistently rename status light properties

5db247f

Update 2nd-gen/packages/swc/components/badge/consumer-migration-guide…

c591740

….mdx Co-authored-by: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com>

cdransf force-pushed the cdransf/migration-guides branch from 3f7fcc2 to c591740 Compare April 27, 2026 15:15

cdransf added 2 commits April 27, 2026 08:36

fix(migration-docs): badge fallbacks and consistency

189f90e

chore(migration-docs): add missing mods

22aad87

cdransf merged commit 16eab6f into swc-1668/poc-components Apr 27, 2026
26 checks passed

cdransf deleted the cdransf/migration-guides branch April 27, 2026 17:07

Conversation

cdransf commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Related issue(s)

Author's checklist

Reviewer's checklist

Manual review test cases

Uh oh!

changeset-bot Bot commented Apr 10, 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 Apr 10, 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 commented Apr 14, 2026

Uh oh!

Uh oh!

rubencarvalho commented Apr 14, 2026

Uh oh!

cdransf commented Apr 14, 2026

Uh oh!

rise-erpelding left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rise-erpelding Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

cdransf Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rise-erpelding left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

cdransf commented Apr 10, 2026 •

edited

Loading

changeset-bot Bot commented Apr 10, 2026 •

edited

Loading

github-actions Bot commented Apr 10, 2026 •

edited

Loading

cdransf Apr 21, 2026 •

edited

Loading