chore(dropzone): storybook docs and consumer migration guide

[cdransf]

Description

Adds the remaining Phase 7 documentation deliverables for the Dropzone 2nd-gen migration: the per-component Storybook docs page, the Behaviors and Accessibility stories, and a dedicated consumer migration guide describing how to move from <sp-dropzone> to <swc-dropzone>.

• 2nd-gen/packages/swc/components/dropzone/dropzone.mdx: new per-component docs page covering Anatomy, Options (sizes), States, Behaviors (event log, browse-and-drop), Accessibility, and Upcoming features.
• 2nd-gen/packages/swc/components/dropzone/stories/dropzone.stories.ts: adds the EventLog, BrowseAndDrop, and Accessibility stories; wires up Figma and Stackblitz links in story metadata; drops the stale autodocs tag now that the MDX page exists; adds a "Replace file" control to the filled-state examples so a control stays reachable by keyboard after a file is accepted.
• 2nd-gen/packages/swc/components/dropzone/Dropzone.ts: adds a missing @cssprop tag for --swc-illustrated-message-illustration-color, found during the @cssprop completeness review.
• 2nd-gen/packages/swc/components/dropzone/migration-guide.mdx: new consumer-facing migration guide covering the sp- → swc- tag rename, isDragged/isFilled → dragged/filled property renames, event renames (including the swc-dropzone-dragleave detail shape change), the filled-content slot behavior change, the now-required accessible name, and the --mod-* → --swc-* CSS custom property changes.
• CONTRIBUTOR-DOCS/03_project-planning/03_components/dropzone/migration-plan.md: Documentation phase checklist items checked off to reflect completed work.
• CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/01_status.md: status table updated for Dropzone.

Motivation and context

Dropzone is not considered production-ready without Storybook documentation that captures the necessary 1st-gen content and a migration guide that gives application developers a clear, verified upgrade path. This PR closes both open documentation gaps identified in the ticket.

Related issue(s)

• fixes SWC-2151

Screenshots (if appropriate)

N/A — documentation-only change. New stories and docs pages are visible under Drop Zone in Storybook (Behaviors, Accessibility) and under Drop Zone / Migration guide.

Author's checklist

• I have read the CONTRIBUTING 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.
• 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

• Storybook docs page renders correctly

  1. Go to Storybook and open Drop Zone
  2. Confirm the Docs page renders with Anatomy, Options, States, Behaviors, Accessibility, and Upcoming features sections, each with a working canvas
  3. Expect no console errors and all <Canvas> blocks to render the correct story

• New Behaviors stories work as documented

  1. Open the Event log story under Drop Zone > Docs > Behaviors
  2. Drag a file over the drop zone and drop it
  3. Expect the event log list to show swc-dropzone-dragover followed by swc-dropzone-drop
  4. Open the Browse and drop story
  5. Click "Browse files", select a file, and confirm the zone switches to its filled state showing the file name and a "Replace file" button

• Migration guide is accurate

  1. Go to Storybook and open Drop Zone / Migration guide
  2. Follow steps 1-6 against a local 1st-gen <sp-dropzone> usage
  3. Expect the guide's before/after snippets to compile and run without further changes needed

Device review

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

Accessibility testing checklist

• Keyboard (required — document steps below)

  1. Go to Storybook, open Drop Zone, and select the Accessibility story
  2. Press Tab until focus reaches the "Browse files" button inside the drop zone
  3. Expect a visible focus ring and the button to be reachable without ever landing on the <swc-dropzone> host itself (it has no tabindex)
  4. Press Enter or Space to activate "Browse files" and select a file from the OS picker
  5. Expect the drop zone to switch to its filled state and a "Replace file" button to become the next focusable element in the same position
  6. Press Tab again and confirm "Replace file" receives focus and re-opens the file picker on Enter/Space

• Screen reader (required — document steps below)

  1. Go to Storybook, open Drop Zone, and select the Accessibility story with a screen reader active (VoiceOver or NVDA)
  2. Switch to browse mode and navigate to the drop zone
  3. Expect the group boundary to announce its accessible name (e.g. "Upload a profile photo, group")
  4. Drag a file over the zone (or use the Browse control) and confirm the visually hidden status region announces "File ready to drop" and then "File accepted" without moving focus
  5. With the zone already filled, drag a new file over it and confirm the status region announces "Drop to replace existing file"

[github-actions]

📚 Branch Preview Links

• Storybook (Gen2, dev mode)
• Storybook (Gen2, prod mode)
• Documentation Site (Gen1)
• Storybook (Gen1)

🔍 Gen1 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-6516

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.

[coveralls]

Coverage Report for CI Build 29454575226

Warning

No base build found for commit 854bee5 on cdransf/s2-dropzone-migration.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 96.257%

Details

• Patch coverage: No coverable lines changed in this PR.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

Requires a base build to compare against. How to fix this →

---

Coverage Stats

Relevant Lines:	39169
Covered Lines:	37903
Line Coverage:	96.77%
Relevant Branches:	6458
Covered Branches:	6016
Branch Coverage:	93.16%
Branches in Coverage %:	Yes
Coverage Strength:	461.12 hits per line

---

💛 - Coveralls

[changeset-bot]

⚠️ No Changeset found

Latest commit: d6cc109

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

[cdransf]

Removing this as we decided to omit Figma links for the time being. ✨

[cdransf]

dropEffect had no @property decorator, so drop-effect="..." in markup was a silent no-op (1st-gen had the same gap). The attribute's live at parse and run-time now. Also added test coverage and updated the api table. ✨