Button

WHEN TO USE

• The control performs an action in the current page: submits a form, opens a dialog, applies a filter, saves a draft.
• The action has to participate in a form. type="submit" and type="reset" are routed through the shared FormController, so a button inside a <form> behaves like a native one even across the shadow boundary.
• A dense toolbar needs an icon-only affordance: set hideText, supply label, and put the glyph in the before slot.
• You need to rank actions visually — primary, secondary, tertiary, neutral and bare are the whole ladder, and there is no sixth treatment.

WHEN NOT TO USE

• The control only navigates, and should read as text inside a sentence or a list of destinations. href does swap in an <a>, but it keeps button styling and role="button" — use it only when the navigation is meant to look and be announced like a button.USE LINK →
• You are putting several buttons side by side and what you actually want is control over their spacing. There is no button-group component: it was removed precisely because it owned arrangement and nothing else.USE LAYOUT →
• The control flips a state that stays visible after the click — a filter pill, a view switch, a formatting toggle. That is selection, not invocation, and it wants a component that owns the selected state.USE TOGGLE-BUTTON →
• The trigger opens a list of navigation destinations. Let the menu own its own trigger relationship rather than wiring a bare button to a floating list by hand.USE MENU →

DO

• For an icon-only button, set hideText, supply label, and place the icon in the before slot. That exact pattern is documented on the component with a worked example, and it is the only combination that produces one accessible name.
• Gate the action in your own click handler when the button is disabled. The component renders aria-disabled but not the native disabled attribute, and its click handler has no disabled branch, so a disabled submit button still submits.
• Drive isExpanded from the open state of whatever the button controls, so the control and the thing it discloses never disagree.
• Reserve variant="primary" for the one action you most want taken on a screen. A strongest-emphasis treatment used for merely important actions stops ranking anything. A destructive confirm is a primary button with destructive copy — status lives on al-badge and al-alert, not on this axis.

DON’T

• Don't combine hideText with visible slot text. The text node is only visually hidden — it stays in the layout and in the accessibility tree, so it duplicates label into a redundant accessible name.
• Don't rely on the glyph alone for meaning. With hideText set and no label, the button ships with no accessible name at all.
• Don't assume ariaControls reaches the DOM on a plain button. It is rendered on the href branch only; the <button> branch emits aria-label, aria-disabled, aria-pressed and aria-expanded and stops there.
• Don't use variant="bare" as a way to draw a link. A bare button is still announced as a button, and still activates on Space.
• Don't leave a disabled button as the only visible path forward without saying somewhere what would enable it. A disabled control is not an error message.