Skip to content

feat(skill): add swc-consumer-migration skill for Spectrum 1 to 2 upgrades #6233

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
blunteshwar wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat(skill): add swc-consumer-migration skill for Spectrum 1 to 2 upgrades #6233

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 123 additions & 0 deletions 2nd-gen/packages/.ai/skills/swc-consumer-migration/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
---
name: swc-consumer-migration
description: Use when a consumer of Spectrum Web Components wants to migrate their application from Spectrum 1 (1st-gen, @spectrum-web-components/*) to Spectrum 2 (2nd-gen, @adobe/spectrum-wc). The skill collects per-component consumer migration guides shipped inside node_modules, detects which components the consumer uses from their package.json, and applies each migration component-by-component with explicit checkpoints. Triggers include "migrate spectrum web components", "migrate swc to 2nd gen", "upgrade @spectrum-web-components", "swc 2nd gen migration", "migrate from spectrum 1 to spectrum 2".
alwaysApply: false
---

# Spectrum Web Components consumer migration

Help an application developer migrate their codebase from 1st-gen Spectrum Web Components (`@spectrum-web-components/*`) to 2nd-gen (`@adobe/spectrum-wc`) by reading the per-component consumer migration guides that ship inside their installed `node_modules` and applying each guide to the consumer's source.

This skill is intended to run inside the **consumer's project**, not the spectrum-web-components repo. It is invoked from Claude Code, Cursor, or Codex.

## When to use

- Consumer's `package.json` lists one or more `@spectrum-web-components/*` dependencies and they want to move to `@adobe/spectrum-wc`.
- Consumer asks for a guided, component-by-component migration with checkpoints.
- Do NOT use this skill to author migration guides — that is `.ai/skills/consumer-migration-guide` in the spectrum-web-components repo.

## Preflight

Before any other step, confirm:

1. Current working directory is the **consumer project root** (contains a `package.json`).
2. `node_modules/` exists. If not, ask the user to run their install command (`npm install`, `yarn`, or `pnpm install`) and stop.
3. At least one of `node_modules/@spectrum-web-components/` or `node_modules/@adobe/spectrum-wc/` exists. If neither exists, stop and tell the user nothing to migrate.

If any check fails, stop and surface the issue. Do not proceed.

## Step 1: Collect guides

Run the bundled collection script. The script is dependency-free Node and works from any consumer project root:

```bash
node <skill-dir>/scripts/collect-guides.mjs
```

`<skill-dir>` is wherever this skill's files live in the consumer project. The script resolves all paths relative to `process.cwd()` so it works whether the skill files were copied into the consumer project or symlinked.

The script:

- Walks the consumer's `node_modules/` (including hoisted and nested workspace layouts).
- Finds every `@spectrum-web-components/*` package and the `@adobe/spectrum-wc` package.
- Locates each consumer migration guide by checking these candidate paths inside each package, in order, first match wins:
1. `<pkg>/consumer-migration-guide.mdx`
2. `<pkg>/dist/consumer-migration-guide.mdx`
3. `<pkg>/components/<name>/consumer-migration-guide.mdx`
4. `<pkg>/dist/components/<name>/consumer-migration-guide.mdx`
5. `<pkg>/docs/consumer-migration-guide.md`
6. `<pkg>/CONSUMER-MIGRATION.md`
- Copies every found guide to `<cwd>/.swc-migration/guides/<component>.md`.
- Writes `<cwd>/.swc-migration/manifest.json` listing every package, with `guidePath: null` for packages that ship no guide.

If a guide is missing from `node_modules/` because the published package does not yet ship it, the user can re-run with a local checkout fallback:

```bash
node <skill-dir>/scripts/collect-guides.mjs --repo=/path/to/spectrum-web-components
```

After the script finishes, read `manifest.json` and report a summary to the user: how many packages were detected, how many guides were collected, and which packages have no guide. Do not proceed if zero guides were collected.

## Step 2: Detect used components

Read the consumer's `package.json` from the project root. If the project is a workspace (`workspaces` field present), also read each workspace package's `package.json`.

From every dependency map (`dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`), collect:

- Every entry whose name starts with `@spectrum-web-components/`.
- Whether `@adobe/spectrum-wc` is already present (and at what version).

Cross-reference with the manifest from Step 1. Build a list:

| Component | 1st-gen pkg | Installed version | Guide available |
| --------- | ------------------------------ | ----------------- | --------------- |
| badge | @spectrum-web-components/badge | 1.11.2 | yes |
| ... | ... | ... | ... |

Show this list to the user. **Stop and ask for confirmation** before making any code changes. Confirm:

- Which components to migrate (default: all that have a guide).
- Whether to migrate in one pass or interactively per component.
- Which directories the agent is allowed to edit (default: `src/`).

## Step 3: Per-component migration

For each confirmed component, in dependency-safe order (alphabetical is fine for first pass):

1. Read `<cwd>/.swc-migration/guides/<component>.md`.
2. Parse the guide for: package changes, import changes, tag-name changes, prop / attribute changes, removed APIs, codemod hints. The expected guide structure is documented in `references/template.md`.
3. Search the consumer's allowed source directories for usages:
- Imports of `@spectrum-web-components/<component>` and its sub-paths.
- The 1st-gen tag name (e.g. `<sp-badge>`) in `.html`, `.htm`, `.tsx`, `.jsx`, `.ts`, `.js`, `.lit`, `.svelte`, `.vue`, `.mdx` files.
- The 1st-gen JS/TS class name if present in the guide.
4. Apply the guide's transformations using the consumer's editor tools. Prefer minimal edits.
5. After each component, surface a diff-style summary to the user: files touched, count of replacements, anything skipped or flagged for manual review. **Stop and ask** before continuing to the next component unless the user explicitly chose batch mode in Step 2.

After all components are migrated, run the post-migration checklist in `references/usage.md` and report results.

## Stop conditions

The skill MUST stop and ask the user explicitly before any of the following:

- Deleting any file.
- Modifying `package.json` dependency versions, adding `@adobe/spectrum-wc`, or removing `@spectrum-web-components/*` entries.
- Modifying lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`).
- Running `npm`, `yarn`, or `pnpm` install / add / remove commands.
- Touching files outside the consumer's confirmed source directories.
- Migrating a component for which `manifest.json` reports `guidePath: null`.

The script and skill never auto-commit. They never push. They never bump versions silently.

## Failure modes

- **Guide missing for a detected package.** Skip that component, log it in the final report under "Manual migration required", and continue with the rest.
- **Workspace setup with multiple `package.json` files.** Aggregate dependency lists across workspaces. Show the per-workspace breakdown in Step 2 and confirm scope before editing.
- **Multiple installed versions of the same package** (deduplication failed in `node_modules`). Surface every version found in the manifest. Migrate against the highest version's guide and warn the user about the duplicates — they likely need to dedupe before publishing.
- **Guide refers to a tag/component the consumer never used.** Skip the unused parts silently. Only report changes the consumer actually has source for.
- **Consumer source uses a 1st-gen API that the guide marks as removed with no replacement.** Do not silently delete code. Insert a `TODO(swc-migration):` comment near the usage, list it in the final report under "Removed APIs requiring redesign", and move on.

## References

- `references/usage.md` — what each section of a guide means, a worked example, and the post-migration checklist.
- `references/template.md` — canonical guide structure that the skill knows how to parse. Component authors copy this when authoring a new guide.
- `scripts/collect-guides.mjs` — the collection script. Run with `--help` for options.
95 changes: 95 additions & 0 deletions 2nd-gen/packages/.ai/skills/swc-consumer-migration/references/template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# Consumer migration guide: canonical template

Component authors copy this template when authoring a new `consumer-migration-guide.mdx` for a 2nd-gen component. The headings below are the structure that `swc-consumer-migration` knows how to parse. Keep them stable. Sentence case.

The authoritative location of a guide in source is:

```
2nd-gen/packages/swc/components/<component>/consumer-migration-guide.mdx
```

Use `.mdx` so it renders in Storybook. The skill also accepts `.md` as a fallback.

---

````mdx
import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="<Component>/Consumer migration guide" />

# <Component> consumer migration guide

One paragraph: what changed at a glance, and the smallest mental model the consumer needs to migrate.

## What changed

### Renamed

| Area | Spectrum 1 (`sp-<component>`) | Spectrum 2 (`swc-<component>`) |
| ---------------- | -------------------------------------------------- | -------------------------------- |
| Tag | `sp-<component>` | `swc-<component>` |
| Import path | `@spectrum-web-components/<component>` | `@adobe/spectrum-wc/<component>` |
| CSS custom props | `--mod-<component>-*` / `--spectrum-<component>-*` | `--swc-<component>-*` |

### Added in Spectrum 2

| Addition | Notes |
| ---------------------------- | ---------------- |
| (new attribute / slot / API) | (when to use it) |

### Removed in Spectrum 2

| Removed | Replacement |
| ------------- | ------------------------------------------------ |
| (removed API) | (1:1 replacement, or "no replacement — see ...") |

## Update your code

### 1. Update the import

```js
// Before
import '@spectrum-web-components/<component>/sp-<component>.js';
// After
import '@adobe/spectrum-wc/<component>';
```
````

### 2. Rename the tag

```html
<!-- Before -->
<sp-<component> ...>...</sp-<component>>
<!-- After -->
<swc-<component> ...>...</swc-<component>>
```

### 3. <Component-specific transformation>

(One subsection per concrete code change consumers must make. Each subsection MUST contain a Before/After fenced code block so the skill can extract the transformation.)

## Styling

(Custom-property renames. Note any properties that have no 1:1 replacement.)

## Accessibility

(Consumer-facing accessibility deltas: required attribute additions, ARIA changes, focus behavior changes.)

## Verification

(Concrete checks the consumer should run after migrating: visual smoke test path, automated test command, screen reader behaviors to verify.)

```

---

## Authoring rules

- **Sentence case** for every heading.
- **Tables** are the source of truth for renames. Code blocks under `## Update your code` are the source of truth for concrete edits.
- **Before / After** must appear inside fenced code blocks for every transformation. The skill keys off this.
- **No links to maintainer docs.** Link only to public consumer docs (Storybook, npm).
- **Do not include `Components/` in the `<Meta title>`** — `titlePrefix` adds it automatically.
- If a section does not apply (e.g. no styling changes), keep the heading and write "No changes." underneath. Do not delete the heading.
```
106 changes: 106 additions & 0 deletions 2nd-gen/packages/.ai/skills/swc-consumer-migration/references/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# Usage reference: parsing guides and applying migrations

This reference is loaded on demand by `swc-consumer-migration`. It explains how to interpret a consumer migration guide, walks through one worked example, and lists the post-migration checklist.

## How guides are structured

Every guide ships as a single `.mdx` (or `.md`) file. The skill expects this shape, with sentence-case headings:

```
# <Component> consumer migration guide

(One-paragraph summary: what changed at a glance.)

## What changed

### Renamed
(Markdown table: Area | Spectrum 1 | Spectrum 2)

### Added in Spectrum 2
(Markdown table: Addition | Notes)

### Removed in Spectrum 2
(Markdown table: Removed | Replacement)

## Update your code

### 1. Update the import
### 2. Rename the tag
### 3. <component-specific steps>

## Styling
(custom-property renames, semantic vs. non-semantic notes)

## Accessibility
(consumer-facing a11y deltas)

## Verification
(what to test after migrating)
```

When parsing, extract:

| From section | What the skill should pull out |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `## What changed > Renamed` | Tag-name renames, package / import-path renames, custom-property renames |
| `## What changed > Added in Spectrum 2` | New attributes/props/slots — informational only, no automatic edits |
| `## What changed > Removed in Spectrum 2` | Removed APIs that need a replacement decision; flag with `TODO(swc-migration):` if no 1:1 replacement exists |
| `## Update your code` | Concrete code transformations the skill should apply |
| `## Styling` | Custom-property renames the skill should apply across CSS and inline `style` strings |
| `## Accessibility` | Required attribute additions (e.g. `aria-label` for icon-only) |
| `## Verification` | Checks to run after migration |

Tables are the source of truth for renames. Code blocks under `## Update your code` are the source of truth for concrete transformations. Treat prose as commentary unless it contradicts the tables.

If a guide deviates from this structure (older guides, partial guides), parse defensively: search for the keywords "Before" / "After" inside fenced code blocks and fall back to surfacing the diff to the user for manual review.

## Worked example: badge

Source guide (shipped today): `2nd-gen/packages/swc/components/badge/consumer-migration-guide.mdx`.

After Step 1 collects guides, the skill reads `<cwd>/.swc-migration/guides/badge.md` and extracts:

- **Package rename:** `@spectrum-web-components/badge` → `@adobe/spectrum-wc/badge`
- **Import rename:** `@spectrum-web-components/badge/sp-badge.js` → `@adobe/spectrum-wc/badge`
- **Tag rename:** `<sp-badge>` → `<swc-badge>`
- **Custom-property rename:** `--mod-badge-*` and `--spectrum-badge-*` → `--swc-badge-*` (semantic variants only)
- **Removed exports:** `BADGE_VARIANTS`, `FIXED_VALUES`, `BadgeVariant`, `FixedValues` → use `Badge.VARIANTS`, `Badge.FIXED_VALUES`, or `typeof Badge.prototype.variant`
- **Accessibility delta:** add `aria-label` to icon-only badges; add `aria-hidden="true"` to decorative icons paired with text

Concrete edits the skill applies in the consumer's `src/`:

1. **Imports.** For every file that imports from `@spectrum-web-components/badge` (any sub-path), rewrite to the corresponding `@adobe/spectrum-wc/badge` import. If the original import had a sub-path (e.g. `/sp-badge.js`), drop the sub-path — the new package exposes the side-effectful registration via the package root.
2. **JSX/HTML tags.** Replace `<sp-badge` with `<swc-badge` and `</sp-badge>` with `</swc-badge>`. Preserve attributes and children. Apply across `.html`, `.htm`, `.tsx`, `.jsx`, `.ts`, `.js`, `.lit`, `.svelte`, `.vue`, `.mdx`.
3. **Named imports.** Replace named imports of `BADGE_VARIANTS` / `FIXED_VALUES` / `BadgeVariant` / `FixedValues` with `Badge.VARIANTS` / `Badge.FIXED_VALUES` / `typeof Badge.prototype.variant`. Pull `Badge` into scope if not already imported.
4. **Custom properties.** In CSS files, SCSS files, and inline `style=` strings, replace `--mod-badge-` and `--spectrum-badge-` with `--swc-badge-` only when the surrounding declaration applies to a semantic variant (positive / informative / negative / notice / neutral). Non-semantic per-color overrides have no replacement — leave them and flag with `TODO(swc-migration):` referencing the "Removed" table.
5. **Forced-colors.** `--highcontrast-badge-border-color` has no replacement. Flag every usage with `TODO(swc-migration): no forced-colors hook in Spectrum 2 badge` and leave the existing rule in place.
6. **Accessibility.** For every `<swc-badge>` whose only children are icons (no text node), add `aria-label="..."` if missing and surface a TODO for the user to fill in the label. For badges with both icon and text, add `aria-hidden="true"` to the icon element.

After applying edits, surface a per-file diff summary and stop for confirmation before moving on to the next component.

## Post-migration checklist

Run these after every component is migrated:

- [ ] **Imports resolve.** No file in the consumer's source still imports from `@spectrum-web-components/<migrated-component>`.
- [ ] **Tag references updated.** Search for the old tag name across all source files. Zero hits expected.
- [ ] **Type references updated.** TypeScript compiles. No `any` introduced where a 1st-gen named export used to be.
- [ ] **Custom properties.** Search for `--mod-<component>-` and `--spectrum-<component>-`. Either renamed to `--swc-<component>-` or flagged with `TODO(swc-migration):`.
- [ ] **Removed APIs.** Every removed API the consumer was using is either replaced or flagged with a `TODO(swc-migration):` comment. Nothing silently deleted.
- [ ] **Accessibility deltas applied.** For every component with an a11y delta in its guide, the corresponding markup change was applied or flagged.
- [ ] **Tests reference updated tags.** Test files (`*.test.*`, `*.spec.*`, `*.stories.*`) updated to use the new tag names and imports.
- [ ] **Lint and type check pass.** Run the consumer's existing scripts (do not invent new ones). If they fail, surface the failures verbatim and stop.

## What the skill does NOT do

- Bump dependency versions in `package.json` — the user runs their own install.
- Run install commands or modify lockfiles.
- Rewrite tests beyond import/tag substitution.
- Apply visual or design changes beyond what the guide explicitly specifies.
- Migrate components for which no guide was collected.

If any of those are needed, surface a clear note in the final report and let the user act.

## Re-running

Re-running `collect-guides.mjs` is safe and idempotent. It overwrites the previous guide copies and the manifest. Source files in the consumer project are never touched by the script — only by the agent applying migrations under explicit confirmation.
Loading
Loading