Merge branch 'swc-1668/poc-components' into marissahuysentruyt/swc-1670-progress-circle

Author: caseyisonit

.ai/README.md

@@ -219,11 +219,61 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re
 - Use when: On the analyze-rendering-and-styling step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`
 - Provides: Workflow summary (specs from CSS + SWC, three-way DOM comparison, CSS⇒SWC mapping table, summary). Full instructions in `CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/cursor_prompt.md`
 
-#### Washing machine migration workflow
+#### Migration — phase 1: prep (`migration-prep`)
 
-- **purpose**: End-to-end 1st-gen → 2nd-gen migration sequence (phases, checklists, links to step docs and style guides)
-- **Doc**: `CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md`
-- Use when: Planning or executing a component migration in the 2nd-gen component migration workstream
+- **purpose**: Understand the component, plan breaking changes, and define scope before any refactoring begins
+- **How to invoke**: Say "start migration prep for [component]", "plan the migration for [component]", or "phase 1 migration for [component]"
+- Use when: Beginning a 1st-gen → 2nd-gen component migration; before any files are created or code is moved
+- Provides: Research checklist (1st-gen API, usage, tests), breaking-change analysis, scope definition, written plan for review
+
+#### Migration — phase 2: setup (`migration-setup`)
+
+- **purpose**: Create the 2nd-gen file and folder structure, wire up exports, and confirm the build passes before implementation begins
+- **How to invoke**: Say "set up 2nd-gen structure for [component]", "create the file structure for [component]", or "phase 2 migration for [component]"
+- Use when: After prep is complete; creating the scaffolding a component needs before any logic is ported
+- Provides: File/folder creation checklist, export wiring steps, build-passes verification
+
+#### Migration — phase 3: API (`migration-api`)
+
+- **purpose**: Move properties, methods, and types from 1st-gen to 2nd-gen while maintaining a clear public API
+- **How to invoke**: Say "migrate the API for [component]", "port properties and methods for [component]", or "phase 3 migration for [component]"
+- Use when: Scaffolding is in place and it's time to define the component's public contract in 2nd-gen
+- Provides: Property/method porting workflow, type definition guidance, API contract review
+
+#### Migration — phase 4: styling (`migration-styling`)
+
+- **purpose**: Migrate CSS to the 2nd-gen structure, apply Spectrum 2 tokens, and ensure stylelint passes
+- **How to invoke**: Say "migrate styling for [component]", "port CSS for [component]", or "phase 4 migration for [component]"
+- Use when: API is in place; translating 1st-gen CSS to 2nd-gen with Spectrum 2 design tokens
+- Provides: CSS migration checklist, token mapping guidance, stylelint validation steps
+
+#### Migration — phase 5: accessibility (`migration-a11y`)
+
+- **purpose**: Implement WCAG-aligned semantics, ARIA, keyboard support, and focus management, and document accessibility behavior
+- **How to invoke**: Say "migrate accessibility for [component]", "implement a11y for [component]", or "phase 5 migration for [component]"
+- Use when: Styling is complete; hardening the component's accessibility implementation
+- Provides: WCAG checklist, ARIA pattern guidance, keyboard/focus requirements, a11y documentation template
+
+#### Migration — phase 6: testing (`migration-testing`)
+
+- **purpose**: Write unit tests, accessibility tests, and Storybook play functions for a migrated component
+- **How to invoke**: Say "write tests for [component] migration", "add migration tests for [component]", or "phase 6 migration for [component]"
+- Use when: Implementation is feature-complete; adding test coverage before review
+- Provides: Test coverage checklist, unit/a11y/play-function patterns, test-running verification
+
+#### Migration — phase 7: documentation (`migration-documentation`)
+
+- **purpose**: Write JSDoc, Storybook stories, and usage docs so the component is usable and understandable by others
+- **How to invoke**: Say "write docs for [component] migration", "document [component] for 2nd-gen", or "phase 7 migration for [component]"
+- Use when: Tests pass; creating the Storybook stories and usage documentation for the migrated component
+- Provides: JSDoc guidelines, stories scaffolding, README/usage doc structure, documentation checklist
+
+#### Migration — phase 8: review (`migration-review`)
+
+- **purpose**: Run final checks, verify lint/tests/build/Storybook, update the workstream status table, and open a PR
+- **How to invoke**: Say "review [component] migration", "final checks for [component]", or "phase 8 migration for [component]"
+- Use when: Documentation is complete; preparing the migration for code review and merge
+- Provides: Pre-PR checklist (lint, tests, build, Storybook), workstream status update steps, PR description guidance
 
 #### Deep understanding
 

.ai/skills/migration-a11y/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: migration-a11y
+description: Phase 5 of 1st-gen to 2nd-gen component migration. Use to implement WCAG-aligned semantics, ARIA, keyboard support, and focus management, and document accessibility behavior.
+---
+
+# Migration a11y ([Phase 5](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md))
+
+[Phase 5](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to implement WCAG-aligned behavior — semantics, ARIA, keyboard support, and focus management — and verify it with assistive technology and automated tests.
+
+See also: [`accessibility-compliance`](../accessibility-compliance/SKILL.md) for general WCAG 2.2 patterns, ARIA reference, and testing tools.
+
+## Mindset
+
+You are an implementer working from evidence, not assumptions. Read the accessibility migration analysis doc first. Every ARIA attribute you add must be justified by the APG pattern or WCAG criterion. If there is no analysis doc yet, stop and create one using the `accessibility-migration-analysis` skill before implementing.
+
+## When to use this skill
+
+- Phase 4 (migration-styling) is complete
+- The user asks to "implement accessibility" or "add a11y" for a component
+- The user asks to add keyboard support, ARIA, or screen reader behavior
+- The user refers to "Phase 5" of the 2nd-gen component migration workstream
+
+## When NOT to use
+
+- Phase 4 is not complete — styling should be in place before a11y testing
+- You need general WCAG or ARIA reference — use the [`accessibility-compliance`](../accessibility-compliance/SKILL.md) skill
+
+## How to invoke
+
+- "Implement accessibility for [component]"
+- "Add a11y for [component]"
+- "Phase 5 for [component] migration"
+
+---
+
+## Workflow
+
+Follow **[Phase 5: Accessibility](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-5-accessibility)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.

.ai/skills/migration-api/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: migration-api
+description: Phase 3 of 1st-gen to 2nd-gen component migration. Use to move properties, methods, and types from 1st-gen to 2nd-gen while maintaining a clear public API.
+---
+
+# Migration API ([Phase 3](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md))
+
+[Phase 3](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to migrate properties, methods, and types from 1st-gen to 2nd-gen — keeping the public API clear, types in core, and internal helpers marked appropriately.
+
+## Mindset
+
+You are defining a contract, not writing logic. Every property and type you place here is a public commitment. Put shared things in core, generation-specific things in SWC, and mark anything temporary with a `@todo`. If you are unsure where something belongs, ask the user, and/or use the `ask-questions` skill.
+
+## When to use this skill
+
+- Phase 2 (migration-setup) is complete and the file structure exists
+- The user asks to "migrate the API" or "move properties/types" for a component
+- The user asks to implement static arrays, debug warnings, or 1st-gen deprecations
+- The user refers to "Phase 3" of the 2nd-gen component migration workstream
+
+## When NOT to use
+
+- Phase 2 is not complete — the core/SWC file structure must exist first
+- You are implementing `render()` or styles — those are later phases
+
+## How to invoke
+
+- "Migrate the API for [component]"
+- "Move properties and types for [component]"
+- "Phase 3 for [component] migration"
+
+---
+
+## Workflow
+
+Follow **[Phase 3: API Migration](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-3-api-migration)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.

.ai/skills/migration-documentation/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: migration-documentation
+description: Phase 7 of 1st-gen to 2nd-gen component migration. Use to write JSDoc, Storybook stories, and usage docs so the component is usable and understandable by others.
+---
+
+# Migration documentation ([Phase 7](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md))
+
+[Phase 7](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is JSDoc on the public API, Storybook stories covering the main use cases, and migration notes where the API diverges from 1st-gen.
+
+See also: [`documentation`](../documentation/SKILL.md) for Adobe content writing standards to follow when writing usage docs and migration notes.
+
+## Mindset
+
+You are writing for the next contributor, not for yourself. Every story, JSDoc line, and migration note should answer the question a new engineer would ask six months from now. Avoid restating the implementation. Explain the intent, the constraints, and why the decisions were made. Be sure to follow the `documentation` skill for writing style and content expectations.
+
+## When to use this skill
+
+- Phase 6 (migration-testing) is complete
+- The user asks to "document [component]" or "add stories for [component]"
+- The user asks to write JSDoc, add Storybook stories, or document migration notes
+- The user refers to "Phase 7" of the 2nd-gen component migration workstream
+
+## When NOT to use
+
+- Phase 6 is not complete — tests should pass before documentation is finalized
+- You are updating docs for an existing component unrelated to migration
+
+## How to invoke
+
+- "Document [component]"
+- "Add stories for [component]"
+- "Phase 7 for [component] migration"
+
+---
+
+## Workflow
+
+Follow **[Phase 7: Documentation](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-7-documentation)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.

.ai/skills/migration-prep/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: migration-prep
+description: Phase 1 of 1st-gen to 2nd-gen component migration. Use to understand the component, plan breaking changes, and define scope before any refactoring begins.
+---
+
+# Migration prep (Phase 1)
+
+[Phase 1](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to thoroughly understand the component and produce a written migration plan—covering API surface, breaking changes, file layout, and naming decisions—before any code is moved or refactored.
+
+## Mindset
+
+You are a planner, not an implementer. Your job is to produce a written plan the team can review and challenge before a single line of code moves. Resist the urge to start implementing. Remember that a wrong plan caught in review is cheaper than a wrong implementation caught in testing.
+
+## When to use this skill
+
+- You are starting a 1st-gen → 2nd-gen component migration
+- The user asks to "prep" or "prepare" a component for migration
+- The user asks to plan or scope a component migration before implementation
+
+## When NOT to use
+
+- You are already past Phase 1 (refactoring, creating files, implementing)
+
+## How to invoke
+
+- "Prep [component] for migration"
+- "Run migration prep for [component]"
+- "Phase 1 for [component] migration"
+
+---
+
+## Workflow
+
+Follow **[Phase 1: Preparation](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-1-preparation)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.

.ai/skills/migration-review/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: migration-review
+description: Phase 8 of 1st-gen to 2nd-gen component migration. Use to run final checks, verify lint/tests/build/Storybook, update the workstream status table, and open a PR.
+---
+
+# Migration review ([Phase 8](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md))
+
+[Phase 8](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is final checks — lint, tests, build, and Storybook — then updating the workstream status table and opening a PR.
+
+## Mindset
+
+You are a gatekeeper, not a rubber stamp. A passing build and green tests are the minimum expectations. Read the diff as if you are a reviewer who did not write this code. Look for missing edge cases, inconsistent conventions, and anything the automated checks cannot catch. Use the style guides in `CONTRIBUTOR-DOCS/02_style-guide` when enforcing code styles.
+
+## When to use this skill
+
+- All previous phases are complete
+- The user asks to "review [component]", "finalize [component]", or "open a PR for [component]"
+- The user refers to "Phase 8" of the 2nd-gen component migration workstream
+
+## When NOT to use
+
+- Phase 7 is not complete — documentation and stories should be finalized before review
+- You are resolving a lint, test, or build failure that belongs to an earlier phase (e.g. stylelint errors → Phase 4, failing unit or a11y tests → Phase 6)
+
+## How to invoke
+
+- "Review [component] migration"
+- "PR review for [component]"
+- "Phase 8 for [component] migration"
+
+---
+
+## Workflow
+
+Follow **[Phase 8: Review](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-8-review)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.

.ai/skills/migration-setup/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: migration-setup
+description: Phase 2 of 1st-gen to 2nd-gen component migration. Use to create the 2nd-gen file and folder structure, wire up exports, and confirm the build passes before implementation begins.
+---
+
+# Migration setup (Phase 2)
+
+[Phase 2](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to create the core and SWC directory structure, stub out the required files, and confirm the component is importable before any implementation work begins.
+
+## Mindset
+
+You are building a foundation, not a feature. Every file you create here is a contract: the right structure now prevents expensive restructuring later. Stub first, verify the build passes, then stop — implementation comes in later phases.
+
+## When to use this skill
+
+- Phase 1 (migration-prep) is complete and the migration plan is approved
+- The user asks to "set up" or "scaffold" a component for 2nd-gen migration
+- The user asks to create the core/SWC file structure for a component
+- The user refers to "Phase 2" of the 2nd-gen component migration workstream
+
+## When NOT to use
+
+- Phase 1 is not complete — write and get team review on the migration plan first
+- You are implementing data model, rendering, or styles — those are later phases
+
+## How to invoke
+
+- "Set up [component] for migration"
+- "Scaffold [component] for 2nd-gen"
+- "Phase 2 for [component] migration"
+- "Create the core and SWC structure for [component]"
+
+---
+
+## Workflow
+
+Follow **[Phase 2: Setup](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-2-setup)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.

.ai/skills/migration-styling/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: migration-styling
+description: Phase 4 of 1st-gen to 2nd-gen component migration. Use to migrate CSS to the 2nd-gen structure, apply Spectrum 2 tokens, and ensure stylelint passes.
+---
+
+# Migration styling ([Phase 4](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md))
+
+[Phase 4](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to migrate CSS to the 2nd-gen structure, replace hard-coded values with tokens, and ensure the component's CSS passes stylelint with no errors.
+
+## Mindset
+
+You are translating, not redesigning. Your job is not to invent new visual decisions. Use the `rendering-and-styling-migration-analysis.md` file that corresponds to the component you are migrating. When the token you need does not exist, use the `ask-questions` skill to flag it with the user. Refer to the CSS styling guides in `CONTRIBUTOR-DOCS/02_style-guide/` when refactoring the CSS (i.e. change `--spectrum` prefixes to `--swc`; `.spectrum*` classes to `.swc*`; `--mod` prefixes should not exist). The CSS style guides are the preferred way to write the CSS, as opposed to any recommendations you find in the rendering analysis doc.
+
+## When to use this skill
+
+- Phase 3 (migration-api) is complete
+- The user asks to "migrate styles" or "migrate CSS" for a component
+- The user asks to apply Spectrum 2 tokens or fix stylelint errors
+- The user refers to "Phase 4" of the 2nd-gen component migration workstream
+
+## When NOT to use
+
+- Phase 3 is not complete — the API must be migrated first
+- You are working on `render()` or template structure — check the workflow doc for rendering context
+
+## How to invoke
+
+- "Migrate styles for [component]"
+- "Phase 4 for [component] migration"
+- "Apply Spectrum 2 tokens for [component]"
+
+---
+
+## Workflow
+
+Follow **[Phase 4: Styling](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-4-styling)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.