feat(.ai): add consumer migration skill by marissahuysentruyt · Pull Request #6145 · adobe/spectrum-web-components

marissahuysentruyt · 2026-04-06T21:13:22Z

Description

⚠️ SECOND PARALLEL MERGE ⚠️
Can be merged directly into feat-agnostic-ai-folder-stuff before or after the washing machine skills PR #6127 or #6139

Adds a consumer-facing migration guide for the Badge component, covering what changed between 1st-gen and 2nd-gen, how to update markup/attributes/slots, styling and customization changes, accessibility expectations, and rollout/testing guidance.

Also ships a reusable .ai skill (consumer-migration-guide) so the same guide structure can be generated consistently for any other component going forward.

Changes:

CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/consumer-migration-guide.md: full consumer migration guide for Badge
.ai/skills/consumer-migration-guide/SKILL.md: skill definition for generating per-component consumer migration guides
.ai/skills/consumer-migration-guide/references/consumer-migration-guide-prompt.md: prompt
.ai/README.md: updated to document the new skill
CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md: updated index
2nd-gen/packages/swc/.storybook/preview.ts: minor update

Motivation and context

Application developers migrating from 1st-gen to 2nd-gen (for example, sp-badge to swc-badge) need practical, consumer-focused guidance that goes beyond internal implementation analysis. This doc covers the day-to-day upgrade path: what to search for, what to change, and how to validate the result. The skill ensures creating a migration guide for consumers is repeatable for every subsequent component migration.

Related issue(s)

partially addresses 1675
swc-1894

Screenshots (if appropriate)

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

Badge consumer migration guide is accurate and complete

Open CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/consumer-migration-guide.md
Follow the "Update your code" section using a real sp-badge usage as input (maybe just try to plop it on the badge storybook docs page as a new story?)
Expect the before/after examples to produce a working swc-badge with no regressions

Consumer migration skill generates a correct guide for a new component

Invoke the consumer-migration-guide skill for a second component (e.g. status light)
Expect the output to follow the same structure as the Badge guide
Confirm links to rendering-and-styling-migration-analysis.md and accessibility-migration-analysis.md are
present where those docs exist

Device review

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

Accessibility testing checklist

Required: Complete each applicable item and document your testing steps (replace the placeholders with your component-specific instructions).

Keyboard
documentation only
Screen reader
documentation only

changeset-bot · 2026-04-06T21:13:26Z

⚠️ No Changeset found

Latest commit: 46dc5ce

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-06T21:19:21Z

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

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.

…skill - The a11y migration analysis doc is a full authoring playbook, not a linting rule. Moves it from .ai/rules/ to .ai/skills/ with a SKILL.md that mirrors the component-migration-analysis skill structure. - Also fixes a stale .cursor/ path reference in component-migration-analysis/SKILL.md.

- Delete .cursor/README.md and .cursor/config.json - Delete all skill files under .cursor/skills/

…kill

caseyisonit · 2026-04-21T18:17:03Z

this just resolved linter issues with links

…tps://github.com/adobe/spectrum-web-components into marissahuysentruyt/feat-consumer-migration-skill

caseyisonit · 2026-04-21T22:27:36Z

allows the migration guides to get picked up

caseyisonit · 2026-04-21T22:27:57Z

to quiet spell check

cdransf

Looks good! Just one note ✨

Co-authored-by: Cory Dransfeldt <445732+cdransf@users.noreply.github.com>

…kill

marissahuysentruyt self-assigned this Apr 6, 2026

marissahuysentruyt changed the base branch from main to marissahuysentruyt/feat-agnostic-folder-ai-stuff April 6, 2026 21:13

marissahuysentruyt changed the title ~~Marissahuysentruyt/feat consumer migration skill~~ feat(.ai): add consumer migration skill Apr 6, 2026

marissahuysentruyt force-pushed the marissahuysentruyt/feat-consumer-migration-skill branch from 3be2546 to 3dd84b6 Compare April 6, 2026 21:18

marissahuysentruyt added 19 commits April 8, 2026 13:21

feat(.ai): .ai/ dir for tool-agnostic support

c856887

docs(.ai): updates readme with .ai references and new skills

ad25fb7

chore(.cursor): remove files relocated to .ai/

e1f184a

- Delete .cursor/README.md and .cursor/config.json - Delete all skill files under .cursor/skills/

feat(.ai): adds .cursor symlinks

0395c95

feat(.ai): add .claude symlinks

d63c149

fix(.ai): updates path references in rules and scripts to .ai

03fc71c

feat: adds new directories to gitignore

5aee790

feat: repo level AGENTS.md

35a8e58

docs(.ai): tweaks to readme language

ee07e57

docs(.ai): overview and reusable prompts

78b3dc8

docs(.ai): fix cursor reference in .ai/rule

d9b6b08

fix(.ai): cursor skills symlink

3d87dbe

feat(.ai): adds missing frontmatter to storybook rules

bcc6554

fix(.ai): contributor docs nav scripts stay out of .ai

373dc21

fix(.ai): handoff references .ai instead of .cursor

095103b

docs(.ai): clarify symlink usage in readme

15b52b3

fix(.ai): missing instructions in a11y migration skill

5419ec0

docs(.ai): update readme with content from agnostic overview file

117b2a4

cdransf mentioned this pull request Apr 10, 2026

docs: add consumer migration guides for S2 components #6169

Merged

4 tasks

Base automatically changed from marissahuysentruyt/feat-agnostic-folder-ai-stuff to main April 13, 2026 19:25

caseyisonit and others added 3 commits April 21, 2026 12:03

chore: merge main

268ac5a

chore: linting fixes in rfc

8832fd0

Merge branch 'main' into marissahuysentruyt/feat-consumer-migration-s…

8447de3

…kill

caseyisonit reviewed Apr 21, 2026

View reviewed changes

caseyisonit marked this pull request as ready for review April 21, 2026 18:19

caseyisonit requested a review from a team as a code owner April 21, 2026 18:19

caseyisonit added Status:Ready for review PR ready for review or re-review. High priority PR review PR is a high priority and should be reviewed ASAP AI tooling and removed Status:WIP PR is a work in progress or draft do-not-merge NO MERGE-Y! labels Apr 21, 2026

caseyisonit added 6 commits April 21, 2026 12:43

chore: moved the guide to component and render in storybook

fe54463

Merge branch 'marissahuysentruyt/feat-consumer-migration-skill' of ht…

240ae36

…tps://github.com/adobe/spectrum-web-components into marissahuysentruyt/feat-consumer-migration-skill

chore: simplify output

f38f6b6

chore: little more cleanup

f716043

chore: cssprops in table with constraint notes

e3e44e5

chore: no mo s2

6042b02

caseyisonit reviewed Apr 21, 2026

View reviewed changes

Comment thread 2nd-gen/packages/swc/.storybook/main.ts

Copy link
Copy Markdown

Contributor

caseyisonit Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

allows the migration guides to get picked up

caseyisonit reviewed Apr 21, 2026

View reviewed changes

Comment thread .vscode/settings.json

Copy link
Copy Markdown

Contributor

caseyisonit Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to quiet spell check

caseyisonit approved these changes Apr 21, 2026

View reviewed changes

cdransf approved these changes Apr 21, 2026

View reviewed changes

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

caseyisonit and others added 3 commits April 21, 2026 16:56

Apply suggestion from @cdransf

904a9fb

Co-authored-by: Cory Dransfeldt <445732+cdransf@users.noreply.github.com>

chore: example fix

231ca1e

Merge branch 'main' into marissahuysentruyt/feat-consumer-migration-s…

412605e

…kill

caseyisonit enabled auto-merge (squash) April 21, 2026 23:05

Merge branch 'main' into marissahuysentruyt/feat-consumer-migration-s…

46dc5ce

…kill

caseyisonit merged commit 022d6ee into main Apr 21, 2026
29 checks passed

caseyisonit deleted the marissahuysentruyt/feat-consumer-migration-skill branch April 21, 2026 23:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(.ai): add consumer migration skill#6145

feat(.ai): add consumer migration skill#6145
caseyisonit merged 34 commits into
mainfrom
marissahuysentruyt/feat-consumer-migration-skill

marissahuysentruyt commented Apr 6, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Apr 6, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 6, 2026 •

edited

Loading

Uh oh!

caseyisonit Apr 21, 2026

Uh oh!

caseyisonit Apr 21, 2026

Uh oh!

caseyisonit Apr 21, 2026

Uh oh!

cdransf left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

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 Apr 6, 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 6, 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!

caseyisonit Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

caseyisonit Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

caseyisonit Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

cdransf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

marissahuysentruyt commented Apr 6, 2026 •

edited

Loading

changeset-bot Bot commented Apr 6, 2026 •

edited

Loading

github-actions Bot commented Apr 6, 2026 •

edited

Loading