Menu

Live variants

default

Markup

<j3w1-menu id="example-menu-default"><div class="menu">
  <button class="menu-button" type="button" id="example-menu-default-menu-file-button" aria-haspopup="menu" aria-expanded="true" aria-controls="example-menu-default-menu-file">File<span class="menu-chevron" aria-hidden="true"><svg viewBox="0 0 16 16" width="12" height="12" focusable="false"><path d="M4 6l4 4 4-4"></path></svg></span></button>
  <ul class="menu-list" role="menu" id="example-menu-default-menu-file" aria-labelledby="example-menu-default-menu-file-button">
    <li role="none"><button class="menu-item" role="menuitem" type="button" tabindex="0"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">New window</span><span class="menu-shortcut">Mod+Enter</span></button></li>
    <li role="none"><button class="menu-item menu-item-demo-target" role="menuitem" type="button" tabindex="-1"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Open…</span><span class="menu-shortcut">Mod+O</span></button></li>
    <li role="none"><button class="menu-item" role="menuitem" type="button" tabindex="-1" aria-disabled="true"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Save</span><span class="menu-shortcut">Mod+S</span></button></li>
    <li class="menu-separator" role="separator"></li>
    <li role="none"><button class="menu-item" role="menuitem" type="button" tabindex="-1"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Quit</span><span class="menu-shortcut">Mod+Shift+Q</span></button></li>
  </ul>
</div></j3w1-menu>

with-submenu

Markup

<j3w1-menu id="example-menu-with-submenu"><div class="menu">
  <button class="menu-button" type="button" id="example-menu-with-submenu-menu-view-button" aria-haspopup="menu" aria-expanded="true" aria-controls="example-menu-with-submenu-menu-view">View<span class="menu-chevron" aria-hidden="true"><svg viewBox="0 0 16 16" width="12" height="12" focusable="false"><path d="M4 6l4 4 4-4"></path></svg></span></button>
  <ul class="menu-list" role="menu" id="example-menu-with-submenu-menu-view" aria-labelledby="example-menu-with-submenu-menu-view-button">
    <li role="none"><button class="menu-item" role="menuitem" type="button" tabindex="0"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Reload</span><span class="menu-shortcut">Mod+R</span></button></li>
    <li role="none"><button class="menu-item menu-item-demo-target" role="menuitem" type="button" tabindex="-1" aria-haspopup="menu" aria-expanded="false" aria-controls="example-menu-with-submenu-submenu-0" id="example-menu-with-submenu-submenu-0-trigger"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Density</span><span class="menu-submenu" aria-hidden="true"><svg viewBox="0 0 16 16" width="12" height="12" focusable="false"><path d="M6 4l4 4-4 4"></path></svg></span></button><ul class="menu-list" role="menu" id="example-menu-with-submenu-submenu-0" aria-labelledby="example-menu-with-submenu-submenu-0-trigger" hidden=""><li role="none"><button class="menu-item" type="button" role="menuitemradio" aria-checked="true" tabindex="-1" data-action="submenu-0:first">First option</button></li><li role="none"><button class="menu-item" type="button" role="menuitemradio" aria-checked="false" tabindex="-1" data-action="submenu-0:second">Second option</button></li></ul></li>
    <li role="none"><button class="menu-item" role="menuitem" type="button" tabindex="-1" aria-haspopup="menu" aria-expanded="false" aria-controls="example-menu-with-submenu-submenu-1" id="example-menu-with-submenu-submenu-1-trigger"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Profile</span><span class="menu-submenu" aria-hidden="true"><svg viewBox="0 0 16 16" width="12" height="12" focusable="false"><path d="M6 4l4 4-4 4"></path></svg></span></button><ul class="menu-list" role="menu" id="example-menu-with-submenu-submenu-1" aria-labelledby="example-menu-with-submenu-submenu-1-trigger" hidden=""><li role="none"><button class="menu-item" type="button" role="menuitemradio" aria-checked="true" tabindex="-1" data-action="submenu-1:first">First option</button></li><li role="none"><button class="menu-item" type="button" role="menuitemradio" aria-checked="false" tabindex="-1" data-action="submenu-1:second">Second option</button></li></ul></li>
    <li class="menu-separator" role="separator"></li>
    <li role="none"><button class="menu-item" role="menuitem" type="button" tabindex="-1"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Full screen</span><span class="menu-shortcut">F11</span></button></li>
  </ul>
</div></j3w1-menu>

with-checks

Markup

<j3w1-menu id="example-menu-with-checks"><div class="menu">
  <button class="menu-button" type="button" id="example-menu-with-checks-menu-options-button" aria-haspopup="menu" aria-expanded="true" aria-controls="example-menu-with-checks-menu-options">Options<span class="menu-chevron" aria-hidden="true"><svg viewBox="0 0 16 16" width="12" height="12" focusable="false"><path d="M4 6l4 4 4-4"></path></svg></span></button>
  <ul class="menu-list" role="menu" id="example-menu-with-checks-menu-options" aria-labelledby="example-menu-with-checks-menu-options-button">
    <li role="none"><button class="menu-item" role="menuitemcheckbox" type="button" tabindex="0" aria-checked="true"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Line numbers</span></button></li>
    <li role="none"><button class="menu-item menu-item-demo-target" role="menuitemcheckbox" type="button" tabindex="-1" aria-checked="false"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Wrap lines</span></button></li>
    <li role="none"><button class="menu-item" role="menuitemcheckbox" type="button" tabindex="-1" aria-checked="true"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Render whitespace</span></button></li>
    <li class="menu-separator" role="separator"></li>
    <li role="none"><button class="menu-item" role="menuitemcheckbox" type="button" tabindex="-1" aria-checked="false" aria-disabled="true"><span class="menu-check" aria-hidden="true">✓</span><span class="menu-label">Minimap</span></button></li>
  </ul>
</div></j3w1-menu>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@4.0.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/menu.css';
import '@j3w1/ui/register/menu';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@4.0.0 j3w1-ui copy menu --out ./vendor/j3w1/menu

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.
`open`	`boolean`	Menu visibility.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.
`show`	`(): void`	Open and focus the first menu item.
`hide`	`(focus?: boolean): void`	Close all menus, optionally restoring the trigger.

events

Name	Type / signature	Meaning
`j3w1-action`	`CustomEvent`	An enabled action or check item was invoked.

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Specimen density

Specimen profile

Menu `menu`

Family: Navigation
Maturity: stable
Priority: R1
Since: 0.1.0
Custom widget: APG menu button (button with aria-haspopup="menu") opening a menu of menuitem, menuitemcheckbox and separator — APG pattern
specified
demonstrated
test implemented

A menu button that opens a list of actions on the raised surface inside a 1px overlay border; the active item is the selection fill and check items show a glyph.

Report an issue with this component

Tokens

Focus a role to inspect its values; follow its link for persistent usage and source details.

Part	Role	Value	Use
`button.text`	`color.text.default`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`button.bg`	`color.surface.default`approveduse	`#0d0707`	D-041 surface.default: color.primitive.modern.panel.
`button.border`	`color.border.control`approveduse	`#c81a1a`	D-041 owner correction: red control and floating-frame borders, distinct from rose text.
`button.bg-hover`	`color.interaction.hover.bg`approveduse	`#1c1010`	D-041 interaction.hover.bg: color.primitive.modern.hover.
`button.bg-open`	`color.interaction.pressed.bg`observeduse	`#420f0c`	Pressed fill.
`button.border-open`	`color.border.active`observeduse	`#e53935`	Active or focused control border.
`button.ring`	`color.interaction.focus.ring`observeduse	`#e53935`	1px dashed focus ring on controls and rows.
`surface.bg`	`color.surface.raised`approveduse	`#140b0b`	D-041 surface.raised: color.primitive.modern.raised.
`surface.border`	`color.border.overlay`approveduse	`#c81a1a`	D-041 owner correction: red control and floating-frame borders, distinct from rose text.
`item.text`	`color.text.default`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`item.bg-hover`	`color.interaction.hover.bg-strong`approveduse	`#1c1010`	D-041 interaction.hover.bg-strong: color.primitive.modern.hover.
`item.text-hover`	`color.text.link-hover`observeduse	`#f4eeee`	Link text on hover, over interaction.hover.bg-strong.
`item.text-disabled`	`color.text.disabled`approveduse	`#a3676b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`active.bg`	`color.interaction.selection.bg`approveduse	`#531310`	Selected row, tab, workspace; D-027 recessed the fill, leaving the 2px indicator and the check to carry selection.
`active.text`	`color.interaction.selection.text`observeduse	`#f4eeee`	Text on the selection.
`active.ring`	`color.interaction.focus.ring`observeduse	`#e53935`	1px dashed focus ring on controls and rows.
`check.glyph`	`color.text.bright`approveduse	`#ffa2a7`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`shortcut.text`	`color.text.muted`approveduse	`#d4868b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`separator.color`	`color.border.divider`approveduse	`#482b2b`	D-041 border.divider: color.primitive.modern.divider.
`chevron.color`	`color.icon.decorative`approveduse	`#986f72`	D-041 icon.decorative: color.primitive.modern.control.

State matrix

Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).

State	Default	With submenu	With checks
`default`
`hover`
`focus-visible`
`open`
`closed`
`disabled`
`checked`
`selected`

A short list of commands behind one button. Choosing a value is select or combobox; moving between views is tabs or the sidebar. Running an action closes the menu; a check item toggles and leaves it open.

Parts as listed in the anatomy. The active item, reached by pointer or arrow key, takes the selection fill.

State	Visual	Non-colour channel
default	button at rest; list on `color.surface.raised` in the `color.border.overlay` frame	—
hover	item → `color.interaction.hover.bg-strong`, text `color.text.link-hover`	cursor: pointer
focus-visible	1px dashed `color.interaction.focus.ring` at −2px on the button and the active item	the ring
open	button `color.interaction.pressed.bg` with 1px `color.border.active`; list shown	`aria-expanded="true"`; list present
closed	button at rest; list hidden	`aria-expanded="false"`; list absent from the tree
disabled	item text `color.text.disabled`; no hover; still reachable by arrow keys when `aria-disabled`	`aria-disabled="true"`; cursor: not-allowed
checked	✓ in `color.text.bright` in the gutter	`aria-checked="true"`; the glyph
selected	active item filled `color.interaction.selection.bg` with `color.interaction.selection.text`	focus on the item; `aria-activedescendant` where used

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

As in the key table; focus never rests on a separator.

The list is aria-labelledby the button. Disabled items use aria-disabled so they stay reachable and announced. Shortcut hints are text, not aria-keyshortcuts alone. Text meets 4.5:1; frame and ring 3:1. Items are at least 24 CSS pixels tall in compact.

A framed box of rows: the active row a fill, the frame a border, the ring an outline. Native menus keep their keyboard model and take the surface, frame and fill colours. A host that cannot draw the frame in the overlay colour uses the strong border colour and records the deviation.

A shadow under the menu. Rounded menu or items. An active item marked by text colour alone. A hover fill unlike every other menu in the product. Icons in a plain menuitem’s check gutter. A menu that stays open after an action. Links styled as menu items without role="menuitem". Disabling by opacity.

Contrast report

17 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.

Pair	State	Kind	Foreground	Background	Ratio	Min	Result
menu default text	default	text	`color.text.default` `#e99499`	`color.surface.raised` `#140b0b`	8.46	4.5	pass
menu default border	default	ui	`color.border.overlay` `#c81a1a`	`color.surface.raised` `#140b0b`	3.34	3	pass
menu hover text	hover	text	`color.text.link-hover` `#f4eeee`	`color.interaction.hover.bg-strong` `#1c1010`	16.19	4.5	pass
menu focus-visible text	focus-visible	text	`color.text.default` `#e99499`	`color.surface.default` `#0d0707`	8.72	4.5	pass
menu focus-visible border	focus-visible	ui	`color.border.control` `#c81a1a`	`color.surface.default` `#0d0707`	3.44	3	pass
menu focus-visible outline	focus-visible	ui	`color.interaction.focus.ring` `#e53935`	`color.surface.default` `#0d0707`	4.73	3	pass
menu open text	open	text	`color.text.default` `#e99499`	`color.interaction.pressed.bg` `#420f0c`	7.02	4.5	pass
menu open border	open	ui	`color.border.active` `#e53935`	`color.interaction.pressed.bg` `#420f0c`	3.81	3	pass
menu closed text	closed	text	`color.text.default` `#e99499`	`color.surface.default` `#0d0707`	8.72	4.5	pass
menu closed border	closed	ui	`color.border.control` `#c81a1a`	`color.surface.default` `#0d0707`	3.44	3	pass
menu checked text	checked	text	`color.text.bright` `#ffa2a7`	`color.surface.raised` `#140b0b`	10.14	4.5	pass
menu selected text	selected	text	`color.interaction.selection.text` `#f4eeee`	`color.interaction.selection.bg` `#531310`	12.47	4.5	pass
menu selected outline	selected	ui	`color.interaction.focus.ring` `#e53935`	`color.interaction.selection.bg` `#531310`	3.38	3	pass
shortcut hint on the raised surface	—	text	`color.text.muted` `#d4868b`	`color.surface.raised` `#140b0b`	7.01	4.5	pass
disabled item text (exempt; house floor 3:1)	disabled	ui	`color.text.disabled` `#a3676b`	`color.surface.raised` `#140b0b`	4.35	3	pass
item separator (decorative; role separator carries the grouping)	—	ui	`color.border.divider` `#482b2b`	`color.surface.raised` `#140b0b`	1.53	1	pass
submenu chevron (decorative; aria-haspopup carries the meaning)	—	ui	`color.icon.decorative` `#986f72`	`color.surface.raised` `#140b0b`	4.48	1	pass

Keys

Key	Action
`Enter / Space / Down`	On the button, opens the menu and focuses the first item; Up opens it and focuses the last.
`Down / Up`	Moves to the next or previous item and wraps.
`Home / End`	Moves to the first or last item.
`Right / Left`	Opens a submenu and focuses its first item; Left closes the submenu and returns to the parent item.
`Enter / Space`	Activates the focused item; a check item toggles and the menu stays open.
`Escape`	Closes the menu and returns focus to the button.
`Tab`	Closes the menu and moves focus to the next tab stop after the button.
`A-Z`	Moves focus to the next item starting with the typed character.

For agents

Component JSON ·Implementation brief ·Build a task kit ·

Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-STATE-MATRIX

j3w1 / theme

j3w1 / command

Live variants

default

with-submenu

with-checks

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Menu `menu`

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Live variants

default

with-submenu

with-checks

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Menu menu

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Menu `menu`