feat(action-menu): S2 migration [CSS-1160] by castastrophe · Pull Request #4085 · adobe/spectrum-css

castastrophe · 2025-07-29T20:52:10Z

Description

This PR:

Adds a new @spectrum-css/actionmenu component that composes ActionButton, Popover, and Menu to present action lists from a trigger.
Updates @spectrum-css/actionbutton and @spectrum-css/actiongroup to treat selection via .is-selected as well as :where([aria-pressed="true"], [aria-expanded="true"]) to cover more accessibility use-cases while keeping selector specificity low.
Refines @spectrum-css/menu to align with Spectrum 2 specifications and accessibility improvements.

Design references:

Figma S2 token specs: link

Includes a changeset with the following bumps:

@spectrum-css/actionmenu: major (new component)
@spectrum-css/actionbutton: minor (selection semantics with ARIA via :where)
@spectrum-css/menu: patch (S2 refinements, accessibility)
@spectrum-css/actiongroup: patch (selection semantics alignment)

How and where has this been tested?

Storybook locally:
- Verified Action menu stories (default, long-press, placements).
- Verified Menu stories for focus indicators, CJK line-height, external link/drill-in icons, thumbnails, and forced-colors behavior.
- Verified Action button and Action group selected visuals using .is-selected, [aria-pressed="true"], and [aria-expanded="true"].
Forced Colors (Windows High Contrast) visual pass in Storybook.
Chromatic/VRT pending reviewer confirmation.

Validation steps

Open Storybook for Action menu:
- Toggle isOpen and confirm popover/menu spacing and placement reflect updates.
- Enable “Long press” and confirm press vs long-press behavior in docs.
Open Storybook for Action button:
- Toggle .is-selected, set aria-pressed="true", and aria-expanded="true"; confirm identical visuals due to :where(...).
Open Storybook for Action group:
- In compact group, confirm hover/selected/focus ring layering and selection visuals via .is-selected and ARIA attributes.
Open Storybook for Menu:
- Confirm external-link and drill‑in icon sizing; thumbnail sizing/alignment.
- Confirm forced-colors readability.

Screenshots

Add Storybook screenshots for:
- Action menu default and long-press
- Action button selected (class vs ARIA)
- Menu focus and forced-colors states

To-do list

I have read the contribution guidelines.
I have updated relevant Storybook stories and templates.
I have tested these changes in Windows High Contrast mode.
If my change impacts other components, I have tested to make sure they don't break.
If my change impacts documentation, I have updated the documentation accordingly.
I have included a well-written changeset if my change needs to be published.

Notes for reviewers

No class name changes; selection semantics expanded via :where([aria-pressed],[aria-expanded]) to avoid specificity issues and broaden accessibility support.
Menu refinements include focus margin reservation, CJK line-height variables, transparent-at-rest backgrounds per S2, and forced-colors improvements.

References

Changesets documentation: https://github.com/changesets/changesets
Figma S2 token specs: https://www.figma.com/design/eoZHKJH9a3LJkHYCGt60Vb/S2-Token-specs?node-id=19758-3424

github-actions · 2025-07-29T21:07:32Z

📚 Branch preview

PR #4085 has been deployed to Azure Blob Storage: https://spectrumcss.z13.web.core.windows.net/pr-4085/index.html.

github-actions · 2025-07-29T21:08:40Z

File metrics

Summary

Total size: 1.43 MB^*
Total change (Δ): 🔴 ⬆ 0.83 KB (0.06%)

Table reports on changes to a package's main file. Other changes can be found in the collapsed Details section below.

Package	Size	Minified	Gzipped	Δ
actionbutton	23.60 KB	22.52 KB	2.99 KB	🟢 ⬇ 0.06 KB
actiongroup	4.85 KB	4.60 KB	0.95 KB	🔴 ⬆ 0.06 KB
actionmenu	0.84 KB	🆕 0.83 KB	🆕 0.48 KB	🆕 0.84 KB
menu	47.47 KB	45.21 KB	5.00 KB	🟢 ⬇ 0.45 KB
popover	16.55 KB	15.95 KB	2.03 KB	🔴 ⬆ 0.13 KB

File change details

actionbutton

Filename	Head	Minified	Gzipped	Compared to base
index.css	23.60 KB	22.52 KB	2.99 KB	🟢 ⬇ 0.06 KB
metadata.json	10.41 KB	-	-	🔴 ⬆ 0.22 KB

actiongroup

Filename	Head	Minified	Gzipped	Compared to base
index.css	4.85 KB	4.60 KB	0.95 KB	🔴 ⬆ 0.06 KB
metadata.json	2.45 KB	-	-	🔴 ⬆ 0.06 KB

actionmenu

Filename	Head	Minified	Gzipped	Compared to base
index.css	0.84 KB	🆕 0.83 KB	🆕 0.48 KB	🆕 0.84 KB
metadata.json	0.31 KB	-	-	🆕 0.31 KB

popover

Filename	Head	Minified	Gzipped	Compared to base
index.css	16.55 KB	15.95 KB	2.03 KB	🔴 ⬆ 0.13 KB
metadata.json	7.30 KB	-	-	-

* Size is the sum of all main files for packages in the library.
* An ASCII character in UTF-8 is 8 bits or 1 byte.

changeset-bot · 2025-07-30T20:23:58Z

🦋 Changeset detected

Latest commit: 1f94719

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@spectrum-css/actionmenu	Major
@spectrum-css/actionbutton	Minor
@spectrum-css/menu	Patch
@spectrum-css/actiongroup	Patch
@spectrum-css/bundle	Patch
@spectrum-css/preview	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

components/menu/index.css

components/accordion/index.css

components/coachmark/stories/template.js

components/combobox/stories/combobox.stories.js

components/icon/stories/template.js

castastrophe · 2025-09-02T16:55:47Z

components/menu/stories/menu.stories.js

 		labelledby: { table: { disable: true } },
 		items: { table: { disable: true } },
 		role: { table: { disable: true } },
-		subrole: { table: { disable: true } },


Subrole ended up being easier to intuit from the role instead of passing it through from the parent.

castastrophe · 2025-09-02T16:58:15Z

components/menu/stories/menu.test.js

-			)}
-		</ul>
-	`,
+	Template: ({


Letting the template handle this logic because it's a bit duplicative to redefine it here and could lead to mismatches.

castastrophe · 2025-09-02T16:58:36Z

components/menu/stories/menu.test.js

 			testHeading: "No selection, with thumbnails",
 			description: undefined,
-			thumbnailUrl: "thumbnail.png"
+			hasThumbnail: true,


Since thumbnail.png is the default, just the hasThumbnail is sufficient.

castastrophe · 2025-09-02T16:59:21Z

components/menu/stories/template.js

 	isCollapsible = false,
 	label,
 	rootClass,
+	role,


Labels can have roles too! 🥳

castastrophe · 2025-09-02T16:59:48Z

components/menu/stories/template.js

+		return html`
+			<span
+				role=${ifDefined(role)}
+				id=${ifDefined(id)}


Need the id and role for switch labels.

components/menu/stories/template.js

castastrophe · 2025-09-10T14:20:00Z

components/actionbutton/dist/metadata.json

    "a.spectrum-ActionButton"
  ],
  "modifiers": [
-    "--mod-actionbutton-animation-duration",


Since this is for S2 and we've agreed to remove modifiers, I removed the mods on any lines I needed to update for this change anyway.

castastrophe · 2025-09-19T17:16:43Z

components/actionbutton/index.css

 }

-/* Focus indicator */
-.spectrum-ActionButton {


Just me tidying up a bit by combining these styles in with the initial definition for .spectrum-ActionButton

components/menu/index.css

components/actionmenu/stories/template.js

components/actionmenu/index.css

components/actionmenu/stories/actionmenu.stories.js

rise-erpelding · 2025-09-24T20:57:52Z

components/actionmenu/stories/actionmenu.stories.js

+ * By default, the menu is opened by pressing the trigger element or activating it via the <kbd>Space</kbd> or <kbd>Enter</kbd> keys. However, there may be cases where the trigger should perform a separate action on press such as selection, and should only display the menu when long pressed. For this use-case, the menu will only be opened when pressing and holding the trigger or by using the <kbd>Option</kbd> (Alt on Windows) + <kbd>Down arrow</kbd>/<kbd>Up arrow</kbd> keys while focusing the trigger.
+ *
+ * This example illustrates the expected visuals and states of the action menu for a trigger with both long press and short press behaviors.
+ */


😍 love this description!

I don't see the long press working here (I can't access the menu for long press), but I don't think we expect it to, is that correct?

Yeah I took a first pass at making the long-press functional and then thought, this feels a little out-of-scope. Do you think it's worth making it work or should I just note that it doesn't work in CSS but does in SWC?

@castastrophe I like your note that the longpress isn't functional in our docs. We could even link to an example or any longPress documentation we have in SWC.

rise-erpelding · 2025-09-25T13:42:56Z

components/coachmark/stories/template.js

I noticed what I thought was maybe a regression for the Media Options story on the Coachmark docs page:

The container has a height being set on it in the customStyles, wondering if removing that would help?

I couldn't figure out what would have introduced it here though, and I assumed it was a regression from something in this branch because I don't see it in the spectrum-two branch preview.

But I do see the same issue when I run spectrum-two locally so I'm wondering if it's something from #4174 maybe, since it looks like that's where the need for some of those explicit dimensions on popover was eliminated?

As a side note, I also have been noticing some weirdness here, but it's inconsistent so I'm not sure what we should do about it. Sometimes when I open the coachmark component story (on local or preview) the height or sometimes width of the component increases infinitely. It doesn't happen every time, but I'm thinking it's triggered if I open the Coachmark Default story after the Action menu story (I was able to replicate in Firefox, Chrome, and Safari).

It also happens in popover, also if I click into the Popover story after Action menu:

Okay, Steph saw some of that too until she'd done a hard refresh. I wonder if it's an inconsistent bug.

Try this and see if you can replicate it, this is what I'm finding that breaks it (regardless of browser):

Open the Action menu component in Storybook (Docs page or Default story, it doesn't matter, as long as the popover is open, this won't happen if the action menu popover stays closed)

Open either the Coach mark component or the Popover component in Storybook (Docs page or Default story)

Expect to see either the height or width of the popover there expand infinitely until you refresh

I think there's something about Action menu, because I can go between Coach mark and Popover just fine.

Another thing I noticed is that if I start on the Popover with position bottom, then go to Action menu where bottom isn't a valid option (there's only bottom-start and bottom-end), then go back to Popover, the popover ends up in a completely different position. Unsure if that's related or not, but something I noticed.

Unless you've got an idea on how to address it, I'm cool with a follow-up ticket.

I think I've finally got this resolved, would you mind validating on your system as well to be sure? Thank you!

I am still seeing the issue when navigating from an open action menu to something like popover or coachmark without refreshing, both locally and in the PR preview 😕

In the end, I've opted to demo the coach mark with just the action button but not the full action menu. I think the issues around rendering the menu as interactive aren't necessarily worth fixing in CSS at this time just for the purposes of the demo (plus I recall we were deprecating the use of action menu inside the coach mark header).

I'm seeing this as well — do we need to increase the height for that Coachmark example? ✨

components/menu/index.css

components/actionmenu/index.css

5t3ph

Not sure if you consider this in-scope but you called it out for testing - maybe for the compact action group the focus radius should be reduced?

components/actionbutton/index.css

components/actionmenu/stories/actionmenu.stories.js

castastrophe · 2025-09-30T13:21:48Z

Not sure if you consider this in-scope but you called it out for testing - maybe for the compact action group the focus radius should be reduced?

@5t3ph I opened an issue for this and will get the question asked in the design channel! #4246

rise-erpelding

I left more details on some of the popover issues I've been noticing, I'd love to hear your thoughts! I'm cool with these being a follow-up ticket if they can't be solved here.

Otherwise, just some minor adjustments needed, I think!

rise-erpelding · 2025-09-30T20:49:01Z

components/coachmark/stories/template.js

Try this and see if you can replicate it, this is what I'm finding that breaks it (regardless of browser):

Open the Action menu component in Storybook (Docs page or Default story, it doesn't matter, as long as the popover is open, this won't happen if the action menu popover stays closed)

Open either the Coach mark component or the Popover component in Storybook (Docs page or Default story)

Expect to see either the height or width of the popover there expand infinitely until you refresh

I think there's something about Action menu, because I can go between Coach mark and Popover just fine.

Another thing I noticed is that if I start on the Popover with position bottom, then go to Action menu where bottom isn't a valid option (there's only bottom-start and bottom-end), then go back to Popover, the popover ends up in a completely different position. Unsure if that's related or not, but something I noticed.

Unless you've got an idea on how to address it, I'm cool with a follow-up ticket.

components/coachmark/stories/template.js

components/actionbutton/index.css

components/actionmenu/stories/actionmenu.stories.js

components/popover/stories/template.js

components/actionmenu/index.css

.changeset/brave-bikes-teach.md

rise-erpelding

I’m still seeing some issues with Action Menu/Popover. I’ve documented most inline and tested across multiple browsers, so hopefully they’re reproducible on your end.

The CSS looks solid overall, though! I wonder if simplifying some of the JS implementation could help stabilize things so we can ship this.

components/popover/stories/template.js

components/actionbutton/stories/template.js

rise-erpelding · 2025-10-08T15:40:51Z

components/coachmark/stories/template.js

I am still seeing the issue when navigating from an open action menu to something like popover or coachmark without refreshing, both locally and in the PR preview 😕

components/popover/stories/template.js

rise-erpelding

I looked at this quickly and noted that the popover issues from before are resolved! 🎉 Really, really nice work!

I did check out Coachmark after I checked out Action menu and Popover, and I'm seeing a similar issue there, but only after switching on "has action menu":

It's also visible from the docs page.

components/popover/index.css

components/actionmenu/stories/actionmenu.stories.js

cdransf

This looks awesome! Just have a few minor questions. ✨

components/actionmenu/index.css

components/actionbutton/stories/actionbutton.stories.js

cdransf · 2025-10-16T19:57:42Z

components/coachmark/stories/template.js

I'm seeing this as well — do we need to increase the height for that Coachmark example? ✨

components/menu/stories/template.js

marissahuysentruyt

I wanted to leave the comments I had so far! I need to go through the menu and popover changes a little more thoroughly tomorrow!

marissahuysentruyt · 2025-10-16T18:51:37Z

components/actionmenu/stories/actionmenu.stories.js

+	},
+	menuArgs: {
+		customStyles: {
+			"--mod-menu-inline-size": "max-content",


You may have already left a comment somewhere about this, but instead of using the mod here, is it possible to use a --spectrum custom property? If we're going to remove mods, would it make sense to not introduce another place where one is being used?

There's a couple more menu mods in the PlaceholderIcons args as well.

I think removing the mods in some of these more complex components are going to be a bigger project and I didn't want to expand the scope of action menu by addressing that quite yet.

.changeset/brave-bikes-teach.md

components/actionbutton/index.css

components/actionbutton/stories/actionbutton.stories.js

components/actionbutton/stories/template.js

components/actionmenu/stories/actionmenu.stories.js

components/actionmenu/stories/template.js

marissahuysentruyt

I was too slow reviewing, but didn't want my comments to be lost!

marissahuysentruyt · 2025-10-17T16:50:03Z

components/actionbutton/stories/actionbutton.test.js

 			${Template({
 				...args,
 				hasPopup: "true",
+				hasLongPress: true,


Do we need an isOpen arg in any of the tests? Not sure if it's valuable, especially if other args are already covering the style changes.

marissahuysentruyt · 2025-10-17T17:09:09Z

components/actionmenu/stories/actionmenu.stories.js

 		},
-		items: { table: { disable: true } },
+		menuArgs: { table: { disable: true } },
+		triggerArgs: { table: { disable: true } },


I go back and forth on the removal of the iconName control from the table. We have a story that demonstrates that users have the ability to change the icon, but then removed the control so users can't experiment, so I'm split.

Anyways, I don't think it's blocking this PR from merging, but I did want to share some thoughts.

marissahuysentruyt · 2025-10-17T17:12:16Z

components/actionmenu/stories/actionmenu.stories.js

+	triggerArgs: {
+		iconName: "More",
+	},


I don't think this is necessary since we use this exact More icon in the default args.

marissahuysentruyt · 2025-10-17T17:36:34Z

components/coachmark/stories/template.js

@@ -1,4 +1,4 @@
-import { Template as ActionMenu } from "@spectrum-css/actionmenu/stories/template.js";
+import { Template as ActionButton } from "@spectrum-css/actionbutton/stories/template.js";


Does changing this from action menu to just an action button imply anything for SWC? I only ask because the Figma specs for coachmark do specify coachmark being composed with a menu. I don't think it does, but this markup change will be noted in the component analysis, so we'll just have to be sure that we review those docs and clarify that the SWC component as is should still use an action menu.

I also could be thinking too hard about it all.

Yeah, I just removed the full implementation here for demonstration purposes but it doesn't change the end-result for SWC.

castastrophe changed the title ~~feat(action-menu): S2 migration~~ feat(action-menu): S2 migration [CSS-1160] Jul 29, 2025

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch from 2729f84 to 779e411 Compare July 30, 2025 20:23

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch 3 times, most recently from 635f709 to 242929c Compare August 1, 2025 20:06

castastrophe marked this pull request as ready for review August 1, 2025 20:06

castastrophe self-assigned this Aug 1, 2025

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch 2 times, most recently from 4baa099 to eb8cde2 Compare August 4, 2025 15:23

castastrophe commented Aug 4, 2025

View reviewed changes

components/menu/index.css Outdated Show resolved Hide resolved

castastrophe added size-2 S ~6-18hrs; not hard or time consuming, one or two work days to complete. wip This is a work in progress, don't judge. run_vrt For use on PRs looking to kick off VRT S2 Spectrum 2 labels Aug 4, 2025

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch 4 times, most recently from 313ee43 to 3babcfa Compare August 6, 2025 23:43

rise-erpelding reviewed Aug 7, 2025

View reviewed changes

components/accordion/index.css Outdated Show resolved Hide resolved

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch 2 times, most recently from 4d618da to f3fa4d4 Compare August 7, 2025 16:14

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch 3 times, most recently from f2ef53c to 409436c Compare August 18, 2025 16:08

adobe deleted a comment from github-actions bot Aug 18, 2025

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch 2 times, most recently from dbd613f to 00038a9 Compare August 18, 2025 17:12

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch 9 times, most recently from 9ac107e to 40b49ff Compare August 29, 2025 14:06

castastrophe commented Sep 2, 2025

View reviewed changes

castastrophe commented Sep 10, 2025

View reviewed changes

castastrophe commented Sep 19, 2025

View reviewed changes

components/menu/index.css Show resolved Hide resolved

rise-erpelding reviewed Sep 25, 2025

View reviewed changes

5t3ph reviewed Sep 25, 2025

View reviewed changes

components/actionbutton/index.css Show resolved Hide resolved

components/actionmenu/stories/actionmenu.stories.js Outdated Show resolved Hide resolved

castastrophe mentioned this pull request Sep 30, 2025

[Design Q] Should the compact action group reduce the focus radius size? #4246

Open

rise-erpelding requested changes Sep 30, 2025

View reviewed changes

rise-erpelding previously requested changes Oct 8, 2025

View reviewed changes

rise-erpelding reviewed Oct 13, 2025

View reviewed changes

castastrophe commented Oct 15, 2025

View reviewed changes

components/popover/index.css Outdated Show resolved Hide resolved

feat(actionmenu): migrate to s2 tokens and styling

0bc5807

marissahuysentruyt reviewed Oct 16, 2025

View reviewed changes

components/actionmenu/stories/actionmenu.stories.js Outdated Show resolved Hide resolved

cdransf reviewed Oct 16, 2025

View reviewed changes

marissahuysentruyt reviewed Oct 16, 2025

View reviewed changes

chore: apply code review feedback awesomeness

1f94719

cdransf approved these changes Oct 17, 2025

View reviewed changes

marissahuysentruyt reviewed Oct 17, 2025

View reviewed changes

github-actions bot mentioned this pull request Oct 17, 2025

chore: release (next) #4254

Merged

castastrophe mentioned this pull request Oct 22, 2025

feat(badge): remove modifiers from the API [SWC-1264] #4283

Merged

14 tasks

		@@ -1,4 +1,4 @@
		import { Template as ActionMenu } from "@spectrum-css/actionmenu/stories/template.js";
		import { Template as ActionButton } from "@spectrum-css/actionbutton/stories/template.js";

Conversation

castastrophe commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How and where has this been tested?

Validation steps

Screenshots

To-do list

Notes for reviewers

References

Uh oh!

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

Uh oh!

📚 Branch preview

Uh oh!

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

Uh oh!

File metrics

Summary

actionbutton

actiongroup

actionmenu

menu

popover

Uh oh!

changeset-bot bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

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!

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!

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!

Uh oh!

5t3ph left a comment

Choose a reason for hiding this comment

castastrophe commented Jul 29, 2025 •

edited

Loading

github-actions bot commented Jul 29, 2025 •

edited

Loading

github-actions bot commented Jul 29, 2025 •

edited

Loading

changeset-bot bot commented Jul 30, 2025 •

edited

Loading