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

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

TODO: Changeset

Description

This branch migrates the action menu component by introducing a new set of custom styles for it when previously none existed. The migration includes updates to its nested components to align with the latest design standards.

The action menu is a composite component that combines an action button with a popover and a menu.

This migration introduces several key improvements:

Action menu

Limited positioning: To align with design guidance, the action menu offers a subset of the popover positioning and so the available Storybook knobs were reduced and documentation added.
S2 token integration: Migrated to use the new S2 token --spectrum-actionmenu-button-to-menu-gap.
Component architecture: To align with standard class naming conventions, the following new classes were added: .spectrum-ActionMenu, .spectrum-ActionMenu-trigger, .spectrum-ActionMenu-popover, .spectrum-ActionMenu-menu.
Documentation: Added detailed stories showcasing positioning variants, icon customization, and menu state management per design guidelines.

Action button

Improved accessibility: Added hasLongPress parameter for better control over icon display and to ensure correct aria attributes were in place.

Icon system

Enhanced styling support: Improved icon template with better styling support, custom style handling, and proper color inheritance. Added customStyles parameter and better integration between fill property and custom styles.

Menu component

Accessibility improvements: Updated roles and aria attributes according to the accessibility feedback provided by Chromatic.

The component now follows modern S2 patterns while maintaining backward compatibility and significantly improving the overall user experience and developer experience.

Motivation and context

The action menu component now has its own stylesheet with S2 design tokens and component architecture. This migration ensures consistency with other migrated components and provides improved accessibility, better positioning options, and enhanced visual design.

Related issue(s)

fixes CSS-1160

Screenshots (coming soon)

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

Action menu positioning and alignment
1. Go to the action menu component stories
2. Test different position options (bottom-start, bottom-end, start-top, end-top)
3. Expect proper alignment and no visual regressions
Icon and label customization
1. Go to the action menu component stories
2. Test different icon names and labels
3. Expect proper icon rendering and label display
Menu state management
1. Go to the action menu component stories
2. Toggle between open and closed states
3. Expect proper visual feedback and accessibility attributes
S2 token integration
1. Inspect the component's CSS custom properties
2. Verify proper usage of --spectrum-actionmenu-button-to-menu-gap and spacing tokens
3. Expect consistent spacing and alignment with S2 design system
Component structure validation
1. Check the generated HTML structure
2. Verify proper class naming (ActionMenu, ActionMenu-trigger, ActionMenu-popover, ActionMenu-menu)
3. Expect clean, semantic markup structure

Device review

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

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.87 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	24.29 KB	23.18 KB	3.05 KB	🔴 ⬆ 0.48 KB
actiongroup	7.73 KB	7.41 KB	1.09 KB	🔴 ⬆ 0.05 KB
actionmenu	0.88 KB	🆕 0.87 KB	🆕 0.49 KB	🆕 0.88 KB
menu	47.46 KB	45.20 KB	4.99 KB	🟢 ⬇ 0.47 KB

File change details

actionbutton

Filename	Head	Minified	Gzipped	Compared to base
index.css	24.29 KB	23.18 KB	3.05 KB	🔴 ⬆ 0.48 KB
metadata.json	10.70 KB	-	-	🔴 ⬆ 0.45 KB

actiongroup

Filename	Head	Minified	Gzipped	Compared to base
index.css	7.73 KB	7.41 KB	1.09 KB	🔴 ⬆ 0.05 KB
metadata.json	3.33 KB	-	-	🔴 ⬆ 0.06 KB

actionmenu

Filename	Head	Minified	Gzipped	Compared to base
index.css	0.88 KB	🆕 0.87 KB	🆕 0.49 KB	🆕 0.88 KB
metadata.json	0.34 KB	-	-	🆕 0.34 KB

⚠️ No Changeset found

Latest commit: 4a2cfe1

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

components/menu/index.css

components/accordion/index.css

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

components/coachmark/stories/template.js

@@ -23,6 +23,7 @@ export const CoachContainer = (
 		currentStep = 2,
 		totalStepCount = 8,
 		isOpen = false,
+		alt = "",


Fixing an a11y feedback note from Chromatic.

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

components/coachmark/stories/template.js

 					})}
 				>
 					<img
 						class="${rootClass}-image"
 						src="${imageSource || "example-card-landscape.png"}"
+						alt="${alt}"


Everything besides this is an auto-linting fix

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

components/combobox/stories/combobox.stories.js

@@ -1,7 +1,20 @@
 import { Template as Menu } from "@spectrum-css/menu/stories/template.js";
-import { Sizes, withDownStateDimensionCapture } from "@spectrum-css/preview/decorators";
+import {


All updates here are linting fixes.

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

components/icon/stories/template.js

@@ -39,6 +39,7 @@ export const Template = ({
 	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

@@ -78,15 +78,12 @@ export default {
 		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

@@ -133,14 +127,14 @@ export const MenuItemGroup = Variants({
 		{
 			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

@@ -37,27 +41,38 @@ const Label = ({
 	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

@@ -258,6 +274,7 @@ export const MenuItem = (
 		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 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 21 times, most recently from ddb17a8 to a3c19d7 Compare September 2, 2025 16:08

feat(actionmenu): migration to S2

eb90bd2

castastrophe force-pushed the castastrophe/feat-action-menu-migration branch 2 times, most recently from 96a7093 to d1e6569 Compare September 2, 2025 16:33

castastrophe added ready-for-review and removed wip This is a work in progress, don't judge. labels Sep 2, 2025

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

castastrophe commented Sep 2, 2025

View reviewed changes

chore(menu): apply aria fixes to menu template per a11y review

4a2cfe1

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

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

Action menu

Action button

Icon system

Menu component

Motivation and context

Related issue(s)

Screenshots (coming soon)

Author's checklist

Reviewer's checklist

Manual review test cases

Device review

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!

⚠️ No Changeset found

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!

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