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

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

Good catch- some of the components must inherit properties too. Like on the docs site, avatar has TON of properties, but they all sort of sound like link properties.

Yes, it does look like a lot of these are from link, so it might be overkill to include all of them.

It might be nice though to include the ones that are more relevant, like disabled, since it's popping up in the table in the "CSS => SWC mapping" section as "not implemented" and it's called out as an implementation gap in the summary section at the bottom, but I can see the disabled avatar in Storybook

migration-roadmap/avatar.md

migration-roadmap/swatch.md

migration-roadmap/swatch-group.md

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.

marissahuysentruyt · 2025-09-25T17:37:57Z

migration-roadmap/avatar.md

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


Good catch- some of the components must inherit properties too. Like on the docs site, avatar has TON of properties, but they all sort of sound like link properties.

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.

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?

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)?

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.

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.

rise-erpelding · 2025-09-26T13:52:38Z

migration-roadmap/avatar.md

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


Yes, it does look like a lot of these are from link, so it might be overkill to include all of them.

It might be nice though to include the ones that are more relevant, like disabled, since it's popping up in the table in the "CSS => SWC mapping" section as "not implemented" and it's called out as an implementation gap in the summary section at the bottom, but I can see the disabled avatar in Storybook

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.

rise-erpelding · 2025-09-26T14:06:10Z

migration-roadmap/avatar.md


 <details>
-<summary>Modifiers</summary>
+<summary>Modifiers *deprecated*</summary>


Do you think it's time to think about taking the modifiers sections out of this documentation? Or could they potentially have some value in staying?

rise-erpelding · 2025-09-26T14:12:40Z

migration-roadmap/swatch.md

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


But noting that it's not called out as missing in the summary or table like it is for avatar, which is good

rise-erpelding · 2025-09-26T14:13:57Z

migration-roadmap/swatch.md

+    <!-- Disabled icon SVG when disabled -->
+    <!-- Mixed value icon when mixed-value -->


Still an open question, not a blocker though, just a curiosity!

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.

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.

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

chore(docs): barebones component migration analysis

aaf1582

castastrophe force-pushed the aramos-adobe/swc1221-component-analysis-docs branch from 2917769 to aaf1582 Compare September 24, 2025 18:41

chore: apply code review feedback

ed93788

castastrophe force-pushed the aramos-adobe/swc1221-component-analysis-docs branch 2 times, most recently from 31017a0 to 152b6af Compare September 24, 2025 20:27

chore: apply code review feedback

c5f8345

castastrophe force-pushed the aramos-adobe/swc1221-component-analysis-docs branch 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


		### 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`)

		<!-- Disabled icon SVG when disabled -->
		<!-- Mixed value icon when mixed-value -->


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


		<details>
		<summary>Attributes</summary>


		<details>
		<summary>Attributes</summary>


		<details>
		<summary>Attributes</summary>


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

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!

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!

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!

changeset-bot bot commented Sep 18, 2025 •

edited

Loading

github-actions bot commented Sep 18, 2025 •

edited

Loading