Button

Overview

Use .btn for a standard button and add at most one variant class to describe the action’s role, such as btn outline. Prefer these shared styles. If a new use case needs another variant, add it to the library so other callers can use it.

Anatomy

A native <button> with class="btn" and optionally one variant class (.outline, .ghost, .destructive) plus stackable modifiers (.sm, .full-width, [aria-pressed]).

Choose at most one variant and any number of modifiers. Modifiers lists the supported combinations and explains when appearance follows an attribute, such as aria-pressed, instead of a class.

Usage

Variants

• .btn — primary action: the main call-to-action in a view (form Submit, "Invite", "Create").
• .btn.outline — secondary action: Cancel/Close in dialogs, toolbar items, nav link-buttons, toggles like "All items" / "Selected only".
• .btn.ghost — tertiary action: low-emphasis inline controls, dropdown triggers that should visually recede.
• .btn.destructive — dangerous action: irreversible operations like Delete. Use sparingly.

Modifiers

Stackable with any variant — see Modifiers for the full list.

• .sm — compact (smaller font-size and padding).
• .full-width — stretch to fill the container (for form submits).
• [aria-pressed="true"] — pressed / selected state for toggle buttons.
• .btn-icon — icon-only button with no text (a sibling class, not a modifier).

Every variant with each modifier and state. The headers name the classes and attributes on each button.

States

Hover and focus-visible are defined in /ui/ui.css. Disabled via the native disabled attribute (opacity 0.5, pointer-events: none) or aria-disabled="true" when the button must remain focusable (opacity 0.5, cursor: not-allowed — the button still takes focus and still fires click).

Icon button

Icon-only buttons use .btn-icon (distinct from .btn): a fixed --size-7 square with a transparent background, so it holds one glyph and no label. Its <ui-icon> child is rendered larger than an icon sitting beside a text label in .btn, so the icon fills an appropriate amount of the button. Always provide an accessible name.

Accessibility

• Role — implicit role="button" on <button>. Activate with Enter or Space. Avoid <div role="button">.
• Icon buttons — must have aria-label (or a .visually-hidden label inside). title alone does not satisfy screen readers reliably.
• Toggle buttons — add aria-pressed="true|false". Screen readers announce "pressed" / "not pressed".
• Destructive buttons — pair with a confirmation dialog for irreversible operations: response_dialog from /ui/lib/dialog.mjs, or a <ui-dialog alertdialog> whose confirm button carries [dialog-confirm].
• Disabled — native disabled is simpler but removes from the tab order. Use aria-disabled if the button must remain focusable (e.g. to surface a tooltip explaining why it's disabled) — the attribute changes the appearance but does not block clicks, so the click handler must check it.

Cross-system

See Cross-system reference § Actions for mappings to Material Web md-button, Bootstrap .btn, and WAI-ARIA APG.

See also

• .badge — non-interactive status pill.
• .form-fields — form submit uses .btn.
• <ui-dialog> — confirmation flow for destructive actions.
• Color — brand / destructive color tokens.