// Phase 4 of 1st-gen to 2nd-gen component migration. Use to implement WCAG-aligned semantics, ARIA, keyboard support, and focus management, and document accessibility behavior.
| name | migration-a11y |
| description | Phase 4 of 1st-gen to 2nd-gen component migration. Use to implement WCAG-aligned semantics, ARIA, keyboard support, and focus management, and document accessibility behavior. |
Phase 4 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 for general WCAG 2.2 patterns, ARIA reference, and testing tools.
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.
Also read the migration plan at CONTRIBUTOR-DOCS/03_project-planning/03_components/[component]/migration-plan.md when available for must-ship accessibility changes, behavior changes that affect semantics, renamed states or props, and unresolved questions that may impact keyboard or focus behavior. 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.
accessibility-compliance skillFollow Phase 4: Accessibility in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.
Phase 4 often requires TypeScript changes, not only documentation. Common examples:
delegatesFocus: true; custom control (e.g. Radio) → role and aria-* on host, manage focus/keyboard. See Checkbox and Radio as reference implementations.delegatesFocus: true — If the component wraps a native control in its shadow DOM, add createRenderRoot() returning this.attachShadow({ mode: 'open', delegatesFocus: true }). This routes host focus to the internal native control. Add it in the base class if all subclasses share the same host-wraps-native-control structure.aria-label on the host are not automatically visible to the internal control. Forward them in the render template or via a protected helper method (e.g. getResolvedAccessibleName()). If the pattern is shared across multiple like components, put the helper in the base class.If accessibility implementation needs to deviate from the migration plan, follow migration-plan-contract.
Use when creating a per-component migration guide for application developers upgrading from Spectrum 1 Web Components to Spectrum 2 components.
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.
Phase 5 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.
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.
Sub-task after Phase 6 of 1st-gen to 2nd-gen component migration. Use to verify all migrated files conform to the project style guides, run linters, and surface any guideline gaps as PR comment notes.
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.