chore(dropzone): full fidelity

[cdransf]

Description

Phase 5 (CSS migration and stories) of the swc-dropzone Spectrum 2 migration. This PR is stacked on top of the file-structure PR and should be merged after that PR lands.

Changes in this PR:

• Dropzone.types.ts — Added DropzoneSize type and DROPZONE_VALID_SIZES constant ('s' | 'm' | 'l'); added DropzoneEventDetail type alias for consumers who imported it from the 1st-gen package
• Dropzone.base.ts — Applied SizedMixin with validSizes: DROPZONE_VALID_SIZES to expose the size attribute on the base class; size is new in 2nd-gen (not in 1st-gen)
• Dropzone.ts — Updated render() to emit a .swc-Dropzone wrapper and a swc-Dropzone-status visually-hidden live region; added @cssprop JSDoc for all five exposed custom properties; fixed @param name mismatch in _onDragStateChange JSDoc
• dropzone.css — Full S2 token-based stylesheet: CSS-only dashed/solid border, size-variant padding overrides, dragged and filled state selectors, --swc-illustrated-message-illustration-color cascade for accent-colored illustration in dragged state, and @media (forced-colors: active) block
• dropzone.stories.ts — New stories file with Playground, Overview, Anatomy, Sizes (options), and States stories; Behaviors and Accessibility stubs deferred to Phase 7
• preview.ts — Added 'Migration plan' to the Dropzone reference doc list in the Storybook sidebar

Motivation and context

This is Phase 5 of the Dropzone Spectrum 2 migration. The CSS migration replaces the 1st-gen Spectrum CSS dependency with 2nd-gen S2 tokens (token() calls), introduces size variants (new in 2nd-gen), and ensures the component renders correctly in both default and dragged/filled states.

Key design decisions resolved during this phase:

• CSS-only border — decided to use CSS border (dashed/solid toggling) rather than an SVG stroke, matching the current spectrum-css main branch approach; SVG stroke can be revisited if the Figma or CSS spec diverges
• Illustrated-message accent color — --swc-illustrated-message-illustration-color is set on :host([dragged]) and cascades through the DOM into swc-illustrated-message's shadow via normal CSS custom property inheritance; no ::slotted() selector needed for color

Related issue(s)

• SWC-2149

Screenshots (if appropriate)

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. (Phase 6 — deferred to a follow-up PR)
• I have included a well-written changeset if my change needs to be published.
• I have included updated documentation if my change required it. (Migration plan and status table updated)

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 state renders correctly

  1. Open Storybook → Drop Zone → Docs
  2. Confirm the zone shows a dashed gray border, transparent background, and correct padding for size m
  3. No console errors

• Dragged state applies correctly

  1. Open Storybook → Drop Zone → States
  2. The "dragged" instance should show a solid accent-colored border, an accent-tinted background, and the illustrated message SVG should be accent-colored
  3. Toggle dragged in the Playground controls; confirm the transition is immediate

• Filled state hides the illustrated message

  1. In the States story, the "filled" instance should show content (uploaded file name) with the illustrated message hidden
  2. The filled+dragged instance should show the dragged visual treatment without the illustrated message

• Size variants change padding only

  1. In the Sizes story, compare s, m, and l instances
  2. Only padding should differ; border and corner radius should be identical across sizes

• Forced-colors / high-contrast mode

  1. Enable forced-colors in browser DevTools (Rendering panel → Emulate CSS media feature)
  2. Default: border uses ButtonText; dragged: background Canvas, border Highlight

Device review

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

Accessibility testing checklist

Required: Complete each applicable item and document your testing steps.

• Keyboard (required — document steps below)

  1. Open Storybook → Drop Zone → Playground
  2. Tab into the drop zone; confirm role="group" is announced and the accessible name is read
  3. Tab to the "Browse files" button inside; confirm it receives focus and can be activated with Enter or Space
  4. Confirm no focus is trapped inside the drop zone region itself

• Screen reader (required — document steps below)

  1. Open Storybook → Drop Zone → States
  2. Navigate to the "Dragged" instance; confirm the status live region (aria-live="polite") announces the state change when dragged is toggled programmatically
  3. Navigate to the "Filled" instance; confirm the illustrated message is hidden from the accessibility tree (it has display: none when [filled]) and only the uploaded-content region is announced
  4. Confirm the group label and structure are coherent with VoiceOver (macOS) and NVDA (Windows)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 80fda76

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

• 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-6446

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.

[5t3ph]

Blocking to assess a functional change of possibly adding a filled-content slot.

[5t3ph]

Would you mind creating a ticket to investigate if we'd want to add something akin to React's FileTrigger (embedded in their DropZone demo, no separate docs) to help facilitate more of the upload operation? It's still feeling odd to me that we turn over so much to consumers to have to handle for the logic.

S1 showed a very rudimentary way to open a hidden file input, which we might want to demo at minimum. Could be done in the docs phase.

[5t3ph]

We should clarify from design if we should at all build in a default for this, but design and React have different ones.

Design Figma:

React:

[5t3ph]

Let's go ahead and update this to the linear version shown in the Figma, per Design's guidance in the Slack thread, so we aren't using an unexpected illustration.

<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" viewBox="0 0 96 96"><path d="M12 68.74a2 2 0 0 1 2 2v3.5a1.5 1.5 0 0 0 1.5 1.5H19a2 2 0 1 1 0 4h-3.5a5.5 5.5 0 0 1-5.5-5.5v-3.5a2 2 0 0 1 2-2m22.5 7a2 2 0 1 1 0 4H27a2 2 0 1 1 0-4zm17 0a2 2 0 1 1 0 4H44a2 2 0 1 1 0-4zm17 0a2 2 0 1 1 0 4H61a2 2 0 1 1 0-4zm15.5-7a2 2 0 0 1 2 2v3.5a5.5 5.5 0 0 1-5.5 5.5H77a2 2 0 1 1 0-4h3.5a1.5 1.5 0 0 0 1.5-1.5v-3.5a2 2 0 0 1 2-2m-36.441-53c1.973 0 3.868.78 5.267 2.17l14.987 14.9A7.4 7.4 0 0 1 70 38.063v21.254c0 4.11-3.348 7.423-7.454 7.423H33.454c-4.106 0-7.454-3.313-7.454-7.423V23.163c0-4.11 3.348-7.423 7.454-7.423zM84 55.24a2 2 0 0 1 2 2v7.5a2 2 0 1 1-4 0v-7.5a2 2 0 0 1 2-2m-72-.5a2 2 0 0 1 2 2v7.5a2 2 0 1 1-4 0v-7.5a2 2 0 0 1 2-2m21.454-35c-1.918 0-3.454 1.544-3.454 3.423v36.154c0 1.88 1.536 3.423 3.454 3.423h29.092c1.918 0 3.454-1.544 3.454-3.423V38.063c0-.904-.361-1.773-1.008-2.416l-14.986-14.9a3.47 3.47 0 0 0-2.447-1.007zm13.594 12a2 2 0 0 1 1.996 2.004l-.035 15.781 5.214-4.324a2 2 0 0 1 2.554 3.078l-8.438 7a2 2 0 0 1-1.31.459l-.033.002a2 2 0 0 1-1.54-.729l-8.222-6.722a2 2 0 0 1 2.532-3.098l5.243 4.286.035-15.74a2 2 0 0 1 2.004-1.997M19 40.74a2 2 0 1 1 0 4h-3.5a1.5 1.5 0 0 0-1.5 1.5v3.5a2 2 0 1 1-4 0v-3.5a5.5 5.5 0 0 1 5.5-5.5zm61.5 0a5.5 5.5 0 0 1 5.5 5.5v3.5a2 2 0 1 1-4 0v-3.5a1.5 1.5 0 0 0-1.5-1.5H77a2 2 0 1 1 0-4z"/></svg>

[5t3ph]

This is getting close! A couple minor things besides the Illustrated Message fix we also chatted about.

[5t3ph]

Let's go ahead and update this to the linear version shown in the Figma, per Design's guidance in the Slack thread, so we aren't using an unexpected illustration.

<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" viewBox="0 0 96 96"><path d="M12 68.74a2 2 0 0 1 2 2v3.5a1.5 1.5 0 0 0 1.5 1.5H19a2 2 0 1 1 0 4h-3.5a5.5 5.5 0 0 1-5.5-5.5v-3.5a2 2 0 0 1 2-2m22.5 7a2 2 0 1 1 0 4H27a2 2 0 1 1 0-4zm17 0a2 2 0 1 1 0 4H44a2 2 0 1 1 0-4zm17 0a2 2 0 1 1 0 4H61a2 2 0 1 1 0-4zm15.5-7a2 2 0 0 1 2 2v3.5a5.5 5.5 0 0 1-5.5 5.5H77a2 2 0 1 1 0-4h3.5a1.5 1.5 0 0 0 1.5-1.5v-3.5a2 2 0 0 1 2-2m-36.441-53c1.973 0 3.868.78 5.267 2.17l14.987 14.9A7.4 7.4 0 0 1 70 38.063v21.254c0 4.11-3.348 7.423-7.454 7.423H33.454c-4.106 0-7.454-3.313-7.454-7.423V23.163c0-4.11 3.348-7.423 7.454-7.423zM84 55.24a2 2 0 0 1 2 2v7.5a2 2 0 1 1-4 0v-7.5a2 2 0 0 1 2-2m-72-.5a2 2 0 0 1 2 2v7.5a2 2 0 1 1-4 0v-7.5a2 2 0 0 1 2-2m21.454-35c-1.918 0-3.454 1.544-3.454 3.423v36.154c0 1.88 1.536 3.423 3.454 3.423h29.092c1.918 0 3.454-1.544 3.454-3.423V38.063c0-.904-.361-1.773-1.008-2.416l-14.986-14.9a3.47 3.47 0 0 0-2.447-1.007zm13.594 12a2 2 0 0 1 1.996 2.004l-.035 15.781 5.214-4.324a2 2 0 0 1 2.554 3.078l-8.438 7a2 2 0 0 1-1.31.459l-.033.002a2 2 0 0 1-1.54-.729l-8.222-6.722a2 2 0 0 1 2.532-3.098l5.243 4.286.035-15.74a2 2 0 0 1 2.004-1.997M19 40.74a2 2 0 1 1 0 4h-3.5a1.5 1.5 0 0 0-1.5 1.5v3.5a2 2 0 1 1-4 0v-3.5a5.5 5.5 0 0 1 5.5-5.5zm61.5 0a5.5 5.5 0 0 1 5.5 5.5v3.5a2 2 0 1 1-4 0v-3.5a1.5 1.5 0 0 0-1.5-1.5H77a2 2 0 1 1 0-4z"/></svg>

[5t3ph]

One suggestion for the Illustrated Message update - thanks for adding that in!