chore(docs): create migration guide for Spectrum CSS to barebones [SWC-1247]

[castastrophe]

Description

Create documentation that guides developers through migrating CSS styles from the spectrum-two branch in the Spectrum CSS repository into the barebones second-generation folder structure. This guide will maintain consistency and proper CSS architecture during the transition to Spectrum Web Components S2.

Motivation and context

Current State:

• Barebones components exist but lack documented migration process from Spectrum CSS
• No formal process for lifting styles and DOM structures from CSS repository to SWC's 2nd Gen
• Migration patterns need to be captured for future component implementations

Related issue(s)

• Related to SWC-1247
• Barebones Rendering & Styling RFC
• Migration roadmap: 2nd-gen-component-analysis branch

Scope and requirements

Components for reference

Using barebones milestone components as examples:

• Badge (primary example - most complete implementation)
• Alert, Button, Divider, Progress Bar, Slider

Author's checklist

• I have identified the specific migration documentation gaps that need to be addressed
• I have reviewed the Barebones Rendering & Styling RFC for baseline expectations
• I have analyzed current barebones component implementations for migration patterns
• I have outlined clear acceptance criteria focused on migration process documentation
• I have specified file locations and source materials for reference

Reviewer's checklist

• Includes a Github Issue with appropriate flag or Jira ticket number without a link
• Migration process documentation is comprehensive and actionable
• Examples reference existing barebones components appropriately
• Documentation addresses differences from RFC expectations
• File locations and technical specifications are clearly defined

Manual review test cases

• Verify migration process using existing barebones components

  1. Follow documented migration process with Badge component as example
  2. Compare results with existing implementation
  3. Expect consistent CSS architecture and styling patterns

• Validate documentation completeness

  1. Review migration notes against Barebones Rendering & Styling RFC
  2. Check for coverage of edge cases and architectural decisions
  3. Expect comprehensive reference guide for future migrations

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4837c01

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

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.

[castastrophe]

Went ahead and pulled this over from Spectrum CSS since it's a nice easy drop-in.

[github-actions]

Tachometer results

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

[rise-erpelding]

Were you able to run Storybook locally and see these mdx pages? I'm getting an error, not sure if it's me or if we'd need more to the Storybook setup, it seems to be the <Title> tag that it can't tolerate.

[rise-erpelding]

This is all useful and well-written!

The only thing I had in my notes that I didn't see mentioned was that in 2nd gen, components have a new naming convention (<swc-badge> instead of <sp-badge>), would that be useful to call out in here?