Skip to content

ci, docs: Remove Spectrum CSS dependencies and processing #5472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 26 commits into from
May 21, 2025
Merged

Conversation

caseyisonit
Copy link
Contributor

@caseyisonit caseyisonit commented May 13, 2025

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

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)

@caseyisonit caseyisonit requested a review from a team as a code owner May 13, 2025 18:29
Copy link

changeset-bot bot commented May 13, 2025

⚠️ 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

Copy link
Collaborator

@rise-erpelding rise-erpelding left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

Copy link

Branch preview

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:

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.

Copy link

Tachometer results

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

blunteshwar and others added 10 commits May 16, 2025 15:42
* chore: remove spectrum-config.js files from various packages
* chore; remove spectrum-css dependencies
* chore: remove unused @spectrum-css dependencies from yarn.lock
* Update packages/icons-ui/package.json
* Update packages/icons-ui/package.json

---------

Co-authored-by: Casey Eickhoff <[email protected]>
* chore: add styling guide

* chore: remove spectrum-config and update other docs

* fix: update yarn new-package to not depend on spectrum-css

* chore: update styling guide

* chore: remove formating from plopfile
Co-authored-by: rise-erpelding <[email protected]>
Co-authored-by: rise-erpelding <[email protected]>
* chore: move tasks into scripts [swc-854]

* chore: update custom element manifest scripts to simpify
* chore: remove build-confirm command and fix cem-tools

* chore: adds build confirm command back

---------

Co-authored-by: Casey Eickhoff <[email protected]>
@nikkimk
Copy link
Contributor

nikkimk commented May 19, 2025

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

@nikkimk
Copy link
Contributor

nikkimk commented May 19, 2025

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",

nikkimk

This comment was marked as duplicate.

@caseyisonit
Copy link
Contributor Author

caseyisonit commented May 19, 2025

@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
Copy link
Contributor Author

caseyisonit commented May 19, 2025

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

@caseyisonit
Copy link
Contributor Author

@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 caseyisonit requested a review from nikkimk May 19, 2025 23:00
@caseyisonit
Copy link
Contributor Author

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

Copy link
Contributor

@nikkimk nikkimk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lofty goal totally met! (LGTM)

Copy link
Contributor

@TarunAdobe TarunAdobe left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

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

caseyisonit and others added 3 commits May 21, 2025 08:50
Co-authored-by: Josh Johnson <[email protected]>
Co-authored-by: Josh Johnson <[email protected]>
@caseyisonit caseyisonit merged commit 8643af5 into main May 21, 2025
24 checks passed
@caseyisonit caseyisonit deleted the CSS-Cutoff branch May 21, 2025 15:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

10 participants