Button Open in Figma
Buttons are essential components in user interfaces, acting as gateways for interaction. They come in various styles, each serving a distinct purpose. Consistency in hierarchy helps guide users through their journey, ensuring that they can easily identify the most important actions to take.
pivot-button is a flexible action component that renders either a <button> or an <a> element depending on whether pivot-href is set. It supports three visual variants (primary, secondary, tertiary), an inverse color scheme for use on dark backgrounds, a destructive modifier for dangerous actions, and a disabled state.
Quick Start
<!-- Default primary button -->
<pivot-button>Submit</pivot-button>
<!-- Secondary button -->
<pivot-button pivot-variant="secondary">Cancel</pivot-button>
<!-- Tertiary button with destructive styling -->
<pivot-button pivot-variant="tertiary" pivot-destructive>Delete</pivot-button>
<!-- Link button (renders as <a>) -->
<pivot-button pivot-href="/dashboard">Go to Dashboard</pivot-button>
<!-- Disabled button -->
<pivot-button pivot-disabled>Unavailable</pivot-button>Rendering Behavior
pivot-button switches its inner element based on context:
- No
pivot-href→ renders a<button>element. Use for actions (submit, open dialog, trigger function). - With
pivot-href→ renders an<a>element. Use for navigation.
<!-- Renders <button type="button"> -->
<pivot-button pivot-variant="primary">Save</pivot-button>
<!-- Renders <a href="/profile"> -->
<pivot-button pivot-variant="primary" pivot-href="/profile"
>View Profile</pivot-button
>
<!-- Form submit button -->
<pivot-button pivot-type="submit">Submit Form</pivot-button>Choosing the correct form matters for semantics: <button> triggers actions; <a> navigates. Do not use pivot-href when the intent is an action.
Note:
pivot-disabledsets thedisabledattribute on the inner<button>only. It has no effect whenpivot-hrefis set, becausedisabledis not a valid attribute on<a>elements — see Disabled State below.
Variant and Modifier Combinations
Variants and modifiers can be combined freely:
<!-- Inverse — for dark backgrounds -->
<pivot-button pivot-variant="primary" pivot-inverse
>Primary Inverse</pivot-button
>
<pivot-button pivot-variant="secondary" pivot-inverse
>Secondary Inverse</pivot-button
>
<!-- Destructive -->
<pivot-button pivot-variant="primary" pivot-destructive
>Delete Account</pivot-button
>
<pivot-button pivot-variant="secondary" pivot-destructive>Remove</pivot-button>
<!-- Inverse + Destructive -->
<pivot-button pivot-variant="primary" pivot-inverse pivot-destructive
>Delete (dark bg)</pivot-button
>With Icons
Place icon elements directly inside the default slot. Icons are styled automatically to match button token sizes (--typography-constants-icon-family, --typography-icon-sm-size).
<!-- Leading icon -->
<pivot-button pivot-variant="primary">
<i class="fa-solid fa-plus"></i> Add Item
</pivot-button>
<!-- Trailing icon -->
<pivot-button pivot-variant="secondary">
Download <i class="fa-solid fa-arrow-down"></i>
</pivot-button>Icons slotted into pivot-button are decorative when accompanied by visible label text and should be hidden from assistive technology:
<pivot-button pivot-variant="primary">
<i class="fa-solid fa-check" aria-hidden="true"></i> Confirm
</pivot-button>If the button has no visible text label (icon-only), provide an accessible name via aria-label on the host element:
<pivot-button pivot-variant="tertiary" aria-label="Close dialog">
<i class="fa-solid fa-xmark"></i>
</pivot-button>Form Participation
pivot-button is a form-associated custom element (static formAssociated = true plus attachInternals()), which gives it access to the ancestor <form> via ElementInternals.form — even though the native <button> it renders lives inside its own shadow root, not inside the <form> itself.
pivot-type="submit"submits that ancestor form when clicked, via a temporary submitter proxy (see below). This runs the browser’s native constraint validation (unless the form haspivot-no-validateset) before submitting — see Form Container’s Validation Behavior.pivot-type="reset"callsform.reset(), restoring every form-associated control inside the form to its initial value.pivot-type="button"andpivot-type="menu"do nothing form-related — only the element’s own nativeclickevent fires.- If there is no ancestor
<form>(apivot-buttonused outside any form),pivot-type="submit"/"reset"are no-ops.
<pivot-form-container pivot-action="/submit">
<pivot-input pivot-name="email" pivot-label="Email"></pivot-input>
<pivot-button pivot-type="submit">Submit</pivot-button>
<pivot-button pivot-variant="secondary" pivot-type="reset"
>Reset</pivot-button
>
</pivot-form-container>Disabled state and an ancestor <fieldset>
Because pivot-button is form-associated, formDisabledCallback runs automatically when an ancestor <fieldset disabled> (or a disabled form) contains it, setting pivotDisabled to match — mirroring native <button> behavior. This is in addition to setting pivot-disabled directly.
How pivot-name/pivot-value reach the submitted form
A form-associated custom element like pivot-button cannot itself be passed to requestSubmit() as a submitter — per the HTML spec, only a native <button type="submit">/<input type="submit"|"image"> qualifies, and passing an arbitrary custom element throws a TypeError. The real native <button> pivot-button renders isn’t eligible either, since it lives inside pivot-button’s own shadow root and is never a descendant of the outer <form>.
To work around this, handleClick() builds a temporary, hidden native <button type="submit">, copies pivot-name/pivot-value onto it, and inserts it as a light-DOM sibling immediately after pivot-button itself — making it a genuine descendant of the form and a valid submitter. It’s passed to form.requestSubmit(proxy) and removed immediately afterward; validation, the submit event, and any pivot-method="dialog" side effects all happen synchronously within that call, so nothing depends on the proxy still being in the DOM once it returns. This proxy is purely internal plumbing — it’s never visible, never independently focusable, and the element the user actually sees and interacts with remains pivot-button’s own shadow-DOM <button>.
The practical effect: pivot-name/pivot-value are included in the submitted FormData exactly as they would be for a native <button type="submit" name="…" value="…">, and for pivot-method="dialog" forms, dialog.returnValue correctly reflects the pivot-value of whichever button was clicked — see Form Container’s pivot-method="dialog" example.
Because the proxy is inserted at pivot-button’s own position rather than appended to the end of the form, relative DOM order between multiple submit buttons is preserved — this is also what the browser uses to pick the form’s implicit “default button” when a user presses Enter in a text field, so behavior matches a native form with multiple submit buttons.
Accessibility
Screen Reader Behavior
pivot-button does not add an ARIA role of its own — the accessible role comes entirely from the inner element it renders. With no pivot-href, the inner <button> is announced as a button; with pivot-href set, the inner <a> is announced as a link. Use <pivot-button> (no pivot-href) for actions and <pivot-button pivot-href="..."> for navigation — this distinction is critical, since using the wrong element misleads screen reader users about what will happen when they activate it (WCAG 2.2 4.1.2 Name, Role, Value).
Disabled State
pivot-disabled sets the disabled attribute on the inner <button>, which removes it from the tab order and prevents activation; screen readers announce it as “dimmed” or “unavailable”. pivot-disabled has no semantic effect when combined with pivot-href, because disabled is not a valid attribute on <a> elements — the link remains focusable and clickable. To disable a link button, avoid pivot-href and handle navigation conditionally in application code, or omit the link entirely.
pivotDisabled can also be set indirectly, not just via the pivot-disabled attribute — see Form Participation’s Disabled state for how an ancestor disabled <fieldset> triggers the same state automatically.
Keyboard Navigation
| Key | Behavior |
|---|---|
Tab |
Moves focus to the button |
Enter |
Activates both <button> and <a> elements |
Space |
Activates <button> elements only |
This matches native <button>/<a> behavior; pivot-button adds no custom key handling of its own (WCAG 2.2 2.1.1 Keyboard).
Focus Management
PivotBase sets delegatesFocus: true on the shadow root, so the inner <button> or <a> receives focus directly — there is no wrapper element in the focus path, and no .focus()/.blur() methods are exposed on the component itself. The native :focus outline is preserved (outline-offset: 4px), keeping focus visible per WCAG 2.2 2.4.7 Focus Visible.
References
- ARIA Authoring Practices Guide — Button Pattern
- MDN —
<button>: The Button element - MDN —
<a>: The Anchor element - WCAG 2.2 — Name, Role, Value (4.1.2)
- WCAG 2.2 — Keyboard (2.1.1)
- WCAG 2.2 — Focus Visible (2.4.7)
API Reference
Props
| Name | Type | Default | Description |
|---|---|---|---|
pivot-variant |
"primary" | "secondary" | "tertiary" |
"primary" |
The button variant style. Allowed values: "primary", "secondary", "tertiary". |
pivot-href |
string |
"" |
This will create an attribute: href="value" |
pivot-target |
"_blank" | "_self" | "_parent" | "_top" | string | null |
null |
This will create an attribute: target="value" |
pivot-name |
string | null |
null |
This will create an attribute: name="value" |
pivot-value |
string | null |
null |
This will create an attribute: value="value" |
pivot-type |
"button" | "submit" | "reset" | "menu" | null |
null |
The button type attribute. Allowed values: "button", "submit", "reset", "menu". |
pivot-disabled |
boolean |
false |
Presence of attribute means true: <pivot-button pivot-disabled> |
pivot-inverse |
boolean |
false |
Button inverse styling. Presence of attribute means true: <pivot-button pivot-inverse> |
pivot-destructive |
boolean |
false |
Button destructive styling. Presence of attribute means true: <pivot-button pivot-destructive> |
Slots
| Name | Description |
|---|---|
default |
Default slot for the button label and optional icon(s) |
CSS Custom Properties
| Name | Description |
|---|---|
--component-button-gap |
Gap between icon and label content. |
--component-button-constants-inset-y |
Vertical padding of the button. |
--component-button-constants-inset-x |
Horizontal padding of the button. |
--typography-private-interactive-family |
Font family used for the button label. |
--typography-private-interactive-button-size |
Font size used for the button label. |
--button-border-style |
Border style of the button. Default: solid. |
--component-button-constants-border |
Border width of the button. |
--component-button-constants-radius |
Border radius of the button. |
--typography-constants-icon-family |
Font family applied to slotted `<i>`/`<svg>` icons. |
--typography-icon-sm-size |
Font size applied to slotted `<i>`/`<svg>` icons. |
--component-button-primary-default-surface |
Background and border color for the primary variant. |
--component-button-primary-default-label |
Text color for the primary variant. |
--component-button-primary-default-destructive-surface |
Background and border color for the primary variant with `pivot-destructive`. |
--component-button-primary-default-destructive-label |
Text color for the primary variant with `pivot-destructive`. |
--component-button-primary-inverse-default-surface |
Background and border color for the primary variant with `pivot-inverse`. |
--component-button-primary-inverse-default-label |
Text color for the primary variant with `pivot-inverse`. |
--component-button-primary-inverse-default-destructive-surface |
Background and border color for the primary variant with `pivot-inverse` and `pivot-destructive`. |
--component-button-primary-inverse-default-destructive-label |
Text color for the primary variant with `pivot-inverse` and `pivot-destructive`. |
--component-button-secondary-default-surface |
Background color for the secondary variant. |
--component-button-secondary-default-label |
Text color for the secondary variant. |
--component-button-secondary-default-border-color |
Border color for the secondary variant. |
--component-button-secondary-default-destructive-surface |
Background color for the secondary variant with `pivot-destructive`. |
--component-button-secondary-default-destructive-label |
Text color for the secondary variant with `pivot-destructive`. |
--component-button-secondary-default-destructive-border-color |
Border color for the secondary variant with `pivot-destructive`. |
--component-button-color |
Hover, focus, and active mix color for the secondary and tertiary variants. |
--component-button-secondary-inverse-default-surface |
Background color for the secondary variant with `pivot-inverse`. |
--component-button-secondary-inverse-default-label |
Text color for the secondary variant with `pivot-inverse`. |
--component-button-secondary-inverse-default-border-color |
Border color for the secondary variant with `pivot-inverse` (also used when `pivot-destructive` is combined with `pivot-inverse`). |
--component-button-secondary-inverse-default-destructive-label |
Text color for the secondary variant with `pivot-inverse` and `pivot-destructive`. |
--component-button-secondary-inverse-default-destructive-border-color |
Border color for the secondary variant with `pivot-inverse` and `pivot-destructive`. |
--component-button-tertiary-default-surface |
Background color for the tertiary variant (also used with `pivot-destructive`). |
--component-button-tertiary-default-label |
Text color for the tertiary variant. |
--component-button-tertiary-default-destructive-label |
Text color for the tertiary variant with `pivot-destructive`. |
--component-button-tertiary-inverse-default-surface |
Background color for the tertiary variant with `pivot-inverse` (also used with `pivot-destructive` combined). |
--component-button-tertiary-inverse-default-label |
Text color for the tertiary variant with `pivot-inverse`. |
--component-button-tertiary-inverse-default-destructive-label |
Text color for the tertiary variant with `pivot-inverse` and `pivot-destructive`. |
--component-button-tertiary-disabled-label |
Text color when `pivot-disabled` is set. |
--component-button-tertiary-disabled-surface |
Background color when `pivot-disabled` is set. |
--component-button-primary-inverse-disabled-label |
Text color when `pivot-disabled` and `pivot-inverse` are both set. |
--component-button-primary-inverse-disabled-surface |
Background color when `pivot-disabled` and `pivot-inverse` are both set. |
Button
Buttons are essential components in user interfaces, acting as gateways for interaction. They come in various styles, each serving a distinct purpose. Consistency in hierarchy helps guide users through their journey, ensuring that they can easily identify the most important actions to take.
Label
Label
Label
Usage
Buttons are the primary method by which users navigate and interact within pages and apps. Because it is very easy for anybody to just ‘add a button’ to satisfy a story or feature the correct usage of buttons, their constraints and guidelines must be carefully considered.
Primary use cases
3 button styles are provided to offer nuance within the page’s design. A common pattern is to reserve the primary button for the page’s single call to action. Secondary and Tertiary styles then can be used for decreasingly important prompts.
When to use
- Pointing users to KPI features like “Apply Now” or “Download”
- Verbs like:
- Submitting information
- Moving forward or backwards through a flow
- Confirming and canceling actions
When not to use
- Navigating to an anchor tag within the current page (use a link instead)
- Navigating to non-application pages
Do’s and Don’ts
Follow these guidelines to ensure consistent, accessible, and user-friendly implementation of this [component/pattern/foundation].

✅ Do
ONLY USE ONE PRIMARY CTA PER PAGE

✅ Do
Use sentence case for all labels but capitalize proper nouns.

✅ Do
Keep label length to a minimum.

✅ Do
Keep icon use consistent between button instances. All button instances type should have the same icon across the entire site.

✅ Do
Keep leading and trailing icon use consistent. Leading icons should be used at the start of prominent actions and trailing icons are usually reserved for navigational context.

⚠️ Caution
Match button widths when possible. A significantly longer label can drive more attention than the button style should command.
Apply for Financing
square-dollar
Learn more
lightbulb-on
❌ Don’t
Don’t force an atypical or unintuitive icon. Icons should only be used for ‘common’ actions like downloading, adding or to add some directionality.
Download PDF
Learn more
🥺
😭
❌ DON’T
YOU DARE USE MORE THAN ONE PRIMARY BUTTON AT A TIME
AEM Authoring Guideance
Search all the previous QA items sent to marketing team regarding this component and paste them here. This section might just be text and screenshots.
To implement this component:
- Instructions
- Instructions
- Instructions
Variants (styles in AEM - for authors)
This component includes the following variants for authors in AEM
Type
- Primary
- Primary Inverse
- Secondary
- Secondary Inverse
- Tertiary
- Tertiary Invese
Icon
- None
- Icon Leading
- Icon Following
Design Considerations
- Only use the inverse state on dark marketing surfaces
Notes
- We may want to document a standard list of system icons and blanket ban the use of off list ones for buttons…
Design Tokens Used
Variables Name Applied as Applied to
Pivot Tokens/
component/button/constants/buttonPaddingH
Padding left
button
Pivot Tokens/
component/button/constants/buttonPaddingH
Padding right
button
Pivot Tokens/
component/button/constants/buttonPaddingV
Padding bottom
button
Pivot Tokens/
component/button/constants/buttonPaddingV
Padding top
button
Pivot Tokens/
component/button/constants/buttonRadius
Border radius
button
Pivot Tokens/
component/button/constants/buttonSpacingIntra
Item spacing
button
Pivot Tokens/
component/button/constants/buttonStroke
Border weight
button
Pivot Tokens/
component/button/primary inverse/default/buttonPrimaryInverseDefaultLabel
Text color
Label
Pivot Tokens/
component/button/primary inverse/default/buttonPrimaryInverseDefaultSurface
Background color
button
Pivot Tokens/
component/button/primary/default/buttonPrimaryDefaultLabel
Text color
Label (3),
✳️ Icon
Pivot Tokens/
component/button/primary/default/buttonPrimaryDefaultSurface
Background color
button (3)
Pivot Tokens/
component/button/primary/disabled/buttonPrimaryDisabledLabel
Text color
Label
Pivot Tokens/
component/button/primary/disabled/buttonPrimaryDisabledSurface
Background color
button
Pivot Tokens/
component/button/secondary/default/buttonSecondaryDefaultLabel
Text color
Label
Pivot Tokens/
component/button/secondary/default/buttonSecondaryDefaultStroke
Border color
button
Pivot Tokens/
component/button/secondary/default/buttonSecondaryDefaultSurface
Background color
button
Pivot Tokens/
component/button/tertiary/default/buttonTertiaryDefaultLabel
Text color
Label
Pivot Tokens/
component/button/tertiary/default/buttonTertiaryDefaultSurface
Background color
button
Pivot Tokens/
global/interaction sizes/md
Min height
button
Text styles Name Applied as Applied to
icon/icon-sm-solid
Text style
✳️ Icon
private/interactive/button
Text style
Label
Status & Changelog
This component is designed to support a wide range of user types, from end users interacting with an interface to internal users managing or configuring systems. It is commonly used by:
[check our pivot file for decisions documented there and check our decision log page. Add them chronologically, latest one on top]
Date
Olivia Rhye
2025-8-8
Olivia Rhye
Members
Olivia Rhye
DST: Michael K., Lauren M., Dan R., Dan O., Chloe P., Melissa W.
Olivia Rhye
Description
Olivia Rhye
Initial setup
Olivia Rhye
All variants — light surface
<pivot-button pivot-variant="primary">Primary</pivot-button>
<pivot-button pivot-variant="secondary">Secondary</pivot-button>
<pivot-button pivot-variant="tertiary">Tertiary</pivot-button>All variants — dark surface (pivot-inverse)
<pivot-button pivot-variant="primary" pivot-inverse>Primary</pivot-button>
<pivot-button pivot-variant="secondary" pivot-inverse>Secondary</pivot-button>
<pivot-button pivot-variant="tertiary" pivot-inverse>Tertiary</pivot-button>Destructive — light surface
<pivot-button pivot-variant="primary" pivot-destructive
>Primary Destructive</pivot-button
>
<pivot-button pivot-variant="secondary" pivot-destructive
>Secondary Destructive</pivot-button
>
<pivot-button pivot-variant="tertiary" pivot-destructive
>Tertiary Destructive</pivot-button
>Destructive — dark surface (pivot-inverse + pivot-destructive)
<pivot-button pivot-variant="primary" pivot-inverse pivot-destructive
>Primary Destructive</pivot-button
>
<pivot-button pivot-variant="secondary" pivot-inverse pivot-destructive
>Secondary Destructive</pivot-button
>
<pivot-button pivot-variant="tertiary" pivot-inverse pivot-destructive
>Tertiary Destructive</pivot-button
>With icons
<pivot-button pivot-variant="primary"
><i class="fa-solid fa-plus" aria-hidden="true"></i> Add Item
</pivot-button>
<pivot-button pivot-variant="primary">
Download <i class="fa-solid fa-download" aria-hidden="true"></i
></pivot-button>
<pivot-button pivot-variant="secondary"
><i class="fa-solid fa-pencil" aria-hidden="true"></i> Edit
</pivot-button>
<pivot-button pivot-variant="tertiary"
><i class="fa-solid fa-angle-left" aria-hidden="true"></i> Back
</pivot-button>
<pivot-button pivot-variant="tertiary" aria-label="Close dialog">
<i class="fa-solid fa-xmark"></i
></pivot-button>Link rendering (pivot-href)
Setting pivot-href renders the component as an <a> element instead of a <button>. Use this form for navigation, not actions — pivot-target (mapped to the anchor’s target attribute) only has an effect in this mode.
<pivot-button pivot-variant="primary" pivot-href="https://example.com"
>Primary Link</pivot-button
>
<pivot-button pivot-variant="secondary" pivot-href="https://example.com"
>Secondary Link</pivot-button
>
<pivot-button
pivot-variant="tertiary"
pivot-href="https://example.com"
pivot-target="_blank"
>Tertiary Link (new tab)</pivot-button
>Disabled — light surface
<pivot-button pivot-disabled>Disabled</pivot-button>Disabled — dark surface (pivot-inverse)
<pivot-button pivot-disabled pivot-inverse>Disabled Inverse</pivot-button>Form button types (pivot-type)
<pivot-button pivot-variant="primary" pivot-type="submit">Submit</pivot-button>
<pivot-button pivot-variant="secondary" pivot-type="reset">Reset</pivot-button>
<pivot-button pivot-variant="tertiary" pivot-type="button">Button</pivot-button>