# Button

Primary trigger for a specific action or form submission. Use "Primary" for the main task, "Secondary" for alternative actions, and "Ghost/Tertiary" for low-priority tasks.

Primary: "Use as the single most important action on a screen. Limit to one per view (e.g., 'Submit', 'Pay Now')."
Secondary: "Use for supporting actions that are not the main goal of the page (e.g., 'Cancel', 'Back')."
Tertiary/Ghost: "Use for low-emphasis actions or repeated items in a list (e.g., 'View Details', 'Learn More')."
Critical: "Use specifically for actions that result in data loss or permanent changes. Usually styled in Red."

import Anatomy from "../../../../../components/Anatomy.astro";
import VariantMatrix from "../../../../../components/VariantMatrix.astro";
import MotionPattern from "../../../../../components/MotionPattern.astro";
import AccessibilityRefs from "../../../../../components/AccessibilityRefs.astro";
import PageMetadata from "../../../../../components/PageMetadata.astro";
import StubFooter from "../../../../../components/StubFooter.astro";
import DoDont from "../../../../../components/DoDont.astro";
import Callout from "../../../../../components/Callout.astro";
import TermList from "../../../../../components/TermList.astro";
import ComponentTabs from "../../../../../components/ComponentTabs.astro";
import ConfidenceChip from "../../../../../components/ConfidenceChip.astro";
import MediaAsset from "../../../../../components/MediaAsset.astro";

<PageMetadata
  slug="components.button.content"
  source="components/dist/registries/dskit.json#button"
  schema={1}
  updated="2026-05-14"
/>

<ComponentTabs component={"button"} activeTab={"content"} />

## Content guidelines

Buttons trigger actions. They are the primary mechanism for users to submit forms, confirm choices, navigate, and initiate processes within the platform.

### When to use

- Use buttons for actions, not navigation. For navigation, use [links](/components/action/link/).
- Use a primary button for the main action on a page or modal.
- Use secondary buttons for alternative or less critical actions.
- Use ghost or tertiary buttons for low-priority or destructive actions that should not draw immediate attention.

### Style

- Use sentence case for all button labels.
- Use the verb + object formula whenever possible (for example, **Create report**, **Delete dataset**).
- Keep labels concise - ideally two to four words.
- Do not end button labels with punctuation.
- Do not use articles (a, an, the) in button labels unless necessary for clarity.

### Behavior

- Disable the primary button until all required fields are complete.
- Show a loading indicator on the button when an action is in progress.
- Return focus to the triggering element after a modal or dialog closes.

### Do / Don't

<DoDont pairs={[{ do: "Create report", dont: "Report" }, { do: "Delete dataset", dont: "Delete" }, { do: "Add connection", dont: "Add a connection" }, { do: "Save changes", dont: "Save Changes" }]} />

### Terminology for button labeling

Use the following term pairs consistently across the platform. Choosing the wrong term creates confusion when the same action appears under different labels in different contexts.

<TermList items={[{ term: "Cancel vs Close", definition: "Use **Cancel** when the user is backing out of a page or modal where information has been entered or a confirmation is required. Cancel returns the user to the previous state without saving. Use **Close** for read-only messages or screens." }, { term: "Create vs Add vs Insert", definition: "Use **Create** when the user is making something brand new. Use **Add** when bringing in similar information that already exists elsewhere. Use **Insert** when bringing in similar information and the ordering is important. The plus (+) icon is only needed when creating a new object to add to something else. When adding an existing object to a list, the icon is not needed." }, { term: "OK", definition: "Use **OK** for read-only pages that are not legally required to be accepted." }, { term: "Accept vs Decline", definition: "Use **Accept** when legal terms of service need to be acknowledged before the user can proceed. **Accept** can also be paired with **Decline** when the user must choose whether to implement proposed changes from someone else or from AI." }, { term: "Got it!", definition: "Use **Got it!** when providing information confirmation modals where the user does not have to take any action." }, { term: "Select vs Choose", definition: "Use **Select** when the user is picking from a list with limited options. Use **Choose** when the user is picking from a large number of options or making an open-ended decision." }, { term: "Submit vs Send vs Save", definition: "Use **Submit** for a form. Use **Send** only for email. Use **Save** when the user is adding or changing selections on a modal." }, { term: "View vs See", definition: "Use **View** as a noun (for example, **Table view**). Use **See** as a verb, but only with a modifier (for example, **See more**)." }, { term: "Stepper buttons", definition: "Use verb + object for the creation button. With few exceptions, the verb should be **Create**. Use only the verb (without the object) when finishing a stepper (for example, **Create** not **Create integration**). In modals and steppers, the initial button and the final button should use the same term in most cases. Exceptions include using **Save** on the final step of a wizard." }]} />