chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail #5740

aramos-adobe · 2025-09-18T04:38:33Z

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 barebones components:

Avatar
Opacity checkerboard
Swatch + Swatch group
Thumbnail

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

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

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

changeset-bot · 2025-09-18T04:38:37Z

⚠️ No Changeset found

Latest commit: 2917769

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 · 2025-09-18T04:40:28Z

📚 Branch Preview

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

Deployed to Azure Blob Storage: pr-5740

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 · 2025-09-18T04:43:30Z

Tachometer results

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

rise-erpelding

Left some comments! We'll definitely want to fill in the Resources sections here, plus review some of the callouts that the docs are making for accuracy!

rise-erpelding · 2025-09-19T13:54:49Z

migration-roadmap/avatar.md

+
+<details>
+<summary>Attributes</summary>
+


Is disabled missing from this list? I know it's listed as a gap below, but it looks like you can actually make the avatar disabled:

https://opensource.adobe.com/spectrum-web-components/storybook/index.html?path=/story/avatar--disabled

rise-erpelding · 2025-09-19T13:56:30Z

migration-roadmap/avatar.md

+```html
+<!-- With link -->
+<a id="link" class="link" href="[href]">
+    <img class="image" alt="[label]" src="[src]" />
+</a>
+
+<!-- Without link -->
+<img class="image" alt="[label]" src="[src]" />
+```


Love that both options are included here!

rise-erpelding · 2025-09-19T14:01:03Z

migration-roadmap/avatar.md

+| `.spectrum-Avatar-link`        | `href` attribute     | Implemented     |
+| `.spectrum-Avatar.is-disabled` | `disabled` attribute | Missing from WC |
+| `.spectrum-Avatar.is-focused`  | Focus state          | Missing from WC |
+| `.spectrum-Avatar--size800`    | `size="800"`         | Missing from WC |


Are these all new sizes for S2 or things that existed in S1 that SWC never implemented (implementation gaps)? Can you make a quick note of which one these "Missing from WC" items are in the table as well? For example:

Suggested change

| `.spectrum-Avatar--size800` | `size="800"` | Missing from WC |

| `.spectrum-Avatar--size800` | `size="800"` | Missing from WC (new size for S2) |

rise-erpelding · 2025-09-19T15:35:16Z

migration-roadmap/avatar.md

+- [CSS migration]()
+- [Spectrum 2 preview]()
+- [React]()


Could we track down the links for these and fill them in?

The migration PR is adobe/spectrum-css#3355

rise-erpelding · 2025-09-19T15:46:47Z

migration-roadmap/avatar.md

+| `.spectrum-Avatar-image`       | `src` attribute      | Implemented     |
+| `.spectrum-Avatar-link`        | `href` attribute     | Implemented     |
+| `.spectrum-Avatar.is-disabled` | `disabled` attribute | Missing from WC |
+| `.spectrum-Avatar.is-focused`  | Focus state          | Missing from WC |


I'm not sure this is a gap, because it does look like at least the linked Avatar is focusable? https://opensource.adobe.com/spectrum-web-components/storybook/index.html?path=/story/avatar--linked&globals=system:spectrum-two

rise-erpelding · 2025-09-19T16:24:22Z

migration-roadmap/swatch.md

+
+## Resources
+
+- [CSS migration]()


adobe/spectrum-css#3677

rise-erpelding · 2025-09-19T16:29:47Z

migration-roadmap/swatch.md

+
+### CSS Spectrum 2 changes
+
+No significant structural changes between CSS main and spectrum-two branches. The templates are identical, indicating that the swatch component structure remains consistent across Spectrum 2 migration.


Hmmm, this feels like a Cursor miss, it forgot about the Add Swatch variant, although it is called out above a couple of times.

rise-erpelding · 2025-09-19T16:30:43Z

migration-roadmap/swatch-group.md

+
+## Resources
+
+- [CSS migration]()


Same migration as Swatch, see the comment there for the PR #.

rise-erpelding · 2025-09-19T16:33:57Z

migration-roadmap/swatch-group.md

+**Web Component Features Missing from CSS:**
+
+- Border attribute support
+- Rounding attribute support
+- Selected state management
+- Selection mode (single/multiple)
+- Shape attribute support
+- Size attribute support


These probably aren't that useful for the purpose of migrating, since we handle all of that a different way in CSS.

rise-erpelding · 2025-09-19T18:16:22Z

migration-roadmap/thumbnail.md

+| `.spectrum-Thumbnail.is-disabled`   | `disabled` attribute   | Missing from WC |
+| `.spectrum-Thumbnail.is-focused`    | Focus state            | Missing from WC |
+| `.spectrum-Thumbnail.is-selected`   | `selected` attribute   | Missing from WC |
+| `.spectrum-Thumbnail:before`        | Pseudo-element styling | Missing from WC |
+| `.spectrum-Thumbnail:after`         | Pseudo-element styling | Missing from WC |
+| `.spectrum-Thumbnail-layer:before`  | Pseudo-element styling | Missing from WC |


Let's take another look at these before we label them as potential gaps or new features that SWC needs to add, I know for sure that disabled does appear to exist in SWC, but some of the other states/pseudo-classes might actually be implemented. Might be worth comparing spectrum-css/components/thumbnail/index.css to spectrum-web-components/packages/thumbnail/src/spectrum-thumbnail.css and other SWC CSS files as well.

chore(docs): barebones component migration analysis

2917769

aramos-adobe requested a review from a team as a code owner September 18, 2025 04:38

aramos-adobe changed the title ~~Aramos-adobe/swc1221-component-analysis-docs~~ chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail Sep 18, 2025

aramos-adobe self-assigned this Sep 18, 2025

aramos-adobe requested review from cdransf, rise-erpelding and marissahuysentruyt September 18, 2025 04:40

aramos-adobe added ready-for-review Documentation labels Sep 18, 2025

rise-erpelding requested changes Sep 19, 2025

View reviewed changes

marissahuysentruyt self-assigned this Sep 23, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail #5740

chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail #5740

aramos-adobe commented Sep 18, 2025

Uh oh!

changeset-bot bot commented Sep 18, 2025

Uh oh!

github-actions bot commented Sep 18, 2025

Uh oh!

github-actions bot commented Sep 18, 2025

Uh oh!

rise-erpelding left a comment

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

rise-erpelding Sep 19, 2025

Uh oh!

Uh oh!

	\| `.spectrum-Avatar--size800` \| `size="800"` \| Missing from WC \|
	\| `.spectrum-Avatar--size800` \| `size="800"` \| Missing from WC (new size for S2) \|


		### CSS Spectrum 2 changes

		No significant structural changes between CSS main and spectrum-two branches. The templates are identical, indicating that the swatch component structure remains consistent across Spectrum 2 migration.


		<details>
		<summary>Attributes</summary>

chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail #5740

Are you sure you want to change the base?

chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail #5740

Conversation

aramos-adobe commented Sep 18, 2025

Description

Motivation and context

Related issue(s)

Author's checklist

Reviewer's checklist

Documentation Quality

Cross-Reference Accuracy

Uh oh!

changeset-bot bot commented Sep 18, 2025

⚠️ No Changeset found

Uh oh!

github-actions bot commented Sep 18, 2025

📚 Branch Preview

🔍 Visual Regression Test Results

Uh oh!

github-actions bot commented Sep 18, 2025

Tachometer results

Uh oh!

rise-erpelding left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!