docs: a11y updates for migration docs

Author: cdransf

2nd-gen/packages/swc/components/badge/migration.md

@@ -176,3 +176,9 @@ All 14 original color variants remain available and are unchanged.
 - When placing a badge alongside an icon in the `icon` slot, ensure the icon is
   decorative (hidden from assistive technology) if the text label already conveys
   the full meaning.
+- For icon-only badges (no visible text), set `aria-label` directly on the `swc-badge`
+  element to provide an accessible name. A badge with no visible text and no
+  `aria-label` has no accessible name and fails WCAG 4.1.2.
+- `variant` does not set any ARIA states. The meaning of a badge comes from its label
+  text, not from the color. Do not add `aria-invalid`, `role="status"`, or similar
+  attributes based on `variant` value alone.

2nd-gen/packages/swc/components/divider/migration.md

@@ -130,9 +130,15 @@ The new internal class names applied to the inner element are:
 ## Accessibility
 
 - `swc-divider` sets `role="separator"` automatically in `firstUpdated`. Do not provide
-  a conflicting `role` attribute unless you have a specific need to override it.
-- When used vertically, `aria-orientation="vertical"` is set automatically.
+  a conflicting `role` attribute.
+- When used vertically, `aria-orientation="vertical"` is set automatically. For
+  horizontal dividers the attribute is omitted, which is correct — the default
+  orientation for `separator` is horizontal.
 - The divider is non-focusable and non-interactive in both generations.
-- `static-color="white"` and `static-color="black"` are intended for use on
-  colored or photographic backgrounds. Ensure sufficient contrast between the divider
-  color and its background.
+- `static-color="white"` and `static-color="black"` are intended for use on colored or
+  photographic backgrounds. Ensure sufficient contrast between the divider color and
+  its background (WCAG 1.4.11 non-text contrast).
+- A divider is a visual supplement to page structure, not a replacement for it.
+  Headings and landmarks still define sections for screen reader users — a divider alone
+  does not communicate that a new section has begun. Use fewer dividers where headings
+  or whitespace can carry the structural meaning.

2nd-gen/packages/swc/components/progress-circle/migration.md

@@ -167,7 +167,9 @@ a light static background that falls outside the normal theme.
 ## Accessibility
 
 - Always provide `label` with a meaningful description. When `label` is set, the
-  component applies `aria-label` to the host element.
+  component applies `aria-label` to the host element. Prefer task-specific labels
+  ("Uploading document", "Processing request") over the generic default ("Loading")
+  whenever context is available.
 - `swc-progress-circle` sets `role="progressbar"` automatically in `firstUpdated`.
   Do not provide a conflicting `role` attribute.
 - In determinate mode (`progress` is set), `aria-valuenow`, `aria-valuemin="0"`,
@@ -177,3 +179,9 @@ a light static background that falls outside the normal theme.
   correctly announces the component as having no known progress value.
 - A development-mode warning is emitted when no accessible name can be determined.
   Provide either `label` or text content in the default slot to satisfy this requirement.
+- Do not add `aria-live="assertive"` to or around `swc-progress-circle` — it will
+  interrupt screen reader users continuously. Use `aria-live="polite"` only when a
+  deliberate status update is needed, and avoid it when multiple components on the page
+  may update simultaneously.
+- Respect `prefers-reduced-motion`. The indeterminate spinner animation should be
+  suppressed or slowed when the user has requested reduced motion.

2nd-gen/packages/swc/components/status-light/migration.md

@@ -195,6 +195,15 @@ All remaining original variants continue to work unchanged.
   meaningful text — do not use the component without a text label, as the indicator dot
   alone conveys no accessible information.
 - Do not rely on color alone to convey status. The text label must independently
-  communicate the state.
+  communicate the state (WCAG 1.4.1).
+- The status dot is rendered as a CSS `::before` pseudo-element and is purely
+  decorative. No additional ARIA attributes are needed for it.
+- Do not add `role="status"` or `aria-live` to `swc-status-light` for static usage.
+  These attributes imply live updates and will cause screen readers to announce the
+  component at unexpected times. If content genuinely updates live, manage the live
+  region at the application level rather than on the component itself.
+- `variant` does not set any ARIA states. The meaning comes from the label text, not
+  the color. Do not map `variant` values to attributes like `aria-invalid` or
+  `aria-label` automatically.
 - With `disabled` removed, there is no mechanism to convey "unavailable" visually
   beyond writing it in the label text. This is intentional per the Spectrum 2 spec.