ci, docs: Remove Spectrum CSS dependencies and processing

[caseyisonit]

Style Management in Spectrum Web Components

This PR documents the guidance for maintaining styles in SWC and removes external style dependencies.

Stylesheet Organization

• spectrum-[component].css: Base stylesheet from spectrum-css
• [component]-overrides.css: Overrides stylesheet from spectrum-css
• [component].css: SWC-specific override stylesheet (loaded last)

Build Process Changes

• spectrum-*.css and *-overrides.css files are preserved during builds
• Token assets in styles/themes folders remain unchanged by builds
• Replaced yarn lint:version with yarn constraints for package version alignment
• Moved task scripts to the scripts folder for better maintenance

Removed Items

• All spectrum-config.js files from component packages
• @spectrum-css dependencies from component package.json files
• Unused scripts
• External spectrum-css references (documentation updates to follow in SWC-811)

Motivation and context

This PR establishes a self-contained styling system for Spectrum Web Components by eliminating external style dependencies and providing comprehensive documentation. Previously, our reliance on @spectrum-css created maintenance overhead, version compatibility issues, and complicated the developer experience. By internalizing all style assets and clarifying the purpose of each stylesheet type, we're simplifying the development workflow and ensuring long-term maintainability.

This change is required to provide clear and thorough styling guidance for developers working with SWC components. It addresses the confusion around the usage of multiple stylesheets and ensures that anyone can understand how to update themes and style new components effectively.

The migration of task scripts and introduction of the yarn constraints command further standardize our development processes, making the codebase more accessible to contributors and reducing the likelihood of inconsistencies across components.

Related issue(s)

• fixes [JIRA-808]
• fixes [SWC-809]
• fixes [SWC-810]
• fixes [SWC-811]
• fixes [SWC-854]
• fixes [SWC-873]

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 Testing Steps

Documentation Verification

• Verify that the following docs don't reference the spectrum-css package:
  • Generating Components
  • Developing a Component
  • Readme
  • Review the new Styling Guide and verify it effectively explains how to style components without spectrum-css dependency

Package Generation Testing

• Verify yarn new-package works correctly:
  • Pull this branch
  • Run yarn && yarn build
  • Run yarn new-package
  • Confirm newly generated package has all files mentioned in the Generating Components guide
  • Verify the new package doesn't depend on spectrum-css

Dependency Removal Verification

Verify all instances are removed by checking these search queries:

• Search for "spectrum-config" (excluding .git, node_modules, .wireit, .html, CHANGELOG.md, changelog-content.md, yarn.lock, .changeset)
• Search for "@spectrum-css" (with same exclusions)
  NOTE: Spectrum-CSS will still remain a dependency for all icon-related packages. Please disregard that in the final review.

Build and Rendering Testing

• Run yarn build and verify no regressions
• Run yarn start and check for rendering issues in Storybook
• Check that CI shows no visual changes or regressions

Theme and Style Testing

• Navigate to different components in Storybook
• Toggle between light/dark modes
• Switch between spectrum themes (S1, Express, Spectrum 2)
• Verify visual appearance matches expected theme

Style Preservation Verification

• Examine built files for components
• Confirm spectrum-[component].css and [component]-overrides.css files exist and are not modified
• Verify theme token files remain intact

Constraints Command Testing

• Run yarn constraints to verify it reports no issues
• Test by updating packages with different dependencies:
  • Expect yarn constraints to report the mismatch
  • Expect yarn constraints --fix to correct the mismatch by updating to the most recent version

Live Update Testing

• Verify Storybook live updates when TypeScript and Primary CSS stylesheet assets are changed
  Note: The storybook hot refresh issue with child stylesheets is a known issue that exists today in both SWC and SP-CSS. For the sake of this PR we will accept that behavior since it's currently present. To test that the changes carry through, add a white space to the primary stylesheet and save to get Storybook to refresh.

Command Testing

• Can you build?
• Can you build react?
• Can you build docs?
• Can you build storybook?
• Can you run docs preview?
• Can you run storybook?
• Can you run tests locally?
• Can you publish a changeset snapshot? (DO NOT COMMIT THIS, just verify on NPM)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3fa3ade

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

[rise-erpelding]

Leaving some comments after reviewing documentation in this PR.

I didn't check #5419 and it's very possible that some of what's mentioned below is covered there:

After checking, I didn't see any remaining spectrum-config.js but I did see a few lingering references to spectrum-config.js, for instance we have spectrum-config.js.hbs still, and spectrum-config.js is still mentioned in the .gitignore, package.json, and it looks like in a few tasks (build-component-inventory.js, process-spectrum-js), those might be opportunities for more cleanup.

There were also a few references to spectrum-css that seemed stale but might also be in the other PR:

• Could we clean up any of the files listed in the "process-spectrum" build step?
• There are also a few scripts in package.json starting with update:spectrum-css, wondering if there's any cleanup opportunity there
• @spectrum-css also mentioned in renovate.json, not sure if we're ready to take that out now or want to do that later.

I'm coming to this without a complete understanding of how things work in SWC, so it's possible that some of these items are correct and/or still necessary, but sharing my observations either way!

[github-actions]

Branch preview

• Documentation Site
• Storybook

Review the following VRT differences

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

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

[nikkimk]

Main README does not match the anatomy of Generating Components guide.

[nikkimk]

Search for "spectrum-config" (excluding .git, node_modules, .wireit, .html, CHANGELOG.md, changelog-content.md, yarn.lock, .changeset)

In packages/search/src/search.css, lines 24-27:

/**
 * Hardcoded values for the multiple search field sizes.
 * Feel free to remove this if you find a better way to handle this on the spectrum-config.
 **/

In README.md, lines 181-187:

- packages
   - new-component-name
       - src
           - index.ts
           - new-component-name.css
           - new-component-name.ts
           - spectrum-config.js

In package.json, lines 250-251:

                "!**/spectrum-config.js",
                "!**/spectrum-config.v1.js",

[caseyisonit]

@castastrophe can i ask for you to take a look at the script gather-spectrum-urls in the documentation project? I don't believe we need this but want your confirmation first :)

Edit: I added a @todo to that file. I presently doesn't do anything or affect anything as its been disabled for some time but feels out of scope for this initiative since its existed in this state prior to cutoff.

[caseyisonit]

@nikkimk Icons will still rely on Spectrum CSS so those observations are expected, I've updated the description.

[caseyisonit]

@castastrophe can i also get your help on the CSS hot reload issue @nikkimk called out tomorrow? I can look deeper in the morning but thought you might know whats up

[caseyisonit]

The storybook hot refresh issue with child stylesheets is a known issue that exists today in both SWC and SP-CSS. I can file a spike ticket to investigate how we might get this working but its an issue with storybook and web components playing nicely. For the sake of this PR we will accept that behavior since its currently present. I will update the tests and description with this context too.

CC @nikkimk @TarunAdobe

[nikkimk]

Lofty goal totally met! (LGTM)

[TarunAdobe]

This pull request is not just acceptable...
pause
It's a shining beacon of engineering brilliance, deserving of song, dance and immediate merge. (LGTM)

[rubencarvalho]

When searching for @spectrum-css I still see a result in renovate.json, could we check if it is still necessary?