feat(ai): update skills for phases 2, 3, 5 by 5t3ph · Pull Request #6208 · adobe/spectrum-web-components

5t3ph · 2026-04-24T20:25:29Z

Description

Updates washing machine related AI Skills for the following phases:

Phase 2 - migration-setup - emphasize looking to migration plan for architectural and structural decisions
Phase 3 - migration-api - retains Phase 2 decisions; keeps deferred items out-of-scope; limits 1st-gen changes to deprecation notices and clarifies deprecation handling
Phase 5 - migration-a11y - documents behavior for adding delegatesFocus and accessible name forwarding

Also adds global typing related to Window.__swc debugging messages, as copied from 1st-gen.

Motivation and context

Updates made per results in using these skills against the Button migration plan and the need to prioritize the migration plan decisions, as well as make the skill more robust in handling common scenarios and team norms/utilities.

Related issue(s)

fixes SWC-2038

Manual review test cases

Validate the updated skills, and ensure they read as generic/worthy of being global considerations across component migrations.

changeset-bot · 2026-04-24T20:25:34Z

⚠️ No Changeset found

Latest commit: 17ac3e6

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

5t3ph · 2026-04-24T20:28:03Z

@@ -39,4 +39,9 @@ Also read the migration plan at `CONTRIBUTOR-DOCS/03_project-planning/03_compone



Phase 5 - accessibility

5t3ph · 2026-04-24T20:28:33Z

@@ -13,6 +13,25 @@ You are defining a contract, not writing logic. Every property and type you plac



Phase 3 - API / Typescript

miwha-adobe · 2026-04-24T20:29:03Z


 Read the migration plan at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component]/migration-plan.md` when available and use it as the planning baseline for names, deprecations, breaking changes, and consumer migration paths. If it is missing, stale, or intentionally incomplete, derive the needed context from source material and call out the missing plan as a risk. See also [`migration-plan-contract`](../migration-prep/references/migration-plan-contract.md).

+The plan's architectural sections also govern **where each property and type lands**. If Phase 2 established that certain properties belong on the SWC class rather than the base (e.g. for shared-reuse reasons), that decision holds in Phase 3 — do not move those properties to the base class during API migration even if a checklist item implies otherwise. If a checklist item and an architectural section conflict, the architectural section governs; update the checklist and note the reason.


If a checklist item and an architectural section conflict, the architectural section governs;

Very nice!

5t3ph · 2026-04-24T20:29:35Z

@@ -11,7 +11,15 @@ description: Phase 2 of 1st-gen to 2nd-gen component migration. Use to create th



Phase 2 - File structure / Setup exports / Scaffold component

5t3ph · 2026-04-24T20:30:29Z

+ * governing permissions and limitations under the License.
+ */
+
+type ElementLocalName = string;


I was getting a local lint error for __swc - Claude found and copied this from 1st-gen

I got the same suggestion when I looked into the linting error as well.

github-actions · 2026-04-24T20:30:53Z

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

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.

5t3ph · 2026-04-24T20:31:00Z

 }
 ```

+## Deprecation warnings


Originally added in Illustrated Message, notified @miwha-adobe I would be including in this work to get merged in sooner

miwha-adobe · 2026-04-24T20:32:08Z

+
+**Deferred items are out of scope.** The plan may explicitly defer features to follow-up tickets (e.g. form-associated behavior, cross-root ARIA). Do not implement deferred items in Phase 3 even if they appear in the API section of the plan — mark them as skipped and note the tracking ticket.
+
+**1st-gen changes are limited to deprecation notices only.** When adding deprecation notices to 1st-gen, restrict changes to: (1) `@deprecated` JSDoc on exported types, consts, and properties; and (2) `window.__swc.warn()` calls added inside already-existing setters or other existing code paths. Do not refactor 1st-gen code structure — no new backing types, no converting simple properties to getter/setter patterns, no new private fields. TypeScript TS6385 hints that arise from deprecated types referencing each other internally are an accepted side effect and do not require structural fixes.


Question: Could this also be a good place to point to debug-validation.md?

miwha-adobe · 2026-04-24T20:32:47Z

+- Do not add new class statics to 1st-gen just to provide this alternative — that is a refactor and out of scope.
+- For **renames**, note the new name in the JSDoc: "...will be replaced by `newName` in a future release."
+
+For the `window.__swc.warn()` call format and the `{ level: 'deprecation' }` option, follow the **Deprecation warnings** section of [`CONTRIBUTOR-DOCS/02_style-guide/02_typescript/17_debug-validation.md`](../../../CONTRIBUTOR-DOCS/02_style-guide/02_typescript/17_debug-validation.md). Key rules from that guide:


Op, just keep reading Miwha :)

5t3ph · 2026-04-24T20:33:35Z

 - Use them for: **runtime validation** (e.g. in `update()` or setters—check value is in the list), **Storybook** `argTypes` `options`, and **tests** (assert against the same source of truth).
 - See `2nd-gen/packages/core/components/badge/Badge.base.ts` and `2nd-gen/packages/swc/components/badge/Badge.ts`.

+> **When to skip class statics:** If the concrete class is a leaf that is not intended to be subclassed with different valid values, adding `static readonly VARIANTS = BUTTON_VARIANTS` to the class would simply re-point a module-level constant. In that case, referencing the module constant directly in debug/validation code is simpler — and avoids the `(this.constructor as typeof Base).VARIANTS` cast entirely. See `swc-button` (`Button.ts`) as an example: its `update()` references `BUTTON_VARIANTS` and `BUTTON_FILL_STYLES` directly rather than hoisting them as statics.


I don't know a lot about this, but it was in response to seeing Claude create these class statics for things like the size and variant consts when they weren't further modified, which seemed odd. Let me know if there's a reason we should keep that pattern!

I recall when I was building out Illustrated Message, that there was a level of abstraction that was unnecessary. I received a similar suggestion to simplify things by removing the cast.

Basically, since the values provided by the base variants weren't being extended or modified, the cast was unnecessary abstraction. It only makes sense to subclass with different values if you're adding to them, otherwise referencing the module constant directly is simpler. I think thats a reasonable addition into the skills instructions.

miwha-adobe · 2026-04-24T20:33:58Z

+};
+type BrandedSWCWarningID = `${ElementLocalName}:${WarningType}:${WarningLevel}`;
+
+interface Window {


Praise: Thanks for adding this! Was getting linting errors as well

miwha-adobe

Great job!

caseyisonit

love this! miwha called out the things i saw but seems like everything is GROOVY

feat(ai): update skills for phases 2, 3, 5

5761b59

5t3ph requested a review from a team as a code owner April 24, 2026 20:25

5t3ph added Status:Ready for review PR ready for review or re-review. 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. AI tooling labels Apr 24, 2026

5t3ph commented Apr 24, 2026

View reviewed changes

miwha-adobe reviewed Apr 24, 2026

View reviewed changes

5t3ph commented Apr 24, 2026

View reviewed changes

miwha-adobe reviewed Apr 24, 2026

View reviewed changes

5t3ph commented Apr 24, 2026

View reviewed changes

miwha-adobe reviewed Apr 24, 2026

View reviewed changes

miwha-adobe approved these changes Apr 24, 2026

View reviewed changes

fix(ai): improve subheading

17ac3e6

caseyisonit approved these changes Apr 24, 2026

View reviewed changes

5t3ph merged commit 77601d5 into main Apr 24, 2026
29 checks passed

5t3ph deleted the seckles/update-skills-2-5 branch April 24, 2026 21:38

		@@ -39,4 +39,9 @@ Also read the migration plan at `CONTRIBUTOR-DOCS/03_project-planning/03_compone

		@@ -13,6 +13,25 @@ You are defining a contract, not writing logic. Every property and type you plac


		Read the migration plan at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component]/migration-plan.md` when available and use it as the planning baseline for names, deprecations, breaking changes, and consumer migration paths. If it is missing, stale, or intentionally incomplete, derive the needed context from source material and call out the missing plan as a risk. See also [`migration-plan-contract`](../migration-prep/references/migration-plan-contract.md).

		The plan's architectural sections also govern where each property and type lands. If Phase 2 established that certain properties belong on the SWC class rather than the base (e.g. for shared-reuse reasons), that decision holds in Phase 3 — do not move those properties to the base class during API migration even if a checklist item implies otherwise. If a checklist item and an architectural section conflict, the architectural section governs; update the checklist and note the reason.

		@@ -11,7 +11,15 @@ description: Phase 2 of 1st-gen to 2nd-gen component migration. Use to create th


		Deferred items are out of scope. The plan may explicitly defer features to follow-up tickets (e.g. form-associated behavior, cross-root ARIA). Do not implement deferred items in Phase 3 even if they appear in the API section of the plan — mark them as skipped and note the tracking ticket.

		1st-gen changes are limited to deprecation notices only. When adding deprecation notices to 1st-gen, restrict changes to: (1) `@deprecated` JSDoc on exported types, consts, and properties; and (2) `window.__swc.warn()` calls added inside already-existing setters or other existing code paths. Do not refactor 1st-gen code structure — no new backing types, no converting simple properties to getter/setter patterns, no new private fields. TypeScript TS6385 hints that arise from deprecated types referencing each other internally are an accepted side effect and do not require structural fixes.

Conversation

5t3ph commented Apr 24, 2026

Description

Motivation and context

Related issue(s)

Manual review test cases

Uh oh!

changeset-bot Bot commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Choose a reason for hiding this comment

Uh oh!

5t3ph Apr 24, 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!

Choose a reason for hiding this comment

Uh oh!

5t3ph Apr 24, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 24, 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!

Choose a reason for hiding this comment

Uh oh!

miwha-adobe Apr 24, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

miwha-adobe Apr 24, 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!

miwha-adobe Apr 24, 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!

Choose a reason for hiding this comment

Uh oh!

miwha-adobe left a comment

Choose a reason for hiding this comment

Uh oh!

caseyisonit left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot Bot commented Apr 24, 2026 •

edited

Loading

5t3ph Apr 24, 2026 •

edited

Loading

5t3ph Apr 24, 2026 •

edited

Loading

github-actions Bot commented Apr 24, 2026 •

edited

Loading

miwha-adobe Apr 24, 2026 •

edited

Loading

miwha-adobe Apr 24, 2026 •

edited

Loading

miwha-adobe Apr 24, 2026 •

edited

Loading