Menu

Canonical specification

Purpose

Offers a short list of actions behind one button. A menu is for commands; choosing a value belongs in select or combobox, and moving between views in tabs or the sidebar. Menus close as soon as an action runs.

Anatomy

A menu button, styled as a secondary button, that opens a list on color.surface.raised inside a 1px color.border.overlay frame. Items are buttons in color.text.default with a check gutter at the inline start, the label, and an optional shortcut hint in color.text.muted. Separators are 1px color.border.divider rules. The active item, whether reached by pointer or by arrow key, is the selection fill color.interaction.selection.bg with color.interaction.selection.text. The reference renders the menu open in flow beneath the button; a host positions it at z.popover.

States

Precedence: disabled > selected > hover; focus-visible is always drawn.

Keyboard

The button opens on Enter, Space or Down (focus on the first item) and on Up (focus on the last). Inside, Up and Down move and wrap, Home and End jump, Right opens a submenu and Left closes it, typing a letter jumps to the next matching item. Enter or Space activates; a check item toggles without closing. Escape closes and returns focus to the button; Tab closes and continues the tab order. Focus never rests on a separator.

Accessibility

The button carries aria-haspopup="menu", aria-expanded and aria-controls; the list role="menu" and aria-labelledby pointing at the button. Items are role="menuitem" or role="menuitemcheckbox" with aria-checked; disabled items use aria-disabled so they remain reachable and announced. Shortcut hints are text, not aria-keyshortcuts alone. Contrast: item text 8.43:1 and shortcut 5.66:1 on the raised surface, active text 12.47:1 on the fill, the frame 4.57:1, ring-container 7.48:1 on the fill. Items are the row height, at least 24 CSS pixels in compact density.

Portability

A framed box with rows; the active row is a fill, the frame a border, the ring an outline. Toolkits with native menus keep their keyboard model and take the surface, frame and fill colours. Hosts that cannot draw the frame in the overlay colour draw it in the strong border colour and record the deviation.

Non-examples

A shadow under the menu. Rounded corners on the menu or the items. An active item marked by text colour alone. A hover fill that differs from every other menu in the product. Icons in the check gutter of a plain menuitem. A menu that stays open after an action. Items that are links styled as menu items without role="menuitem". Disabling by opacity.