Toolbar

Problem Context

• A document, canvas, map, table, list, media viewer, or selected object has several frequent commands that users apply repeatedly.
• The commands share one scope and can remain visible without interrupting the work surface.
• Some commands are compact, stateful, grouped, or lower priority enough to need separators, toggles, menus, or overflow.
• Keyboard users need to move through the command set efficiently without leaving the work context.

Selection Rules

• Choose toolbar when a persistent view-scoped command surface groups several related controls for repeated use.
• Use a button group when there are only a few visible peer actions for one workflow moment and ordinary tab order is sufficient.
• Use a menu button when secondary commands can stay hidden behind one named trigger.
• Use a command palette when commands are broad, searchable, shortcut-driven, or cross-product rather than scoped to the current view.
• Use header, global navigation, side navigation, tabs, or bottom navigation when controls move between destinations instead of applying commands.
• Do not put unrelated actions into one toolbar just because they share horizontal space.
• Do not rely on tooltips as the only names for icon-only toolbar controls.
• Keep primary submit, destructive review, and multi-step decisions outside overflow unless the toolbar is explicitly the correct command surface.
• Define overflow priority before responsive collapse so essential controls remain available and secondary controls move predictably.
• Use toolbar role and composite keyboard behavior only when the implementation provides arrow-key focus movement and predictable nested-control behavior.

Required States

• Default toolbar with label, visible scope, grouped controls, and focusable entry point.
• Keyboard focus inside the toolbar with current roving item or active control indicated.
• Arrow-key movement among toolbar controls.
• Pressed or selected toggle state for stateful commands such as Bold, Filters on, or Preview mode.
• Disabled command state with visible reason or unavailable target.
• Selection-scoped state showing selected object count and enabled contextual commands.
• Overflow state when commands do not fit or are lower priority.
• Nested menu button or compact input state inside the toolbar.
• Command activated state with status feedback and focus preserved.
• Responsive narrow viewport state with stable priority and reachable overflow.

Interaction Contract

• The toolbar has a clear accessible name and visual scope tied to the current view, selected objects, or editor surface.
• Controls inside the toolbar share one command context; unrelated navigation and page-level settings stay outside.
• Tab reaches the toolbar in a predictable place, and implementations using composite toolbar behavior let arrow keys move between controls.
• Home and End move to first and last toolbar controls when supported by the implementation.
• Enter or Space activates the focused command, toggles stateful buttons, or opens a nested menu button according to the control role.
• Activation preserves the user's object selection and focus unless the command intentionally opens a dialog, route, or confirmation flow.
• Disabled controls communicate why they are unavailable when the reason is not obvious from selection or context.
• Overflow retains command labels, grouping, and object scope rather than becoming an unnamed dumping ground.
• Nested controls define whether arrow keys move within the control or across toolbar items, avoiding conflicting behavior.

Implementation Checklist

• Inventory the commands and remove actions that do not share the toolbar's current view or selection scope.
• Name the toolbar by the surface it controls, such as Text formatting, Map tools, Selected rows, or File preview actions.
• Group controls by task, add separators where groups change, and order commands by frequency and risk.
• Define which commands are visible, which move to overflow, and which belong in a menu, dialog, footer, or command palette.
• Implement native buttons, toggle buttons, menu buttons, inputs, and labels with synchronized accessible names and states.
• Choose ordinary tab order or composite toolbar keyboard behavior deliberately; if using toolbar role, implement arrow movement and orientation.
• Keep disabled reasons, selected object count, pressed state, command result, and overflow status available to assistive technology.
• Test keyboard, screen reader, high zoom, touch target size, mobile overflow, localization, forced colors, and nested widget key conflicts.

Common Generated-UI Mistakes

• Labelling any horizontal button row as a toolbar without shared scope or keyboard behavior.
• Using a toolbar for primary app navigation or unrelated destinations.
• Packing rare, destructive, and primary submit actions into one dense strip.
• Using icon-only buttons whose names exist only in hover tooltips.
• Forgetting pressed state for toggles such as Bold, Filter on, or Preview.
• Leaving selection-only commands enabled when nothing is selected.
• Putting form fields, tables, or long explanations in toolbar overflow.
• Letting responsive collapse hide important commands behind an unnamed More icon.

Critique Questions

• What surface or selected object does this toolbar control?
• Do all controls share that scope, or are navigation and unrelated commands mixed in?
• Can keyboard users enter once, move between controls efficiently, activate a command, and keep their selection?
• Which controls are stateful, disabled, destructive, or overflowed, and how are those states exposed?
• Would a button group, menu button, command palette, header, or navigation pattern better match the user's job?