+ Buttons are used for actions such as saving, submitting, progressing a + workflow, opening a dialog, changing a mode, or performing an operation on + data. +
+ ++ In DiamondDS, buttons should feel calm, predictable, and intentional. They + should help users understand what action is available, what matters most, and + what will happen next. +
+ ++ The main action should be easy to find. Supporting actions should remain + available without competing with it. Alternative actions or modes can use the + secondary intent when they represent a distinct path or interaction state. +
+ +## Use buttons when + +primary contained for the main action.primary outlined for supporting actions.secondary only for distinct alternative actions or modes.error for destructive or risky actions.secondary to mean “second most important”.| Type | +Meaning | +Recommended style | +
|---|---|---|
| Main action | ++ The action users are expected to take now. This should be the clearest + action in the view, section, dialog, or workflow step. + | +
+ primary contained
+ |
+
| Secondary action | ++ A supporting action in the same workflow. It is useful, but should have + less visual weight than the main action. + | +
+ primary outlined
+ |
+
| Alternative action or mode | ++ A distinct action family, path, or interaction mode. This is not just a + lower-priority action. + | +
+ secondary outlined by default;
+ secondary contained when active or strongly emphasised
+ |
+
| Destructive action | ++ A risky, destructive, or irreversible action, such as delete, clear, or + abort. + | +
+ error outlined or error text by default;
+ error contained only when the destructive action is the
+ main confirmed action
+ |
+
+ Use primary contained for the main action in a view, section,
+ dialog, or workflow step.
+
+ If multiple actions look equally primary, users lose clarity on what to do + next. +
+ + + +## Secondary actions + ++ Secondary actions support the main action within the same workflow. They + should remain visible and available, but they should not compete with the main + action. +
+ +
+ Use primary outlined for secondary actions. This keeps the action
+ connected to the main workflow while giving it less visual weight.
+
+ Do not use secondary colour just because an action is less
+ important. In DiamondDS, secondary means a different intent,
+ path, or mode.
+
+ Alternative actions often represent a different workflow, interaction mode, or + action family rather than a supporting action within the current workflow. +
+ +
+ When an alternative action is available but inactive, use
+ secondary outlined. When the alternative mode becomes active,
+ secondary contained can be used to communicate its active state.
+
+ As workflows progress, the main action may change. A primary contained action + may become a primary outlined action when it acts as a response to an active + process rather than the main action used to begin it. +
+ + + +### Same-weight alternatives + ++ When two alternative actions should carry similar visual weight, use outlined + buttons rather than two contained buttons. +
+ + + +### Active alternative mode + ++ When an alternative mode is active, a secondary contained button can be used + to communicate that state. The primary action may become outlined when it + represents a response to an active process rather than the action used to + start it. +
+ ++ This pattern allows users to understand both the current mode and the actions + available to leave, stop, or change it. +
+ + + +### Active primary and alternative actions + +
+ A primary contained button can appear alongside a
+ secondary contained button when their roles are clearly
+ different: one represents the main action, while the other represents an
+ active alternative mode.
+
+ Avoid this pairing when the buttons represent competing choices or when both + appear to be primary actions. +
+ + + +## Destructive actions + +
+ Use error styling for actions that are destructive, risky, or
+ irreversible.
+
error for destructive actions such as delete, abort, or
+ clear.
+ error outlined or error text by default.
+ error contained only when the destructive action is the
+ main confirmed action, such as in a confirmation dialog.
+ When multiple buttons appear together, use hierarchy first, then intent.
+ +primary contained for the main action.
+ primary outlined for supporting actions in the same
+ workflow.
+ secondary outlined for distinct alternative paths or modes.
+ secondary contained only when the secondary intent is
+ active or clearly emphasised.
+ + In most cases, prefer one contained button per decision area. More than one + contained button is acceptable only when the buttons do not compete for the + same meaning. +
+ +## State and emphasis + +| Variant | +Emphasis | +Use for | +
|---|---|---|
+ contained
+ |
+ High | +Main actions, active modes, or confirmed high-emphasis actions. | +
+ outlined
+ |
+ Medium | ++ Supporting actions, available alternative modes, and actions near a main + action. + | +
+ text
+ |
+ Low | +Inline, optional, or low-priority actions. | +
+ Use emphasis to guide decisions. Use colour only when it communicates intent. +
+ +## State priority + +| State | +Purpose | +Priority | +
|---|---|---|
| Disabled | +Shows that interaction is unavailable. | +Highest | +
| Error | +Shows that an action is risky, destructive, or has failed. | +High | +
| Active | +Shows that a mode or toggle-like action is currently on. | +High | +
| Focus | +Shows keyboard position. | +High | +
| Hover | +Shows pointer interaction. | +Low | +
+ Disabled and error states should always win over active, hover, focus, or + selected states. +
+ +## Token guidance + +| Need | +Prefer | +Avoid | +
|---|---|---|
| Main actions | +
+ primary
+ |
+ Raw brand hex values | +
| Alternative actions or modes | +
+ secondary
+ |
+ Using secondary as decoration or “less important primary” | +
| Destructive actions | +
+ error mapped from danger tokens
+ |
+ Custom red values | +
| Button text | +
+ contrastText, onSolid, semantic foreground
+ tokens
+ |
+ Hardcoded white or black text | +
| Outlined border | +
+ border.subtle, border.emphasis
+ |
+ Hardcoded grey borders | +
| Hover state | +
+ action.hover, overlay.hover
+ |
+ One-off hover colours | +
| Focus state | +
+ theme.focusRing, semantic focus tokens
+ |
+ Browser default focus only | +
+ Button labels should describe the action clearly. Avoid vague labels such as + “OK” or “Submit” when a more specific label would help users understand the + result. +
+ +Button — used for actions in forms, dialogs, toolbars, and
+ workflows.
+ IconButton — used for compact icon-only actions.
+ ButtonGroup — groups related button actions.
+ ToggleButton — used for selectable or persistent action states.
+