| name | migrate-swc-gen1-to-gen2 |
| description | Upgrade Spectrum 1 (sp-* elements, @spectrum-web-components/*) to Spectrum 2 (swc-* elements, @adobe/spectrum-wc). Use when developers need to migrate from Spectrum 1 to Spectrum 2 web components, or when they mention @spectrum-web-components, sp-* elements, or Spectrum 1. |
| license | Apache-2.0 |
| kind | migration |
| metadata | {"author":"Adobe","website":"https://spectrum-web-components.adobe.com"} |
Spectrum 1 → Spectrum 2 migration
Upgrade sp-* Spectrum 1 components (@spectrum-web-components/*) to
swc-* Spectrum 2 components (@adobe/spectrum-wc).
You do not have to migrate everything at once. Gen 1 and Gen 2 coexist in
the same app — <sp-badge> and <swc-badge> are independent custom elements.
Migrate one component (or one screen) at a time.
TL;DR
- Install
@adobe/spectrum-wc alongside your existing @spectrum-web-components/* packages.
- Switch Gen 1 to the
spectrum-two theme so it aligns visually with Gen 2.
- Add the Gen 2 stylesheet and
swc-theme classes to your application root.
- Load Adobe Clean Spectrum VF (the Spectrum 2 font).
- Replace
<sp-*> elements with <swc-*> one component at a time, following
each component's migration guide.
- Once no
<sp-*> elements remain, remove Gen 1 packages, theme imports, and
<sp-theme>.
For the full coexistence walkthrough — including font setup, --mod-* → --swc-*
CSS mapping, and decommissioning Gen 1 — read
Migrate from Gen1 first.
Scope
This skill covers the Spectrum 1 → Spectrum 2 migration only. Do not perform
major framework upgrades (e.g. React version bumps) as part of this migration;
note them as recommended follow-ups in the final report instead.
Step 1 — Read the overarching migration guide
Before starting, read Migrate from Gen1.
It covers the coexistence model, theme bridging, font loading, CSS namespace
changes, and decommissioning. Understanding this context prevents common mistakes.
Step 2 — Identify what is being migrated
- Search package manifests for
@spectrum-web-components/* dependencies.
- Note the package manager (npm / yarn / pnpm) from the lockfile.
- Find app entrypoints, root providers, and any
<sp-theme> usages.
- Check each
sp-* component against the list of available migration guides below.
Components without a guide are still Gen 1 only — keep them installed.
Step 3 — Install Gen 2
npm install @adobe/spectrum-wc
yarn add @adobe/spectrum-wc
pnpm add @adobe/spectrum-wc
Keep existing @spectrum-web-components/* packages. Gen 2 ships as a single
monorepo package; import individual components from subpaths.
Step 4 — Align Gen 1 visually with Spectrum 2
Switch the existing <sp-theme> to system="spectrum-two" to keep Gen 1
components visually consistent with their <swc-*> neighbors:
import '@spectrum-web-components/theme/sp-theme.js';
import '@spectrum-web-components/theme/src/spectrum-two/themes.js';
<sp-theme system="spectrum-two" color="light" scale="medium">
</sp-theme>
Step 5 — Add the Gen 2 stylesheet and theme classes
import '@adobe/spectrum-wc/swc.css';
<html class="swc-theme swc-theme--light">
<body>
</body>
</html>
Theme classes: swc-theme--light, swc-theme--dark, swc-theme--adaptive.
See Theme and scales.
Step 6 — Load Adobe Clean Spectrum VF
Gen 2 uses Adobe Clean Spectrum VF (the Spectrum 2 font family). See
Fonts for Adobe Fonts, CDN, and
self-hosted setup instructions.
Step 7 — Replace components one at a time
For each component to migrate:
-
Open the component's migration guide from references/components/ (e.g.
references/components/badge.md). It lists renamed attributes, removed
features, new additions, and a CSS custom property mapping table.
-
Update the import:
import '@spectrum-web-components/badge/sp-badge.js';
import '@adobe/spectrum-wc/components/badge/swc-badge.js';
-
Rename the tag (<sp-badge> → <swc-badge>) and apply attribute renames.
-
Replace --mod-badge-* CSS overrides with --swc-badge-* equivalents.
See Component styles.
The tag prefix always changes from sp- to swc- across all components.
Step 8 — Validate
- Type-check:
tsc --noEmit
- Run tests covering the migrated components.
- Run the build and verify output.
Fix all failures before declaring the migration complete.
Step 9 — Decommission Gen 1 (when ready)
Once no <sp-*> elements remain:
- Remove
@spectrum-web-components/* from package.json.
- Remove
<sp-theme> and its imports.
- Remove remaining
--mod-* CSS overrides.
Step 10 — Generate final report
Summarise:
Changes made
- Packages added and removed
- Components migrated (before/after tag names)
- Attributes renamed or removed
- CSS custom property renames applied
Remaining items
- Components with no Gen 2 equivalent yet (still on Gen 1)
- Any open questions or gaps
Recommended follow-ups
- Any major dependency upgrades that were out of scope
Documentation structure
Overarching guides
{{MIGRATION_GUIDE_LIST}}
Per-component migration guides
One file per migrated component in references/components/.
Read the guide for a component to see its exact breaking changes and CSS mapping.
Components with a migration guide: {{MIGRATION_COMPONENT_NAMES}}.
Components without a migration guide are still Gen 1 only. Keep
@spectrum-web-components/[name] installed until a Gen 2 equivalent ships.
{{MIGRATION_COMPONENT_LIST}}
