feat(action-menu): S2 migration [CSS-1160] #4085

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.44 MB^*
Total change (Δ): 🔴 ⬆ 0.83 KB (0.05%)

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.62 KB	22.53 KB	2.99 KB	🟢 ⬇ 0.04 KB
actiongroup	7.73 KB	7.41 KB	1.09 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

File change details

actionbutton

Filename	Head	Minified	Gzipped	Compared to base
index.css	23.62 KB	22.53 KB	2.99 KB	🟢 ⬇ 0.04 KB
metadata.json	10.52 KB	-	-	🔴 ⬆ 0.34 KB

actiongroup

Filename	Head	Minified	Gzipped	Compared to base
index.css	7.73 KB	7.41 KB	1.09 KB	🔴 ⬆ 0.06 KB
metadata.json	3.33 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

🦋 Changeset detected

Latest commit: 2aed50b

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

castastrophe · 2025-09-02T16:49:20Z

components/coachmark/stories/template.js

 		currentStep = 2,
 		totalStepCount = 8,
 		isOpen = false,
+		alt = "",


Fixing an a11y feedback note from Chromatic.

components/coachmark/stories/template.js

components/combobox/stories/combobox.stories.js

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

components/icon/stories/template.js

 	fill,
 	id = getRandomId("icon"),
 	customClasses = [],
+	customStyles = {},


I saw a regression in the icon VRTs where the fill was inheriting to all icons due to the custom property's inheritance.

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.

castastrophe · 2025-09-02T17:01:11Z

components/menu/stories/template.js

 		hasExternalLink = false,
 		hasActions = false,
 		id = getRandomId("menuitem"),
+		labelId = getRandomId("menuitem-label"),


label id lets us connect the switch input field with the already present label for the menu item

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

castastrophe · 2025-09-19T17:18:36Z

components/menu/index.css

-		.spectrum-Menu-itemCheckbox {
-			grid-area: checkmarkArea;
-		}
+	&.is-selectableMultiple:not(:has(.is-selectable)) .spectrum-Menu-itemCheckbox {


Added this not to prevent clash with the is-selectable placement.

components/actionmenu/stories/template.js

components/actionmenu/index.css

rise-erpelding · 2025-09-24T20:54:42Z

components/actionmenu/stories/actionmenu.stories.js

+ * Action menu allows users to access and execute various commands or tasks related to their current workflow. It's typically triggered from an action button by user interaction.
+ *
+ * Note that the accessibility roles are different for an action menu compared to a normal menu. The action menu is a combination of a menu, popover, and action button.


I think this might be the same description that appears for the default story as well, we could probably eliminate one of these!

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?

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.

rise-erpelding · 2025-09-25T16:09:14Z

components/menu/index.css

I see the accessibility improvements that are mentioned in the changeset for menu but I don't really see updates to some of these other items (forced-colors, focus indicator, cjk), am I looking in the right place?

Menu refinements

Updates @spectrum-css/menu styles to align with latest Spectrum 2 design specifications and improve accessibility.

Focus indicator tokens wired through: width, color, gap/offset, and outline style.

CJK line-height tokens applied for labels, descriptions, and section headers.

External link and drill‑in icon sizing variables exposed; thumbnail sizing and alignment refined.

Forced-colors improvements and readability adjustments.

Non-breaking; no class or DOM changes required.

Hmm I wonder if I pulled some of that back and forgot to update the changeset. I'll double check.

rise-erpelding · 2025-09-25T17:09:48Z

components/actionmenu/index.css

+
+/*
+ * @spectrum-css/actionmenu
+ * This component is a combination of a menu, popover, and action button.


This comment is more related to popover, which wasn't changed in this PR:

I see the button jumping a bit (for bottom-start it moves down and to the right) when I click it, I think it's related to the previous popover positioning (alliteration always!) work and doesn't seem intentional:

Screen.Recording.2025-09-25.at.12.01.12.PM.mov

If I pull down spectrum-two, I can also see the issue there:

Screen.Recording.2025-09-25.at.12.08.30.PM.mov

Just noting I still see this jumping around! Sadly I don't think the video I attached previously is working, I'm going to try a gif version instead!

I'm seeing:

The action button jumps from the middle of the window to more of an upper-left position (only if I reload this from a closed position though)

Smaller shakes every time I reopen it from a closed position.

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?

5t3ph · 2025-09-23T21:15:27Z

components/actionbutton/index.css

-	&.is-selected {
+	/* expanded is specific to action menu when the menu is open */
+	&:where(.is-selected, [aria-pressed="true"], [aria-expanded="true"]) {
 		--mod-actionbutton-background-color-default: var(--mod-actionbutton-background-color-default-selected, var(--spectrum-neutral-background-color-selected-default));


Should this update component properties instead of mods, or is it a case where it hits an issue going into SWC environment?

Either way - a good case to flag for our upcoming discussions around this 👍

That said - I also don't see this change in the Action Menu tokens, possibly because "selected" is a different state/intent than "expanded"? Should we double-check with design if this should take on the darker background?

Yes, action button should be our first attempt to introduce layers I suspect because it is riddled with specificity battles and often hooking the modifiers was the only way to ensure properties updated in context.

got it, ok!

5t3ph · 2025-09-25T20:02:09Z

components/actionmenu/stories/actionmenu.stories.js

+};
+
+/**
+ * Action menus can be positioned in four locals relative to the trigger but <u>only one menu can be triggered at a single time</u>.


[nit] perhaps switch to <em> since underlines usually indicate a link?

Great point! Updating this now.

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.

rise-erpelding · 2025-09-30T21:10:35Z

components/coachmark/stories/template.js

 						imageIsFixedHeight: true,
 						imageSource: "example-card-portrait.png",
 						customStyles: {
 							"height": "315px"


I think this 315px set height is causing this issue on the Coachmark Docs page:

rise-erpelding · 2025-09-30T21:37:51Z

components/actionbutton/index.css

-	&:disabled,
-	&.is-disabled {
+	/* ideal when we want to disable the button but still allow it's content to be focused */
+	&:where(:disabled, .is-disabled, [aria-disabled="true"]) {


Just noticed that I think this might be changing the specificity so that I see the text color change when I hover over the disabled action button 😱

rise-erpelding · 2025-09-30T21:43:46Z

components/actionmenu/stories/actionmenu.stories.js

Docs page looks great!

rise-erpelding · 2025-09-30T21:52:04Z

components/popover/stories/template.js

 		if (["top", "bottom"].some((e) => position.startsWith(e))) {
 			customWrapperStyles["min-inline-size"] = "var(--spectrum-popover-width)";
-			customWrapperStyles["min-block-size"] = "calc(var(--spectrum-popover-height) + var(--spectrum-popover-trigger-height, 0px) + var(--mod-popover-wrapper-spacing, var(--spectrum-spacing-100) * 2))";
+			customWrapperStyles["min-block-size"] = "calc(var(--spectrum-popover-height) + var(--spectrum-popover-trigger-height, 0px) + var(--spectrum-popover-animation-distance, var(--spectrum-spacing-100) * 2))";


Awesome, now I can see the action menu CSS working to set the spacing properly!

I do think there's still a little funkiness going on with popover: the growing height/width thing on the Popover/Coachmark story I mentioned, plus the positioning of the popover seems to change when switching stories from Action menu to Popover. I already mentioned this in the comment on the Coachmark template.js but just wanted to make sure it didn't get lost!

rise-erpelding · 2025-09-30T22:03:27Z

components/actionmenu/index.css

+
+/*
+ * @spectrum-css/actionmenu
+ * This component is a combination of a menu, popover, and action button.


Just noting I still see this jumping around! Sadly I don't think the video I attached previously is working, I'm going to try a gif version instead!

I'm seeing:

The action button jumps from the middle of the window to more of an upper-left position (only if I reload this from a closed position though)

Smaller shakes every time I reopen it from a closed position.

rise-erpelding · 2025-09-30T22:06:28Z

.changeset/brave-bikes-teach.md

+### Menu refinements
+
+Updates `@spectrum-css/menu` styles to align with latest Spectrum 2 design specifications and improve accessibility.
+
+- Focus indicator tokens wired through: width, color, gap/offset, and outline style.
+- CJK line-height tokens applied for labels, descriptions, and section headers.
+- External link and drill‑in icon sizing variables exposed; thumbnail sizing and alignment refined.
+- Forced-colors improvements and readability adjustments.
+- Non-breaking; no class or DOM changes required.


I can't find the comment off the top of my head, but did we talk about updating this part of the changeset to more accurately reflect menu changes?

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 commented Sep 2, 2025

View reviewed changes

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch from 1ddcb45 to 4a2cfe1 Compare September 2, 2025 17:25

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch 3 times, most recently from 748e3cb to 76988b3 Compare September 10, 2025 14:15

castastrophe commented Sep 10, 2025

View reviewed changes

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch 7 times, most recently from e4bf910 to 46a8a1b Compare September 19, 2025 17:14

castastrophe commented Sep 19, 2025

View reviewed changes

feat(actionmenu): migrate to s2 tokens and styling

75c284c

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch from 46a8a1b to 75c284c Compare September 19, 2025 17:28

rise-erpelding reviewed Sep 25, 2025

View reviewed changes

5t3ph reviewed Sep 25, 2025

View reviewed changes

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch from 14468b0 to 22ccfc9 Compare September 29, 2025 17:27

chore: apply code review feedback awesomeness

2aed50b

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch from 22ccfc9 to 2aed50b Compare September 29, 2025 18:04

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

feat(action-menu): S2 migration [CSS-1160] #4085

Are you sure you want to change the base?

feat(action-menu): S2 migration [CSS-1160] #4085

Uh oh!

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

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!

Choose a reason for hiding this comment

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!

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

Menu refinements

Uh oh!

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