docs(slider,meter,progressbar,dropzone,illustratedmessage): migration roadmap

[marissahuysentruyt]

Description

Creates AI-generated migration documentation to analyze component differences to guide SWC migration to S2, with human vetting. The documentation serves as a bridge between the migrated Spectrum 2 CSS work and the corresponding web components, in order to help engineers understand what needs to be implemented, updated, or aligned between the two systems to guide the development of 2nd generation web components.

This batch is for the components: Meter, Progress bar, Slider, Illustrated message, Drop zone.

Motivation and context

• Clear development roadmap: Provides comprehensive feature gap analysis for building 2nd generation web components
• Implementation requirements: Identifies all features and capabilities that need to be implemented to match Spectrum 2 CSS and design specs
• Breaking change transparency: Establishes implementation requirements and design changes that may lead to breaking changes and/or API changes for the next major version
• Adoption planning: Enables developers and consuming teams to plan for 2nd gen web component adoption and understand migration effort required

Related issue(s)

SWC-1219

Screenshots (if appropriate)

---

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed at 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

Documentation Quality

• All files follow template structure with proper collapsible sections
• CSS => SWC mapping tables use correct status values
• Summary sections are concise and actionable
• No broken markdown syntax

Cross-Reference Accuracy

• CSS selectors match actual metadata.json files
• SWC attributes match actual TypeScript source files
• DOM structure comparisons match template files
• Implementation gaps are complete and accurate

Device review

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 710afb8

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

• Documentation Site
• Storybook

🔍 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-5775

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.

[github-actions]

Tachometer results

Currently, no packages are changed by this PR...

[cdransf]

One minor question, but this looks awesome! ✨

[rise-erpelding]

Dropping comments for the first 4 components, will do slider separately in a little bit!

[rise-erpelding]

Adding a color to the track seems to be supported in CSS (Legacy & S2) but since I think it's done through inline styles, I'm not sure it really counts as an implementation gap.

[marissahuysentruyt]

Do you mean this control CSS has, where we can add a custom slider track color?

I think I agree that it's not really an implementation gap- as long as we have the correct CSS cascade, consumers should be able to set the track color similarly, right? However, when I try this in SWC storybook, with style="--spectrum-slider-track-color: linear-gradient(red, blue);", only part of the track fill (and actually the unfilled track) gets the custom color.

Think I should just mention at so it's on our radar, to verify the right behavior when we migrate? That's where I'm leaning now.

[rise-erpelding]

However, when I try this in SWC storybook, with style=“--spectrum-slider-track-color: linear-gradient(red, blue);“, only part of the track fill (and actually the unfilled track) gets the custom color.

Ahhh. I thought that was the intended behavior but I think it may not be. It looks like the track doesn't need to be filled in S1, but the way we did the S2 migration, it looks like that's not an option. The designs portray a fill most of the time, but the offset variant does show some unfilled sliders.

The Storybook control, I think, has been setting the color on the custom property for the unfilled part of the track since S1, but since we didn't always fill the track it wasn't as noticeable. The gradient example on the S1 docs page is unfilled.

Since it is doable but does get more complicated to do custom track colors if the track should always be filled, that'd be a good thing to clarify with design one way or the other, so yeah, I think it would be spot-on to mention it so we can verify it when we're migrating.

[rise-erpelding]

We're missing the precise (handle) variant, it's new for S2! On the table and in the summary.

[rise-erpelding]

Looks good, I think we can slide these in! 🥁