feat(tooltip): documentation, consumer migration guide

[5t3ph]

Description

Completes Phase 7 (documentation), and adds the consumer migration guide for swc-tooltip.

Phase 7 — Documentation

• Storybook stories: Playground, Overview, Anatomy, Options (variants, placements), States (open), Behaviors (events, auto-stack), Accessibility, and UpcomingFeatures (additive-phase items)
• JSDoc on all public properties, slots, and --swc-tooltip-background-color CSS custom property

Consumer migration guide

• New migration-guide.mdx at 2nd-gen/packages/swc/components/tooltip/
• Covers all six breaking changes (B1–B6): icon slot removal, variant="positive" removal, variant="info" rename, event renames with timing change, self-managed removal and new for-based sibling authoring pattern
• Prominent initial-release scope callout: automatic hover/focus wiring and pixel positioning are not yet available; includes manual event wiring pattern for the current release
• --mod-tooltip-* breaking change callout and --swc-tooltip-background-color public property table
• Migration plan checklist updated; all consumer migration guide items marked complete

Motivation and context

Tooltip is the first 2nd-gen component with non-trivial behavioral complexity (native popover, ARIA wiring via ariaDescribedByElements, additive controller architecture). The consumer migration guide specifically calls out what works today vs. what ships in a future release to prevent consumers from expecting hover/focus auto-wiring that isn't yet active.

Related issue(s)

• SWC-2026
• SWC-2027

[changeset-bot]

⚠️ No Changeset found

Latest commit: ba73d86

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

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.

[cdransf]

Looks good! Just had one question ✨

[rubencarvalho]

Looks good! We just need to make sure to update the "hover" section when we integrate the HoverController! 😄
Also, please check if the global-button.css should be included 👍

[rubencarvalho]

Is this supposed to be commited?

[rubencarvalho]

This is nice, but I feel like our whole SB customization needs some love 😛 cc: @caseyisonit