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

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!

migration-roadmap/avatar.md

migration-roadmap/swatch.md

migration-roadmap/swatch-group.md

migration-roadmap/thumbnail.md

migration-roadmap/avatar.md

marissahuysentruyt · 2025-09-25T17:39:28Z

migration-roadmap/avatar.md

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


oh I love how this showcases where the props go!

marissahuysentruyt · 2025-09-25T17:45:09Z

migration-roadmap/avatar.md

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


oh yeah, I think Rise mentioned we could mark the disabled attribute as Implemented.

Nice, I'll update this

marissahuysentruyt · 2025-09-25T17:48:14Z

migration-roadmap/avatar.md

+
+## Summary of changes
+
+### CSS => SWC implementation gaps


oh! There's a follow up ticket for avatar with some newly added default gradient background support. Should we call out that there's more to this component that isn't supported by CSS yet either?

Just thinking out loud- when would that work be done? Separately from the SWC migration to S2? Like a follow up once avatar has migrated?

Oh dang, that's tough. I'm tempted to call it "out of scope" for now since it wasn't in place when we first migrated the component. Do you think we're likely to miss it if we do that though?

I don't think it hurts to include information about variants that we didn't implement in CSS, and I'm not sure what the exact order of implementation would be, but I would guess that we might do a single pass to bring our existing CSS over, then go back and address the other variants later, so it might not be absolutely necessary to include for the "first pass" migration.

We do have a ticket for those additional variants: CSS-1236. If that ends up happening in CSS before we migrate, we should come back and note it in these docs. But if we address it in SWC, I think we'll be ok.

I'm also hoping/assuming that we'll do some kind of design review before shipping anything so that's another fallback for missing variants to be called out!

marissahuysentruyt · 2025-09-25T17:52:56Z

migration-roadmap/opacity-checkerboard.md

+
+```html
+<!-- Used as a utility class in other components -->
+<div class="opacity-checkerboard [variant]">


What would one of the variant options be? Like fill (which I saw in the swatch story)?

Oh yeah, I suppose it doesn't have any variants. I can remove this reference.

marissahuysentruyt · 2025-09-25T20:17:50Z

migration-roadmap/swatch-group.md

+
+### CSS Spectrum 2 changes
+
+No significant structural changes between CSS main and spectrum-two branches. The templates are identical, indicating that the swatch group component structure remains consistent across Spectrum 2 migration. Swatch group includes a setting for single or multiple selection and it might be worth connecting with design to see if there should be any unique styles designed that differentiates single or multi-select swatch groups.


I'm not sure where this information would be most helpful, but could we add a short description of why the border prop for swatch group is getting deprecated for SWC S2?

If I'm remembering correctly, the border used to be applied per-swatch within a swatch group (as in- low-contrast swatches would get the light border, while higher contrast swatches didn't need a border). Design decided that they wanted borders on all swatches for S2, however. The only exception looks like the addSwatch.

I added some verbage to this end, let me know if it sounds okay!

marissahuysentruyt · 2025-09-25T20:25:20Z

migration-roadmap/thumbnail.md

+
+<!-- With background -->
+<div
+    class="spectrum-Thumbnail spectrum-Thumbnail--cover spectrum-Thumbnail-layer is-selected is-disabled is-focused spectrum-Thumbnail--size500"


Is this background example supposed to have the layer class still?

marissahuysentruyt · 2025-09-25T20:26:06Z

migration-roadmap/thumbnail.md

+
+<!-- Default -->
+<div
+    class="spectrum-Thumbnail spectrum-Thumbnail--cover spectrum-Thumbnail-layer is-selected is-disabled is-focused spectrum-Thumbnail--size500"


same here- I assume the layer class needs to be removed.

marissahuysentruyt · 2025-09-25T20:27:03Z

migration-roadmap/thumbnail.md

+    <div
+        class="spectrum-Thumbnail-background"
+        style="background-color: [backgroundColor]"
+    ></div>


And then this gets removed from the Default example markup too, I assume?

marissahuysentruyt · 2025-09-25T20:29:06Z

migration-roadmap/thumbnail.md

+
+**CSS features missing from Web Component:**
+
+- Disabled state support (`.is-disabled`)


I think disabled is supported in SWC! It's not on the API table, though.

I wonder how that happened... it looks like focus and selected are supported as well.

migration-roadmap/avatar.md

rise-erpelding · 2025-09-26T14:04:43Z

migration-roadmap/opacity-checkerboard.md

+
+- [CSS migration](https://github.com/adobe/spectrum-css/pull/3394)
+- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-opacity-checkerboard--docs)
+- [React](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorslider--docs) (not a standalone component, but styles are used by the color slider)


not a standalone component, but styles are used by the color slider

Love this clarification, will be borrowing this for other components if it comes up.

migration-roadmap/avatar.md

migration-roadmap/swatch.md

rise-erpelding · 2025-09-26T14:31:21Z

migration-roadmap/swatch.md

+
+### CSS Spectrum 2 changes
+
+There is a new add swatch functionality in the `spectrum-two` branch and supplemental state and pseudo-element styling selectors in the `spectrum-two` branch which will automatically be applied when consumed by the web component for Spectrum 2.


Just a nit to make the name of the feature stand out more. This seems to align with Adobe's grammar & mechanics guidelines although I do see other examples on the page where they're using quotes or italics.

Suggested change

There is a new add swatch functionality in the `spectrum-two` branch and supplemental state and pseudo-element styling selectors in the `spectrum-two` branch which will automatically be applied when consumed by the web component for Spectrum 2.

There is a new **add swatch** functionality in the `spectrum-two` branch and supplemental state and pseudo-element styling selectors in the `spectrum-two` branch which will automatically be applied when consumed by the web component for Spectrum 2.

Yes, love it!

rise-erpelding · 2025-09-26T14:44:55Z

migration-roadmap/swatch-group.md

+<details>
+<summary>Attributes</summary>
+
+- `border` (string) - Border style: 'light', 'none' **deprecated** (from Swatch component)


Yep, as mentioned with Swatch the borders are more transparent when in the group.

rise-erpelding · 2025-09-26T14:56:22Z

migration-roadmap/thumbnail.md

+
+<!-- With background -->
+<div
+    class="spectrum-Thumbnail spectrum-Thumbnail--cover spectrum-Thumbnail-layer is-selected is-disabled is-focused spectrum-Thumbnail--size500"


rise-erpelding · 2025-09-26T14:58:26Z

migration-roadmap/thumbnail.md

+| `.is-disabled`                      | `disabled` attribute   | Missing from WC |
+| `.is-focused`                       | Focus state            | Missing from WC |
+| `.is-selected`                      | `selected` attribute   | Missing from WC |


It looks like these states do exist in SWC

rise-erpelding · 2025-09-26T14:59:11Z

migration-roadmap/thumbnail.md

+
+**CSS features missing from Web Component:**
+
+- Disabled state support (`.is-disabled`)


I wonder how that happened... it looks like focus and selected are supported as well.

rise-erpelding · 2025-10-03T13:19:04Z

migration-roadmap/avatar.md

+
+**CSS features missing from Web Component:**
+
+- Disabled state support (`.is-disabled`)


Suggested change

- Disabled state support (`.is-disabled`)

rise-erpelding · 2025-10-03T13:32:39Z

migration-roadmap/avatar.md

+
+## Summary of changes
+
+### CSS => SWC implementation gaps


I don't think it hurts to include information about variants that we didn't implement in CSS, and I'm not sure what the exact order of implementation would be, but I would guess that we might do a single pass to bring our existing CSS over, then go back and address the other variants later, so it might not be absolutely necessary to include for the "first pass" migration.

We do have a ticket for those additional variants: CSS-1236. If that ends up happening in CSS before we migrate, we should come back and note it in these docs. But if we address it in SWC, I think we'll be ok.

I'm also hoping/assuming that we'll do some kind of design review before shipping anything so that's another fallback for missing variants to be called out!

rise-erpelding · 2025-10-03T13:40:07Z

migration-roadmap/swatch.md

+    - `.spectrum-Swatch-disabledIcon path:last-child`
+- `.spectrum-Swatch-fill`
+    - `.spectrum-Swatch-fill:before`
+- `.spectrum-Swatch-icon`


Duplicate:

Suggested change

- `.spectrum-Swatch-icon`

rise-erpelding · 2025-10-03T13:41:08Z

migration-roadmap/swatch.md

+- `.spectrum-Swatch-fill`
+    - `.spectrum-Swatch-fill:before`
+- `.spectrum-Swatch-icon`
+- `.spectrum-Swatch-image`


Another duplicate (the suggestion doesn't seem to work for me to suggest removing 2 lines of code, sorry for the duplicate suggestion 😆)

Suggested change

- `.spectrum-Swatch-image`

rise-erpelding · 2025-10-03T13:52:54Z

migration-roadmap/swatch.md

+- `rounding` (string) - Corner rounding: 'none', 'full'
+- `selected` (boolean) - Whether the swatch is selected
+- `shape` (string) - Shape variant: 'rectangle'
+- `size` (string) - Size: 'xs', 's', 'm', 'l'


Is it maybe because it's using a size mixin? I've noticed if the types aren't defined within the file (if they're imported) those don't get picked up either.

rise-erpelding · 2025-10-03T14:45:04Z

migration-roadmap/thumbnail.md

+
+<!-- Default -->
+<div
+    class="spectrum-Thumbnail spectrum-Thumbnail--cover spectrum-Thumbnail-layer is-selected is-disabled is-focused spectrum-Thumbnail--size500"


Suggested change

class="spectrum-Thumbnail spectrum-Thumbnail--cover spectrum-Thumbnail-layer is-selected is-disabled is-focused spectrum-Thumbnail--size500"

class="spectrum-Thumbnail spectrum-Thumbnail--cover is-selected is-disabled is-focused spectrum-Thumbnail--size500"

rise-erpelding · 2025-10-03T14:45:24Z

migration-roadmap/thumbnail.md

+
+<!-- With background -->
+<div
+    class="spectrum-Thumbnail spectrum-Thumbnail--cover spectrum-Thumbnail-layer is-selected is-disabled is-focused spectrum-Thumbnail--size500"


Suggested change

class="spectrum-Thumbnail spectrum-Thumbnail--cover spectrum-Thumbnail-layer is-selected is-disabled is-focused spectrum-Thumbnail--size500"

class="spectrum-Thumbnail spectrum-Thumbnail--cover is-selected is-disabled is-focused spectrum-Thumbnail--size500"

rise-erpelding · 2025-10-03T14:46:52Z

migration-roadmap/thumbnail.md

+    <div
+        class="spectrum-Thumbnail-background"
+        style="background-color: [backgroundColor]"
+    ></div>


As with legacy, the default thumbnail doesn't have this background div

Suggested change

<div

class="spectrum-Thumbnail-background"

style="background-color: [backgroundColor]"

></div>

rise-erpelding · 2025-10-03T14:52:09Z

migration-roadmap/thumbnail.md

+| `.is-disabled`                      | `disabled` attribute   | Missing from WC |
+| `.is-focused`                       | Focus state            | Missing from WC |
+| `.is-selected`                      | `selected` attribute   | Missing from WC |


rise-erpelding · 2025-10-03T14:53:50Z

migration-roadmap/thumbnail.md

+- Disabled state support (`.is-disabled`)
+- Focus state support (`.is-focused`)
+- Selected state support (`.is-selected`)


I think focus, selected, and disabled, are all there in SWC.

Suggested change

- Disabled state support (`.is-disabled`)

- Focus state support (`.is-focused`)

- Selected state support (`.is-selected`)

None found for this component.

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

castastrophe force-pushed the aramos-adobe/swc1221-component-analysis-docs branch 4 times, most recently from 152b6af to c5f8345 Compare September 24, 2025 20:31

marissahuysentruyt reviewed Sep 25, 2025

View reviewed changes

rise-erpelding reviewed Sep 26, 2025

View reviewed changes

marissahuysentruyt assigned castastrophe and unassigned marissahuysentruyt Sep 29, 2025

rise-erpelding force-pushed the 2nd-gen-component-analysis branch from 1c7d103 to ab5ae6a Compare October 1, 2025 21:23

aramos-adobe and others added 2 commits October 2, 2025 13:58

chore(docs): barebones component migration analysis

cb31306

chore: apply code review feedback

0a7e4f9

castastrophe force-pushed the aramos-adobe/swc1221-component-analysis-docs branch from c5f8345 to 088c63c Compare October 2, 2025 17:59

chore: apply code review feedback

ee5fdd5

castastrophe force-pushed the aramos-adobe/swc1221-component-analysis-docs branch from 088c63c to ee5fdd5 Compare October 2, 2025 18:11

castastrophe requested review from rise-erpelding and marissahuysentruyt October 2, 2025 18:12

rise-erpelding reviewed Oct 3, 2025

View reviewed changes


		### CSS Spectrum 2 changes

		No significant structural changes between CSS main and spectrum-two branches. The templates are identical, indicating that the swatch group component structure remains consistent across Spectrum 2 migration. Swatch group includes a setting for single or multiple selection and it might be worth connecting with design to see if there should be any unique styles designed that differentiates single or multi-select swatch groups.


		CSS features missing from Web Component:

		- Disabled state support (`.is-disabled`)


		### CSS Spectrum 2 changes

		There is a new add swatch functionality in the `spectrum-two` branch and supplemental state and pseudo-element styling selectors in the `spectrum-two` branch which will automatically be applied when consumed by the web component for Spectrum 2.

	There is a new add swatch functionality in the `spectrum-two` branch and supplemental state and pseudo-element styling selectors in the `spectrum-two` branch which will automatically be applied when consumed by the web component for Spectrum 2.
	There is a new add swatch functionality in the `spectrum-two` branch and supplemental state and pseudo-element styling selectors in the `spectrum-two` branch which will automatically be applied when consumed by the web component for Spectrum 2.

	class="spectrum-Thumbnail spectrum-Thumbnail--cover spectrum-Thumbnail-layer is-selected is-disabled is-focused spectrum-Thumbnail--size500"
	class="spectrum-Thumbnail spectrum-Thumbnail--cover is-selected is-disabled is-focused spectrum-Thumbnail--size500"

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 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

changeset-bot bot commented Sep 18, 2025 •

edited

Loading

github-actions bot commented Sep 18, 2025 •

edited

Loading