feat(icon): make swc-icon public with BYO SVG docs and private elements catalog

[TarunAdobe]

Description

Make <swc-icon> a public 2nd-gen component: public Storybook docs, consumer migration guide, and npm export boundary — while keeping the internal elements/ SVG catalog monorepo-only.
Included in this PR:

• Contributor icon migration plan
• Remove @status internal from swc-icon JSDoc (match badge/button: @since only)
• Export Icon only from components/icon/index.ts (stop leaking factories via @adobe/spectrum-wc/icon)
• Public icon.stories.ts, icon.mdx, and migration-guide.mdx (BYO SVG; no public elements/ import path)
• Trim icon.internal.* to maintainer catalog (dev Storybook only; prod excludes *.internal.*)
• Fix conversational-ai pattern imports to use relative elements/ paths
• Update JSDoc @example to inline SVG only
• Changeset for @adobe/spectrum-wc

---

Motivation and context.

<swc-icon> already exists in 2nd-gen and is used internally (badge, patterns, etc.), but it is marked internal and excluded from production Storybook. Consumers upgrading from <sp-icon> need a documented public wrapper that accepts slotted SVG, not iconset registry lookup. The internal elements/ factories stay a maintainer convenience for SWC development — not a public icon catalog.

---

Related issue(s)

• N/A

---

Screenshots (if appropriate)

N/A — docs and export-boundary change. Verify in Storybook after merge.

Author's checklist

• I have read the [CONTRIBUTING](https://github.com/adobe/spectrum-web components/blob/main/CONTRIBUTING.md) and
  PULL_REQUESTS documents.
• I have reviewed the Accessibility Practices for this feature, see: Aria Practices
• I have added automated tests to cover my changes. (Existing icon unit + Playwright a11y tests; re-run after public story rename.)
• 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

• Public icon docs (production Storybook build)
  1. Run yarn storybook:build in 2nd-gen/packages/swc
  2. Open the Icon docs page under Components
  3. Expect: Overview, Sizes, Anatomy, Accessibility — all demos use inline SVG
  4. Expect: no "Shared templates" / "Available icons" / elements/ import guidance on the public page
• Internal catalog (dev Storybook only)
  1. Run yarn storybook in 2nd-gen/packages/swc
  2. Open Icon internal docs (icon.internal.mdx stories)
  3. Expect: maintainer catalog and elements/ reference still available locally
• Consumer migration guide
  1. Open Icon → Migration guide in Storybook
  2. Expect: sp-icon → swc-icon, slot SVG, no @adobe/spectrum-wc/.../elements import path
  3. Expect: breaking changes documented (name, src, xxs/xxl, --mod-icon-*)
• Package export boundary
  1. Confirm components/icon/index.ts exports Icon only
  2. Confirm @adobe/spectrum-wc/icon does not re-export Chevron100Icon etc.
  3. Spot-check badge docs still show correct <swc-icon> + aria-hidden guidance
• Downstream patterns
  1. Open conversational-ai pattern stories that use chevrons
  2. Expect: no @adobe/spectrum-wc/icon/elements imports in source; icons render correctly

Device review

• Did it pass in Desktop?
• Did it pass in (emulated) Mobile?
• Did it pass in (emulated) iPad?

Accessibility testing checklist

Icon a11y behavior is unchanged (slot SVG gets role="img"; label sets aria-label; no label → aria-hidden).
Re-verify on public docs stories.

• Keyboard (required — document steps below)
  1. Open Icon → Accessibility story in Storybook
  2. Tab through the page
  3. Expect: <swc-icon> is not focusable; no spurious focus stops on decorative icons
• Screen reader (required — document steps below)
  1. Open Icon → Overview (labelled) and a decorative example (no label)
  2. With VoiceOver/NVDA, inspect the labelled icon
  3. Expect: labelled icon announced as image with name (e.g. "Search")
  4. Expect: decorative icon (no label) hidden from the accessibility tree

[changeset-bot]

⚠️ No Changeset found

Latest commit: 509696a

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-6415

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.