feat(avatar): migrate avatar component to S2

[cdransf]

Description

Migrates sp-avatar to 2nd-gen swc-avatar as part of the Spectrum 2 component migration epic.

What's included:

• Core layer (2nd-gen/packages/core/components/avatar/) — AvatarBase class with src, alt, size,
  showStroke, and disabled properties; AvatarSize type and AVATAR_VALID_SIZES constant; label
  compatibility shim with DEBUG deprecation warning
• SWC layer (2nd-gen/packages/swc/components/avatar/) — Avatar concrete class extending AvatarBase;
  S2-aligned CSS using design tokens for all 17 sizes (50–1500); show-stroke outline support; disabled
  reduced-opacity state
• Storybook — Playground, Overview, Anatomy, Sizes, Decorative, ShowStroke, Disabled, InActionButton, and
  Accessibility stories; breaking-changes table in component JSDoc; full argType defaults
• Tests — 15 Storybook play-function test stories covering defaults, property reflection, size validation,
  aria-hidden toggling, disabled state, and DEBUG warnings; 6 Playwright ARIA snapshot tests
• Docs — migration.md consumer migration guide; migration plan with all phases complete
• Global — hides SpectrumElement infrastructure members (dir, VERSION, CORE_VERSION,
  hasVisibleFocusInTree) from every component's Storybook API table

Motivation and context

swc-avatar is the Spectrum 2 implementation of the avatar component. Key changes from 1st-gen: label →
alt, is-decorative → alt="", linked variant removed (wrap in <a> instead), default size changed from
100 to 500, size scale extended to 1500, disabled state retained (now applies to any avatar at reduced
opacity rather than only the linked variant).

Related issue(s)

• SWC-1805

---

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

• Default labeled avatar renders as a circle with correct alt text

  1. Open Storybook and navigate to Avatar → Overview
  2. Inspect the rendered <swc-avatar> — confirm size attribute is 500 and no aria-hidden attribute is
     present
  3. In the shadow DOM, confirm <img alt="Jane Doe"> is present

• Decorative avatar is hidden from the accessibility tree

  1. Navigate to Avatar → Decorative
  2. Confirm aria-hidden="true" is present on the <swc-avatar> host element
  3. Verify no img role appears in the browser's accessibility tree inspector

• show-stroke outline renders correctly on dark backgrounds

  1. Navigate to Avatar → Show Stroke
  2. Confirm both avatars (size 500 and 1000) show a visible outline against the gradient background
  3. The size-1000 avatar outline should appear slightly thicker (2 px vs 1 px)

• Disabled avatar renders at reduced opacity

  1. Navigate to Avatar → Disabled
  2. Confirm the avatar image is visibly faded (30% opacity)
  3. Confirm disabled attribute is present on the <swc-avatar> host element
  4. Confirm the avatar is still announced by a screen reader (not hidden from the accessibility tree)

• All 17 sizes render correctly

  1. Navigate to Avatar → Sizes
  2. Confirm avatars scale from 16 px (size 50) to 104 px (size 1500) with no clipping or distortion

---

Accessibility testing checklist

• Keyboard — swc-avatar is a static, non-interactive element and receives no focus on its own.
  Keyboard accessibility for linked avatars is provided by a wrapping <a>.

  1. Open Storybook and navigate to Avatar → Overview
  2. Tab through the page — confirm swc-avatar is skipped entirely (not in tab order)
  3. Navigate to Avatar → In Action Button — confirm Tab reaches the wrapping <button> and Enter/Space
     activate it

• Screen reader — swc-avatar exposes an img role with alt text through the shadow DOM.

  1. Open Avatar → Overview with a screen reader active (VoiceOver / NVDA)
  2. Navigate to the avatar — confirm it is announced as "Jane Doe, image" (or equivalent)
  3. Open Avatar → Decorative — confirm the avatar is not announced at all (hidden via aria-hidden="true")
  4. Open Avatar → Disabled — confirm the avatar is still announced normally (disabled does not hide it from
     AT)

[changeset-bot]

⚠️ No Changeset found

Latest commit: de8b3f7

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]

📚 Branch Preview Links

• Documentation Site (first-gen)
• Storybook (first-gen)
• Storybook (second-gen)

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

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6113

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.