These conventions define where users find commands across PUDL sites. They were agreed on 2 October 2026. They complement the web contract and integration guide. The implementation notes below describe support in PUDL 0.40.0. The API is documented in the web contract; the vendored PUDL specification is unchanged.
The site bar belongs to the site or application shell. Its commands and order remain stable as the active applet changes. The applet bar belongs to the active applet, article, or other content and appears to the site’s right. An article can use its title as the identity of that group. Existing implementation terms host and front refer to these respective groups; their API names remain unchanged.
Each group begins with an identity menu bearing its owner’s visible name, optionally with a logo. The hamburger glyph toggles that group’s first menu. The name and glyph must not navigate to different destinations or expose different commands.
Each group forms one slightly raised surface around its glyph, identity, and menu titles. Its shared border and shadow establish that elevation in both themes. This follows the Parks Computing appearance confirmed on 3 October 2026. Individual titles gain hover, open, and focus treatments within that surface.
Menus describe the scope of their commands. Opening a menu does not change the active content or selection on which those commands operate. Settings labels distinguish this instance’s settings from defaults for future instances where both exist.
The standard order is Site name, Go, Applets, View, Window, Help. A site omits menus for which it has no meaningful commands. The remaining menus retain their relative order. Site-specific menus may appear after Applets and before View when their purpose cannot fit a standard menu. They must not become destinations for applet command contributions.
Applets is a top-level launcher immediately after Go. Launching a tool is frequent enough to deserve direct access and is distinct from navigating site destinations. Do not bury the primary launcher under Go. A toolbar or launch page may provide an additional route.
| Menu | Contents |
|---|---|
| Site identity | Home; About the site; Site settings when available; account and sign-in commands when applicable; Copy workspace link when supported. |
| Go | Site destinations, site search, and navigation commands. |
| Applets | Available tools that users can launch. The list describes available tools, regardless of which instances are already open. |
| View | Site presentation, including theme, sidebar visibility, and window/classic layout. |
| Window | Active-window controls, arrangements, bulk window commands, and the open-window list. |
| Help | Site help, keyboard guidance, support, and the active applet’s help contribution. |
The identity menu groups related entries with separators. It is not a general navigation directory or a drawer for unrelated commands. Theme choices belong under View; the settings page can expose the same preference. Applet launching belongs under Applets. Account actions remain clearly separated from navigation and workspace sharing. A browser site must not offer Quit unless its environment actually supports quitting the application.
Applets launches tools; Window selects and manages existing windows. Sites with multiple instances must make launch behavior clear, using labels such as New editor window when a command always creates another instance. Reusing an existing instance must not discard its work.
A site may add a pins group between the site bar and the applet bar, for the applets and articles its readers go to most, one press away in both the window and classic views. It was proposed by parkscomputing.com on 5 October 2026. The group stands after the site bar so that it stays put as the active applet changes.
Its first control is the Pins menu, marked by the pin glyph as an identity is marked by the menu glyph. The menu holds the site’s pinning commands, such as Pin “About” and Unpin “About” for whatever is in front, disabled when nothing pinnable is. After it come buttons, not menus, one for each pinned item, showing the icon and title the item shows elsewhere, such as in the taskbar. Each is a link to the item’s page, so a modified click opens a new tab, and the site may handle a plain press itself, as a window view does by opening or raising the item’s window.
When the buttons do not fit, they all give way together to one menu, Items, which lists them, so the bar never shows an arbitrary subset. That happens before the bar itself collapses. In the collapsed bar, the Pins section lists the pinning commands and then the pins. A group with nothing pinned keeps its Pins menu, so the reader can see where pins go.
Storing pins and deciding what can be pinned are the site’s. Pinning a particular item is an operation on that item, so a Pin command also belongs in the item’s own domain menu or window menu, where the reader works with it; the Pins menu offers the same command for whatever is in front.
The standard order is Applet name, File, Edit, domain menus. File and Edit appear only when the applet supports their functions. Domain menus use familiar nouns or verbs from the applet’s work, such as Palette, Game, Story, Discussion, Query, or Run. An applet must not create its own Go, Applets, View, Window, or Help menu; the contribution rules below provide shared destinations where appropriate.
| Menu | Contents |
|---|---|
| Applet identity | About the applet; Applet settings when available; Open as a page when supported; Copy link to this applet or content; Close window when windowed. |
| File | Creation, opening, saving, import, export, printing, and document lifecycle commands. |
| Edit | Undo/redo, supported selection and clipboard operations, and find/replace. |
| Domain menus | Commands specific to the applet’s subject or workflow. |
Close window is the final identity-menu command, separated from sharing commands. Close document belongs under File. Labels must distinguish these actions where both exist. A standalone page must not imply it can close the browser tab.
Save, Run, Pin, sorting, and similar working commands do not belong in the identity menu. A small applet still gives working commands a named domain menu; it does not use its identity menu as an exception. A content reader can use Reader as its identity, with Story and Discussion as its working menus. Long article titles may be visually truncated while retaining their complete accessible names.
Only the active applet contributes commands. Its contribution follows the site’s entries, separated and headed by the applet’s name. It cannot replace, reorder, or relabel site commands, add commands to the site identity menu or Applets launcher, or create site-bar titles. Launch registration belongs to the host’s applet catalog and is independent of the active applet’s menu contributions.
| Site menu | Permitted contribution |
|---|---|
| Go | Navigation within the active applet, such as previous/next item or go to line. |
| View | Presentation of the active applet, such as word wrap, line numbers, or preview visibility. |
| Help | Applet help, applet keyboard guidance, and applet-specific support. |
| Window | No arbitrary injected commands. The host supplies standard window actions from supported window capabilities. |
A command has one canonical menu location. Toolbar buttons and contextual menus may provide additional access. Applet-local navigation goes under Go, while operations on content stay in its domain menu. For example, Next story belongs in the reader’s Go contribution; Pin this story belongs under Story. Discussion-specific sorting can remain under Discussion because it is an operation on that content collection. View governs presentation such as showing a preview or wrapping text.
Shared slots have a consistent meaning even when their contents are contextual. An applet’s View command still targets that applet. Moving it into the site bar must not make its keyboard shortcut global.
Hosts must provide each shared menu required by their installed applets, even if the host itself has no commands for it. The menu appears when it has commands and disappears when empty. Commands must not silently vanish because a host omitted a required destination. Hosts use data-menubar-id for these destinations. Applets use those IDs as into keys. Exact displayed labels remain a compatibility fallback; IDs are preferred for translated sites.
PUDL 0.40.0 implements standard menu IDs and ordering, validates contribution destinations, preserves command ownership across contributions, and closes menus when their source is removed or replaced. Existing label-based contributions still resolve where their destination has a permitted standard identity. Empty declared slots appear when populated and are omitted otherwise. Missing or disallowed destinations produce console diagnostics.
Hosts opt into generated window management by adding data-menubar-windows to a title with data-menubar-id="window". PUDL obtains capabilities from pudlWindows.menuCommands(), the same source used by window chrome, and adds bulk actions and the open-window list. Custom content commands cannot enter this generated list.
Legacy commands() applets retain their working commands under Actions and receive a separate identity menu. Since 0.51.0 a window whose content offers no menu receives the same identity menu under the window’s title. Generated article menus use scope-specific sharing and close labels, and since 0.49.0 have no File menu: Print is in the article’s identity menu, only where the host marks its page menu data-page-print, because printing a page of windows prints the desktop rather than the article. Explicit applet menus() definitions remain author-controlled: PUDL cannot infer whether a command called Settings changes this instance or every instance, or whether a domain command belongs in the identity menu. Site authors must apply the placement rules above.
The migration guide gives the supported markup and API changes. The implementation design records the decisions and verification scope.