chore(progress-bar): create migration plan for progress bar

[miwha-adobe]

docs(progress-bar): add 2nd-gen migration plan (Phase 1)

Description

Adds the Phase 1 migration plan for the <sp-progress-bar> → <swc-progress-bar> 2nd-gen migration at CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-bar/migration-plan.md.

This is a planning deliverable only — no component code is created or changed. The plan documents:

• The full 1st-gen API surface (progress, indeterminate, label, side-label, static-color, size, deprecated over-background).
• The architecture decision that <swc-progress-bar> is the second consumer of the existing LinearProgressMixin (2nd-gen/packages/core/mixins/linear-progress-mixin.ts) and the shared linear-progress-base.css, both of which the Meter migration deliberately pre-built. Both shared artifacts are consumed unchanged (closed to feature additions).
• The breaking and a11y-required changes (B1–B12): tag rename, progress→value, minValue/maxValue, side-label→label-position, removal of the deprecated over-background, --mod-*→--swc-linear-progress-*, role="progressbar" moved off the host onto the shadow wrapper, determinate-vs-indeterminate ARIA rules, and the label-slot + accessibleLabel naming model.
• Additive features inherited from the shared layer (A1–A4): static-color="black", description slot, value-label, formatOptions.
• The two resolved/scoped open questions: Q1 — de-hardcode the meter docs URL in the shared mixin's DEBUG warnings and fix the 1st-gen copy-paste bug that references <sp-progress-circle> in the <sp-progress-bar> warning; Q2 — the indeterminate animation is the only visual not inherited from the Meter-validated surface and will be lifted figma.

The principal API difference from the migrated Meter: progress bar has no variant property (single accent fill).

Motivation and context

Progress bar is the next component in the 2nd-gen migration workstream. Phase 1 produces a reviewed plan before any implementation begins, so breaking changes, naming, and the shared-base strategy can be challenged in review rather than during testing. Because progress bar reuses the linear-progress mixin and shared CSS that Meter already shipped, the plan also confirms those artifacts stay closed to feature additions.

Related issue(s)

• Epic SWC-1769 (Progress bar 2nd-gen migration)
• SWC-1771 (Phase 1: planning)

Screenshots (if appropriate)

N/A — documentation only.

---

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. N/A — documentation-only change.
• I have included a well-written changeset if my change needs to be published. N/A — internal contributor docs, not a published package.
• 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

• Migration plan is internally consistent and technically accurate

  1. Open CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-bar/migration-plan.md
  2. Verify the breaking-change tables (B1–B12) and additive table (A1–A4) match the 1st-gen source and the shipped Meter shared surface
  3. Expect the architecture section to reuse LinearProgressMixin / linear-progress-base.css with no planned changes to those files, and the API to omit a variant property

• Relative links and references resolve

  1. From the plan, follow the links to the accessibility analysis, rendering analysis, sibling Meter plan, 1st-gen source, shared mixin, and shared CSS
  2. Do this for the References section and inline links
  3. Expect every link to resolve to an existing file/anchor

Device review

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

Accessibility testing checklist

Documentation-only change — there is no shipped component or UI to operate in this PR. The plan itself defines the accessibility requirements (role placement, determinate/indeterminate ARIA, naming model) that will be implemented and manually tested in Phases 4–6 of the migration.

• Keyboard (required — document steps below) — N/A for this PR. The plan specifies progress bar is non-focusable (no tabindex, keyboard skips it); keyboard testing will be performed when the component is implemented (Phase 6).

  1. N/A — no interactive component in this PR
  2. —
  3. —

• Screen reader (required — document steps below) — N/A for this PR. The plan specifies the screen-reader contract to verify at implementation time: role="progressbar" on the shadow wrapper; determinate exposes aria-valuemin/max/now/text; indeterminate omits all four; name from the label slot (aria-labelledby) or accessible-label (aria-label).

  1. N/A — no implemented component in this PR
  2. —
  3. —

[changeset-bot]

⚠️ No Changeset found

Latest commit: 532c4e1

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

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 great! ✨

[caseyisonit]

I dont know if this is the place but i feel like we might want to consider a pending or indeterminate component that super simple and comes as a circle or a bar. Progress circle has extremely similar API and i wonder if we can do a comparison and see if there might be a shared class here?

[5t3ph]

Looks good, just one note for the styling phase.

[5t3ph]

In the styling phase, you can inspect React's implementation to grab the values here. Note that they currently do not change anything for prefers-reduced-motion but we will want to account for that (TBD, we can chat in that phase).