Button

How to choose a button

Every button's role comes from two independent decisions: how much visual weight it should carry (appearance), and what it means semantically (variant). Pick both, then check the component reference below for the exact wording of that combination's role.

1. Appearance — how much weight?

2. Variant — what does it mean?

The rule that trips people up: Neutral/Accent is the default primary, not Brand/Accent

Accent is a visual weight, not a colour-specific thing — a solid-fill button competes with any other solid-fill button nearby, regardless of colour. Practically, that means:

• Neutral/Accent is the default primary button. It's what most views and dialogs should reach for — the main save/submit/confirm/create action. It reads as solid and final without needing any brand emphasis.
• Brand/Accent is not the everyday "make this the important button" upgrade — it's reserved for a small set of extremely high-value, high-stakes actions (e.g. publishing something publicly, completing a major milestone). If you're reaching for Brand/Accent just because an action feels like "the" primary action in an otherwise ordinary view, use Neutral/Accent instead.

Whichever one is present, it's capped at one Accent-tier button per view — if a second action still needs to feel final rather than soft, drop it to Filled-Outlined or Outlined rather than adding a second Accent button of any colour. Two Accent-tier buttons side by side will always compete for attention.

Note: appearance="filled" is a separate, valid value outside this role system — it's used for pressed/active states in segmented controls and toggle button groups (see ButtonGroup), not for standalone button roles.

Component reference

Neutral

Brand

Brand/Filled-Outlined and Brand/Outlined are not currently in the system — considered and deliberately excluded, since Neutral/Filled-Outlined already covers "tied to the primary flow, reduced weight," and no concrete screen has needed a third brand-weighted step. Revisit if a real use case comes up.

Danger

Success

Warning

Info

Note: rendered as variant="brand" data-color="info" — this installed version of Web Awesome has no native "info" button variant. See component-overrides.css for the mapping.

Content guidelines

• Sentence case. "Save changes," not "Save Changes" or "SAVE CHANGES."
• *Product entity names stay capitalised (pending review).* Stakeholder, Property, Event, Consultation, Response (Open Point) and Project, Team, Team Leader, Campaign (Social Point) are capitalised in button labels, as with any other officially-named product term: "Add Stakeholder," "Create Property," "Delete Event," not "add a stakeholder," "create a property," "delete an event." This is the current standard, applied consistently across both products — see Capitalisation for the full reasoning and its open questions, which are still under review with marketing.
• Verb + object. Tell the user what happens: "Delete Project," "Add Stakeholder," "Send invitation." Avoid vague labels like "OK," "Yes," or "Submit" — the label should tell users exactly what will happen without needing to read surrounding context.
• 1–3 words, 5 maximum. Longer labels wrap or truncate at small sizes and slow down scanning.
• State the consequence directly for destructive actions. "Delete Consultation," not "Remove?" or "Are you sure?" — the confirmation dialog, not the button label, is where you explain what's irreversible.
• Match the label to the actual outcome. If a "Save" button also triggers a validation step, "Save" still describes the outcome correctly — but if it navigates elsewhere or triggers a side effect the user wouldn't expect, name that instead.
• Loading labels use present continuous. "Saving…," "Deleting…," "Publishing…" — not "Save" with a spinner, which reads as unresponsive rather than in progress.
• Never rely on colour alone to convey meaning. A Danger button's label should already say "Delete," "Remove," or "Revoke" — the red colour reinforces the label, it doesn't replace it.

Buttons use horizontal padding from the spacing scale. Heights are fixed per size to ensure consistent alignment with other form elements.

These values come from the --orbit-button-size-{xs|s|m|l|xl}-* tokens, listed below. The heights are shared with inputs and selects through --orbit-size-control-*, so a button and a field line up in a row.

Component tokens

Button's colours, sizes and motion are published as framework-neutral CSS variables, so any framework (including React Aria components) can use them without Web Awesome. Colours follow Light and Dark mode and the product theme automatically. Every one aliases a Semantic token, never a Primitive.

States are overlays, not separate colours: hover, active and selected draw the overlay token over the fill rather than defining a colour per state.

Full-width buttons (width: 100%) are appropriate in forms, mobile viewports, and single-column card layouts. Avoid them in toolbars or inline contexts.

All button variants display a 2px solid focus ring in --wa-color-focus with a 2px offset, visible on both light and dark backgrounds. The ring must have at least 3:1 contrast against colours adjacent to it.

Use :focus-visible rather than :focus to suppress the ring on mouse click while preserving it for keyboard navigation.

After activation, focus must follow the outcome:

• Opening a dialog → focus moves to the first focusable element inside the dialog.
• Closing a dialog → focus returns to the button that triggered it.
• No context change (e.g. toggling state) → focus stays on the button.

Normal-weight text requires 4.5:1 contrast. Large text (18px regular or 14px bold) requires 3:1. Focus indicators and UI boundaries require 3:1 against adjacent colours. Disabled states are exempt.

The minimum touch target is 24×24px. The recommended target is 44×44px — use this as the standard for all interactive elements.

The medium button (40px height) meets the minimum and approaches the recommendation with horizontal padding included. The small variant (32px height) requires an invisible touch target extension to reach 44×44px.

On Social Point community-facing surfaces, prefer medium or large buttons. Community participants include people with motor impairments for whom small tap targets are a significant barrier.