docs(menu, action-menu): component analysis by aramos-adobe · Pull Request #5981 · adobe/spectrum-web-components

aramos-adobe · 2026-01-22T05:15:47Z

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 components: Menu, Action menu

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

Screenshots (if appropriate)

N/A - Documentation only

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 review test cases

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

Device review

Did it pass in Desktop?
Did it pass in (emulated) Mobile?
Did it pass in (emulated) iPad?

…tton, In-field button and In-field progress circle (#5738) * chore(docs): barebones analysis for SWC-1218 * chore(docs): address feedback * chore(docs): address feedback

…roadmap (#5729) * docs(checkbox): migration roadmap * docs(fieldgroup): migration roadmap * docs(radio): migration roadmap * docs(switch): migration roadmap * docs(checkbox, field-group): update migration roadmap - gives clarification on invalid checkbox consideration - clarifies some of the implementation gaps for field group

… roadmap (#5775) * docs: add component analysis docs adds migration roadmap and component analysis docs for meter, progress bar, slider, illustrated message and drop zone.

…ard, swatch + swatchgroup, thumbnail (#5740)

…sis (#5788)

changeset-bot · 2026-01-22T05:15:51Z

⚠️ No Changeset found

Latest commit: 0936149

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 · 2026-01-22T05:22:01Z

📚 Branch Preview Links

🔍 First Generation 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-5981

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.

marissahuysentruyt

Oh no! I'm seeing quite a few Cursor hallucinations. Would you double check some things, and maybe re-run the prompt for a few places?

marissahuysentruyt · 2026-01-22T21:15:39Z

migration-roadmap/action-menu.md

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


Can you find the links to all of these and add them please?

marissahuysentruyt · 2026-01-22T21:15:59Z

migration-roadmap/menu.md

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


Can you find the links to these places and add them here?

marissahuysentruyt · 2026-01-22T21:17:05Z

migration-roadmap/menu.md

+<details>
+<summary>Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two)</summary>
+
+```diff


Can you make sure that Cursor runs the diff on the rendered markup, instead of on the template files? A lot of this isn't relevant to the SWC migration.

Yep, I think the <details><summary> sections for Legacy and for Spectrum 2 might be identical? Ideally this section would be a diff of what changed between those two sections so we can easily see how the markup changes.

marissahuysentruyt · 2026-01-22T21:20:00Z

migration-roadmap/action-menu.md

+<details>
+<summary>CSS selectors</summary>
+
+None found for this component.


After the migration, there are 2 action menu selectors. maybe ask cursor to tell you what branches its going to pull this information from before re-running this portion of the prompt.

marissahuysentruyt · 2026-01-22T21:22:00Z

migration-roadmap/action-menu.md

+```
+
+</details>
+


We are missing the diff between CSS branches. If there's no diff, we might be able to mimic the avatar diff section:

I like this pattern better too, but I checked the prompt and we're still telling it to omit the section entirely if there's no diff. I would argue that updating the prompt to be more like this avatar example would be better?

FWIW, Avatar, Badge, Help text, Opacity checkerboard, Swatch group, Swatch, and Thumbnail all use this "No significant structural changes" pattern, so it is pretty common in spite of the fact that the prompt doesn't have it.

It might be worth fiddling around in Cursor to see if we can get it to look at the existing docs then update the prompt based on those patterns, but if we go that route, we definitely should have a human read through the prompt changes and make sure they make sense.

marissahuysentruyt · 2026-01-22T21:27:32Z

migration-roadmap/menu.md

+- `selects` - inherit
+- `selects` - single
+- `selects` - multiple


Do you want to combine these, sort of like the tooltip placement attribute values from the other PR?

I'm also surprised to see that the description of selects from the API page isn't coming through. Could you add it?

marissahuysentruyt · 2026-01-22T21:29:22Z

migration-roadmap/menu.md

+    @sp-menu-submenu-opened=${this.handleDescendentOverlayOpened}
+    @sp-menu-submenu-closed=${this.handleDescendentOverlayClosed}
+    @slotchange=${this.handleSlotchange}


I'm not certain we need the handling called out since they aren't necessary for the DOM.

Yep, we could honestly just leave it as a <slot></slot>, or a slot with a comment is nice too, like in action group, for example:

 <slot></slot>

marissahuysentruyt · 2026-01-22T21:32:40Z

migration-roadmap/menu.md

+    <svg class="spectrum-Menu-itemIcon spectrum-Menu-itemIcon--workflowIcon">...</svg>
+
+    <!-- Label: -->
+    <span class="spectrum-Menu-itemLabel|spectrum-Menu-sectionHeading spectrum-Switch-label? spectrum-Menu-itemLabel--truncate?">


I almost missed this hidden menu heading class. Do you think it should be separated out at all? I think the thing that tripped me up was that it was under the "Label" comment. Maybe the comment could be updated to include "heading" somehow?

I don't think this is a blocker- it could have just been me!

marissahuysentruyt · 2026-01-22T21:33:58Z

migration-roadmap/menu.md

+
+| CSS selector | Attribute or slot | Status |
+|-------------|------------------|--------|
+| `.spectrum-Menu` | N/A (root element) | Implemented |


We may have to update this table once the selectors have been corrected.

marissahuysentruyt · 2026-01-22T21:36:55Z

migration-roadmap/menu.md

+**Main branch approach:**
+- Uses a `iconWithScale()` helper function that maps size to specific icon variants with scale numbers
+- Example: size "s" → "ArrowLeft200", size "m" → "ArrowLeft300", size "l" → "ArrowLeft400"
+- Applied to chevron icons and back button icons
+
+**Spectrum 2 approach:**
+- Simplified icon naming - removes the helper function for most icons
+- Uses direct icon names: "ChevronRight", "Checkmark"
+- For back button icons specifically, uses inline size mapping: "ArrowRight" + size suffix ("100", "400", etc.)
+- The size mapping is more explicit and simplified
+
+**Impact:** This change makes icon usage more consistent and removes the need for a helper function to translate between size values and icon scale numbers. The Spectrum 2 approach is more straightforward and easier to maintain.
+
+**Additional changes:**
+- Removed theme CSS imports (`../themes/spectrum.css` and `../themes/express.css`) in spectrum-two branch
+- The template structure and DOM markup remain identical between branches


Can you update the formatting of this CSS Spectrum 2 changes section to match some of the other components? I was expecting to see some of the new menu stuff (like the thumbnail and external link) to be listed here, but I think since Cursor might have populated this with S1 stuff, it's all missing.

and that would be bad for an SWC migration 😆🤭

rise-erpelding · 2026-01-22T21:55:27Z

migration-roadmap/action-menu.md

+
+### CSS
+
+Action Menu does not have its own CSS component. It is a composite pattern that combines Action Button, Popover, and Menu components.


Action menu got migrated in the spectrum-two branch in October, I think? That migration does add a really minimal CSS file that we'll probably want to mention.

rise-erpelding · 2026-01-23T16:25:23Z

migration-roadmap/action-menu.md

+```
+
+</details>
+


I like this pattern better too, but I checked the prompt and we're still telling it to omit the section entirely if there's no diff. I would argue that updating the prompt to be more like this avatar example would be better?

FWIW, Avatar, Badge, Help text, Opacity checkerboard, Swatch group, Swatch, and Thumbnail all use this "No significant structural changes" pattern, so it is pretty common in spite of the fact that the prompt doesn't have it.

It might be worth fiddling around in Cursor to see if we can get it to look at the existing docs then update the prompt based on those patterns, but if we go that route, we definitely should have a human read through the prompt changes and make sure they make sense.

rise-erpelding · 2026-01-23T17:26:18Z

migration-roadmap/menu.md

+    @sp-menu-submenu-opened=${this.handleDescendentOverlayOpened}
+    @sp-menu-submenu-closed=${this.handleDescendentOverlayClosed}
+    @slotchange=${this.handleSlotchange}


Yep, we could honestly just leave it as a <slot></slot>, or a slot with a comment is nice too, like in action group, for example:

 <slot></slot>

rise-erpelding · 2026-01-23T17:32:15Z

migration-roadmap/menu.md

+    <!-- For icons: -->
+    <svg class="spectrum-Menu-itemIcon spectrum-Menu-itemIcon--workflowIcon">...</svg>


Spectrum 2 also supports thumbnails before the description, we'll want to include that in the markup here too.

rise-erpelding · 2026-01-23T17:32:46Z

migration-roadmap/menu.md

+        </span>
+      </label>
+    </div>
+


We'll also want to include the linkout feature added in S2.

rise-erpelding · 2026-01-23T17:36:42Z

migration-roadmap/menu.md

+							}[size] || "100"),
+```
+
+**Key change**: Icon sizing approach was simplified in Spectrum 2. The `iconWithScale()` helper function was removed from the main branch and replaced with simpler inline logic or direct icon names. The back button icon now uses a more explicit size mapping for the ArrowRight icon.


iconWithScale appears to exist on both main and spectrum-two, not sure where it got this 🤔

rise-erpelding · 2026-01-23T17:39:20Z

migration-roadmap/menu.md

+<details>
+<summary>Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two)</summary>
+
+```diff


Yep, I think the <details><summary> sections for Legacy and for Spectrum 2 might be identical? Ideally this section would be a diff of what changed between those two sections so we can easily see how the markup changes.

rise-erpelding · 2026-01-23T17:50:04Z

migration-roadmap/menu.md

We'll also have to have migration documentation for menu item, menu divider, and menu group... right now the docs sort of hint at some of those, but I think a big thing that would be really helpful to know is that CSS includes all of those in its menu package whereas SWC breaks them up into separate components.

When we tackle menu for 2nd-gen, I'm not sure if we would try to tackle all of its components (MenuItem, MenuGroup, MenuDivider) all at once but it would be helpful to have a separate section or markdown file that compares each of these. It wouldn't be a component-to-component comparison, because CSS doesn't have all of those components, but we could compare the SWC MenuItem with the parts of the Spectrum-CSS package that relate to menu item.

rise-erpelding · 2026-01-23T17:53:41Z

migration-roadmap/menu.md

+- `value` - Value of the selected item(s)
+- `value-separator` - Separator for multiple values (default: ",")
+- `size` (inherited from SizedMixin)
+


We'll want to include attributes and properties from sp-menu-item and other sp-menu components that will map to the CSS selectors that were listed above. I like the idea of putting them in a separate section or even their own file, either one would work. Left a comment with more detail on this above!

…m-web-components into 2nd-gen-component-analysis

…omponent-analysis-docs

marissahuysentruyt and others added 10 commits December 10, 2025 11:30

chore: add cursor prompt

e165f73

docs: add prompt output files for subset of components

c3e3d7a

docs: barebones component analysis docs, prompt updates (#5720)

13922a1

chore(docs): barebones analysis for Field label, Help text, Picker bu…

f0963cb

…tton, In-field button and In-field progress circle (#5738) * chore(docs): barebones analysis for SWC-1218 * chore(docs): address feedback * chore(docs): address feedback

docs: textfield-based component analysis docs (#5741)

b41f6e0

docs(slider,meter,progressbar,dropzone,illustratedmessage): migration…

601f7f9

… roadmap (#5775) * docs: add component analysis docs adds migration roadmap and component analysis docs for meter, progress bar, slider, illustrated message and drop zone.

chore(docs): 2nd gen component analysis for avatar, opacity checkerbo…

a21c7b4

…ard, swatch + swatchgroup, thumbnail (#5740)

docs(button, buttongroup, actionbutton, actiongroup): component analy…

7e7651f

…sis (#5788)

first docs feedback

d817bf0

aramos-adobe self-assigned this Jan 22, 2026

aramos-adobe requested a review from a team as a code owner January 22, 2026 05:15

marissahuysentruyt requested changes Jan 22, 2026

View reviewed changes

rise-erpelding requested changes Jan 23, 2026

View reviewed changes

docs(menu): making changes to menu.md

96e320d

marissahuysentruyt force-pushed the 2nd-gen-component-analysis branch from 7e7651f to 8b8fe5c Compare February 2, 2026 19:55

caseyisonit added Status:Addressing feedback PR owner is addressing review comments and will change label back to "Ready for review" when ready. and removed Status:Ready for review PR ready for review or re-review. labels Feb 3, 2026

aramos-adobe added 3 commits February 5, 2026 14:16

docs(menu): migrating additional components

faffe45

Merge branch '2nd-gen-component-analysis' of github.com:adobe/spectru…

437d23f

…m-web-components into 2nd-gen-component-analysis

Merge branch '2nd-gen-component-analysis' into aramos-adobe/swc1222-c…

0936149

…omponent-analysis-docs

aramos-adobe closed this Feb 10, 2026


		### CSS

		Action Menu does not have its own CSS component. It is a composite pattern that combines Action Button, Popover, and Menu components.

		<!-- For icons: -->
		<svg class="spectrum-Menu-itemIcon spectrum-Menu-itemIcon--workflowIcon">...</svg>

		```

		</details>

		```

		</details>

Conversation

aramos-adobe commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Reviewer's checklist

Manual review test cases

Documentation Quality

Cross-Reference Accuracy

Device review

Uh oh!

changeset-bot bot commented Jan 22, 2026 • 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 Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

Uh oh!

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

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aramos-adobe commented Jan 22, 2026 •

edited

Loading

changeset-bot bot commented Jan 22, 2026 •

edited

Loading

github-actions bot commented Jan 22, 2026 •

edited

Loading