Migrate UserAvatar web component from ibm-products to @carbon/web-components #22949

Summary

Migrate the UserAvatar web component from carbon-for-ibm-products into the Carbon core monorepo as part of the selective component migration tracked in the parent epic.

Custom element tag: cds-user-avatar
Source: ibm-products-web-components/src/components/user-avatar
Target: packages/web-components/src/components/user-avatar/
Target status: Stable
Notes: React counterpart tracked under #22792.

React counterpart: #22792

Parent epic: #22794

Checklist

• LitElement class (user-avatar.ts) — @customElement, @property, @state decorators; prefix from ../../globals/settings; carbonElement decorator; no ibm-products utilities
• index.ts — registers the custom element only
• Export added to packages/web-components/src/index.ts
• Component styles (user-avatar.scss) — scoped to :host(cds-user-avatar); uses @carbon/styles tokens; not added to packages/styles/scss/components/_index.scss
• Stories (user-avatar.stories.ts) — CSF3, const meta = { ... }; export default meta
• MDX docs page (user-avatar.mdx) — usage examples, <ArgTypes of="cds-user-avatar" />
• Unit tests (__tests__/user-avatar-test.js) — @open-wc/testing, shadow DOM queries, await el.updateComplete
• All lint, type-check, and test checks pass

How to verify

• Perform manual testing in v12 Storybook
• Confirm cds-user-avatar is exported from @carbon/web-components
• Verify parity with the React UserAvatar component (Migrate UserAvatar from @carbon/ibm-products to Carbon core #22792)
• Verify the migration is complete:
  • Delete the component from the ibm-products-web-components repo
  • Copy the migrated folder back and verify the diff in git source control
  • Compare styles to ensure no unintended changes were introduced