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: c648fbf

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/

marissahuysentruyt · 2026-04-08T18:02:13Z

CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/consumer-migration-guide.md

+| `outline` constraint | N/A | `outline` only applies to semantic variants; ignore or remove when used with color variants |
+| New non-semantic color variants | 1st-gen did not have `pink`, `turquoise`, `brown`, `cinnamon`, `silver` | No action required unless you want to use these new variants |
+| Internal CSS class names | `spectrum-Badge*` → `swc-Badge*` | Remove any selectors targeting `spectrum-Badge*` classes |
+| `--mod-badge-*` custom properties | Same property names, same behavior | No action required if using supported `--mod-badge-*` properties |


this has to be updated to reference the css code styles (--mod basically got changed to exposed --swc variables).

for agent knowledge: mention that the css style guide recommendations weigh more than the literal recommendations in the rendering-and-styling analysis.

marissahuysentruyt · 2026-04-08T18:02:39Z

CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/consumer-migration-guide.md

+
+Remove any CSS rules in your application that select these classes. If you need to style a badge, apply styles to the host element (`swc-badge`) using the supported `--mod-badge-*` custom properties.
+
+### CSS custom properties, tokens, and supported theming hooks


this whole section about --mods is incorrect. ☝️ I left a comment about needing to change it.

marissahuysentruyt · 2026-04-08T18:03:46Z

CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/consumer-migration-guide.md

+
+---
+
+## Migration checklist


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

marissahuysentruyt force-pushed the marissahuysentruyt/feat-agnostic-folder-ai-stuff branch from 7bdadee to 117b2a4 Compare April 8, 2026 17:21

marissahuysentruyt added 2 commits April 8, 2026 13:42

feat(.ai): consumer migration skill

accb70a

feat(badge): adds consumer migration guide docs

c648fbf

marissahuysentruyt force-pushed the marissahuysentruyt/feat-consumer-migration-skill branch from 3dd84b6 to c648fbf Compare April 8, 2026 17:48

marissahuysentruyt commented Apr 8, 2026

View reviewed changes

cdransf mentioned this pull request Apr 10, 2026

docs: add consumer migration guides for S2 components #6169

Open

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

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
marissahuysentruyt wants to merge 21 commits intomainfrom
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!

marissahuysentruyt Apr 8, 2026

Uh oh!

marissahuysentruyt Apr 8, 2026

Uh oh!

marissahuysentruyt Apr 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		Remove any CSS rules in your application that select these classes. If you need to style a badge, apply styles to the host element (`swc-badge`) using the supported `--mod-badge-*` custom properties.

		### CSS custom properties, tokens, and supported theming hooks

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!

marissahuysentruyt Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

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