Button

Purpose

A button labels an action and invites the user to take it. The label must be specific enough that the outcome is unambiguous before the tap — "Book now", not "Submit". The visual weight of the button (primary vs ghost) communicates how important that action is relative to everything else on the page.

Usage

Reach for a button when the tap changes state or data — booking a trip, saving a form, cancelling a reservation, submitting a search. When the goal is navigation — moving the user to a different URL with nothing changing on the server — reach for a Link instead, even if it needs button-like visual weight (in which case, pass href to this component; see Buttons vs links).

Buttons appear wherever a flow needs a decision point: at the bottom of a form (submit / cancel), inside a modal or drawer (confirm / dismiss), on a card (a single supporting action), and in a toolbar (compact, low-emphasis controls). The variant you choose should match how many other actions compete for attention in that exact spot — see Variants below.

Anatomy

The focus ring (callout 5) only renders on :focus-visible — tab to the button above with your keyboard to see it appear.

Measurements

The redline below is drawn from the values actually shipped in Button.jsx and lib/kuoni-tokens.js at the md size — nothing here is estimated. Kuoni buttons use content-driven auto width; there is no 150 px-style fixed minimum. The only enforced floor is the min-width baked into each size's Tailwind class (min-w-[80px] at md), which only becomes visible when the label is very short — most real labels (multi-word, verb-led) exceed it comfortably.

Variants

Primary

Wow Yellow background, Dark text. The single highest-emphasis action on the view.

When to use: The single most important thing a user can do on the current view. "Book now" on a holiday detail page. "Continue to payment" at the bottom of a booking form. "Search" on the homepage search widget.

---

Secondary

Dark background, white text. High emphasis but not the primary action. Appears alongside, never instead of, the primary button when a second important action exists.

When to use: An important supporting action that exists on the same view as a primary button. "Save and exit" next to "Continue". "View all offers" next to "Book now". If you find yourself making this decision often, reconsider whether the second action is truly important enough to warrant the visual weight.

---

Ghost

Transparent background, dark stroke border. Low emphasis. Disappears into the layout while remaining clearly interactive.

When to use: Dismissal actions ("Cancel", "Close"), tertiary navigation links styled as controls ("Back", "Edit"), toolbar and table row actions that should not compete with primary content. In a button group, ghost lives next to a primary or secondary button.

---

Danger

Red background, white text. Reserved for irreversible or destructive actions.

When to use: Permanently destructive actions where the consequence cannot be undone — "Cancel booking", "Delete account", "Remove traveller". Never use danger for actions that are merely negative in sentiment but reversible.

---

Variant comparison

Sizes

Three sizes share the same type size and padding rhythm. The height difference (32 / 40 / 48 px) establishes the touch-target hierarchy. Default to md for all product UI; use lg for hero and marketing moments; use sm for compact toolbars and table row actions.

Tap target is the touch input case: WCAG 2.1 AA (2.5.5) requires a 44 × 44 px minimum for anything operated by a finger. Kuoni honours this by expanding the effective touch area with padding/margin at sm, and by the rendered box already meeting it at md/lg.

Click target is the pointer input case — mouse or trackpad, which is far more precise than a fingertip. The rendered button box itself is the click target, and it can safely be smaller than 44 × 44 px for pointer users; the two figures are shown separately here because conflating them into one blended number would either understate the touch requirement or overstate what pointer users actually need.

States

Default and hover

The button transitions its background on hover over 150 ms. The cursor changes to pointer. A pressed (active) state darkens by one more step.

---

Disabled

Prefer keeping the button enabled and showing a validation error over disabling it. A disabled button is hard to discover — it doesn't invite the tap, and once tapped (or not) it explains nothing about what's missing or how to fix it. In most product flows the better pattern is: leave the button active, let the user attempt the action, and surface a clear inline error ("Add at least one traveller to continue") when they do. Reserve true disabling for cases where the action is genuinely unavailable in a way that doesn't need to be discoverable — a "Refresh" button with no new data to fetch, not a "Continue" button waiting on form completion.

The disabled prop applies the native disabled attribute, which:

• Removes the button from the tab order
• Prevents all pointer and keyboard events
• Reduces opacity to 40%

When to use disabled: When the action is genuinely not available in the current application state and you do not need sighted keyboard users to discover the button still exists (e.g., a submit button before a required form field is filled — and only when a validation-error alternative genuinely isn't feasible).

When to prefer aria-disabled: When the button exists but is temporarily unavailable and keyboard users should still be able to find it and understand why it is inactive (e.g., a "Proceed" button that's waiting for a price-check API call to return). Manage the click behaviour in onClick instead of using the native attribute.

---

Loading

The loading prop shows a spinner in the leading icon position, blocks interaction, and sets aria-busy="true" and aria-disabled="true" so assistive technology announces the change. The button label is preserved so the button width stays stable and screen readers still hear the action name.

A visually-hidden loadingLabel ("Loading, please wait" by default) is injected for screen readers. Customise it to describe the specific operation:

<Button loading loadingLabel="Checking flight availability">
  Search
</Button>

With icons

Icon slots sit inside the button's padding — not outside it — so the overall visual weight stays constant. Use 16 px icons at md size (12 px at sm, 20 px at lg).

Leading icon

Trailing icon

Icon-only

When using a button with no visible label, you must supply aria-label so screen-reader users know what the button does.

The loading spinner automatically replaces the iconLeft icon while loading so you never need to hide it manually.

Full width

The fullWidth prop makes the button stretch to fill its container. Use for mobile form actions and any context where the button should be the primary width reference on the page.

Button groups

When two or more actions appear side by side, place the primary (or most important) button first, followed by secondary or ghost variants.

Where groups sit in a layout

Use gap-3 (space.3 — 12 px) between buttons in a horizontal group, matching the token already used for button internal padding rhythm. Don't invent a different gap value for grouped buttons.

Minimum button width

Kuoni buttons are auto-width by content, with an enforced Tailwind min-w-[80px] at md (64px at sm, 96px at lg) baked into Button.jsx's size classes — see Measurements above. When grouping buttons of the same size, this shared floor keeps very short labels ("Cancel", "Back") from looking narrower than their neighbours.

Grouping combinations

Buttons vs links

Pass href to render the button as an <a> tag with button styling — for CTAs that navigate rather than act. An aria-label is applied automatically and rel="noreferrer noopener" is added when target="_blank".

{/* Action — form submit */}
<Button type="submit" variant="primary">Complete booking</Button>

{/* Navigation — link styled as button */}
<Button href="/destinations/maldives" variant="secondary">
  Explore the Maldives
</Button>

{/* External link */}
<Button href="https://kuoni.co.uk" target="_blank" variant="ghost">
  Visit kuoni.co.uk
</Button>

Content guidelines

Good button copy is invisible — the user reads it once and immediately knows what to do. Bad copy creates pause and doubt.

Lead with a verb

The label must start with an action word that names the outcome.

Be specific

Prefer the specific over the generic. Generic labels transfer the cognitive work of understanding the outcome onto the user.

Keep it short

One to four words is almost always enough. When the label is longer than five words, the hierarchy is wrong — the button is being asked to do too much.

Use sentence case

"Book now", not "Book Now". Only proper nouns are capitalised.

Omit unnecessary articles

"Add luggage", not "Add a luggage item".

Best practices

Rules below apply across every variant — they aren't specific to Primary, Secondary, Ghost or Danger. Variant-specific guidance lives with each variant in Variants, and grouping-combination guidance lives in Button groups.

Props

Accessibility

Keyboard interaction

Note for href buttons: When rendered as an <a> tag, only Enter activates the link — Space scrolls the page. If keyboard users must activate with Space, use a <button> instead and handle navigation in onClick.

Focus ring

All variants show a 2 px ring with 2 px offset on :focus-visible. This selector fires only for keyboard (and sequential) focus, not for mouse clicks — avoiding the distracting ring for pointer users while keeping it visible for keyboard users. The ring colour is chosen per variant to ensure 3:1 contrast against the page background:

disabled vs aria-disabled

{/* Native disabled — removed from tab order, no events fire */}
<Button disabled>Not available</Button>

{/* aria-disabled — stays focusable, announces as disabled, click fires
    but you suppress the action in onClick */}
<Button
  aria-disabled
  onClick={(e) => {
    if (e.currentTarget.getAttribute('aria-disabled')) {
      e.preventDefault();
      showTooltip('Complete your details to continue');
    }
  }}
>
  Continue
</Button>

Use aria-disabled when you want users to discover the button exists and understand why it is temporarily inactive. A tooltip or inline message should explain what they need to do to enable it. See States → Disabled for the underlying product decision on when to disable at all.

Loading state announcements

When loading becomes true, a visually-hidden string is injected into the button. Screen readers re-announce the button label including this text when focus remains on the button. Because the visual label does not change, sighted users see the spinner instead.

{/* aria output while loading:
    "Checking availability — Loading, please wait, button" */}
<Button loading loadingLabel="Loading, please wait">
  Checking availability
</Button>

For long operations, also use aria-live on a status region elsewhere in the page to announce completion.

Icon-only buttons

Every button with no visible text must have an aria-label. Without it, screen readers announce only the button role with no name — the worst possible experience for non-sighted users.

{/* ✅ Correct */}
<Button
  variant="ghost"
  aria-label="Add to wishlist"
  iconLeft={<Heart size={16} />}
/>

{/* ❌ Incorrect — screen reader announces "button" with no name */}
<Button variant="ghost" iconLeft={<Heart size={16} />} />

Colour contrast

Related components

• Link — use instead of Button whenever the action is navigation to a URL rather than a state change. Button itself can render as a link (href prop) when it needs to look like a button while behaving like one.
• Button groups are a layout pattern documented above (Button groups), not a separate component — there is no standalone ButtonGroup in the library; compose multiple Button instances with a flex container and gap-3.