ACE: Buttons

Design

Resting	Disabled	Comment
		The simple button can be used in different contexts: in the tool bar to access primary actions (Ask question), in the footer of a form or dialog to confirm and submit the inputs (OK), and within forms to access additional functionality (Browse).
		The caution button is used to confirm actions that are high risk.
		Loading buttons show a loading state to indicate something is happening (click for a demo).
		Buttons can include both icons and text.
		Buttons can include both icons in multiple positions
		Buttons can be icon-only.
		The subtle button is used where an action that is often not the focus of the page - it has a subtle design that provides a lower weight in the resting state's visual hierarchy.
		The mimimal button is used for inline actions, where a subtle button would be too much - minimal buttons have tighter spacing. Minimal buttons are used almost exclusively with an icon and no text.
		Link buttons match the text link style.
		Link buttons may include icons.

Button text and icons

Most buttons use visible text, which is a verb for actions or a noun when triggering further controls (eg. launching a Dropdown). Some buttons use text and an icon; some use just the icon. In all cases, real text must be supplied in the HTML so all designs should specify the alternate text for icon-only buttons.

'Close' buttons have particular usage: when the Close button is the only button in its context, the full visible text 'Close' should be used:

When the Close button is accompanied by other buttons, it must appear last in the set and simply use the Close icon:

Button placement

When buttons appear in a Dialog footer; or immediatley after a Message, Table or Expander; they should be centre-aligned.

In forms, button placement varies:

When they appear after a multiple-group form they are centre-aligned
When they appear within a section they are aligned to an indent matching the left edge of form inputs
Inline buttons are placed adjacent to the right of the related input, with a grid unit of horizontal space
Inline button spacing is reduced for edit in place scenarios, where space is at a premium

Button groups

There are two types of button group, combined and separate. Combined groups are for buttons which directly relate to each other, to the extent that they are part of one overall choice or action. Separate groups keep the individual buttons separate, as their actions are not directly related.

The default type is the Combined button group, which creates a set of related buttons in a combined style:

Separate button groups are a simple wrapper for buttons, keeping the buttons themselves separate:

Separate button groups often aren't necessary if the buttons are already contained in another element, for example within a Header actions item.

Pressed buttons

Pressed buttons can be used in combined groups to indicate interactions such as choosing filters. In most cases, only one button in the group will be pressed at a time:

Note this is not the same as the Toggle control which toggles between two mutually-exclusive named states. Nor are Pressed Buttons the same as Tabs, which load different pages or sets of content.

Pressed buttons must be actions that control something in the current view, they should not take the user to a different view entirely.

Dimensions

In the majority of cases, the default button size is the right thing to use. In some cases it is necessary to override this by manually setting dimensions.

Buttons can be set to four sizes, with a minimum width for each that will scale horizontally to allow for internationalisation. While there are larger button sizes all care must be taken to craft a concise button label.

Example	Width (pixels)	Comment
	31	Used for displaying a familiar action that can be represented by a single icon.
	80	The most commonly used button size.
	140	Useful when more information is needed to convey the action.
	200	Useful when more information is needed to convey the action.

Code

Example	Element	Code
	Default button.	HTML Classic ASP `<button class="ace-button" type="button"><span>Default</span></button>` `<% ace.Button(Array("text", "Default")) %>`
	Caution button.	HTML Classic ASP `<button class="ace-button ace-button-caution" type="button"><span>Caution</span></button>` `<% ace.Button(Array(_ "text", "Caution",_ "type", "caution"_ )) %>`
	Subtle button.	HTML Classic ASP `<button class="ace-button ace-button-subtle" type="button"><span>Subtle</span></button>` `<% ace.Button(Array(_ "text", "Subtle",_ "type", "subtle"_ )) %>`
	'Link buttons' are used when the design requires a link set next to a button; or for cases where the code requires a BUTTON element, but the design requires a link style.	HTML Classic ASP `<button class="ace-button ace-button-link" type="button"><span>Link</span></button>` `<% ace.Button(Array(_ "text", "Link",_ "type", "link"_ )) %>`
	Icons for link buttons are placed before the text rather than afterwards.	HTML Classic ASP `<button class="ace-button ace-button-link ace-button-icon" type="button"><span><span class="ace-icon ace-icon-control-arrowright"></span><span class="ace-text">Forgot password</span></span></button>` `<% ace.Button(Array(_ "text", "Forgot Password",_ "type", "link",_ "icon", "control-arrowright",_ "iconText", "cloud",_ "iconPosition", "first"_ )) %>`
	Buttons can include an icon. Note the icon can have additional alternate text if required; but don't set the same string for both.	HTML Classic ASP `<button class="ace-button ace-button-icon ace-button-icon" type="button"><span><span class="ace-text">Close</span><span class="ace-icon ace-icon-icon-close"></span></span></button>` `<% ace.Button(Array(_ "icon", "control-close",_ "text", "Close",_ "type", "icon"_ )) %>`
	Icon-only buttons have a modifier class and wrap an instance of ace-icon. Note there must always be descriptive text available within the button, so it is included within the icon.	HTML Classic ASP `<button class="ace-button ace-button-icon ace-button-icon" type="button"><span><span class="ace-icon ace-icon-control-close" title="Close">Close</span></span></button>` `<% ace.Button(Array(_ "icon", "control-close",_ "iconText", "Close",_ "type", "icon"_ )) %>`
	Icon-only subtle button.	HTML Classic ASP `<button class="ace-button ace-button-subtle ace-button-icon" type="button"><span><span class="ace-icon ace-icon-control-close" title="Close">Close</span></span></button>` `<% ace.Button(Array(_ "icon", "control-close",_ "iconText", "Close",_ "type", "subtle"_ )) %>`
	Setting button to collapsible makes the text hidden on small screens.	HTML Classic ASP `<button class="ace-button ace-button-subtle ace-button-icon ace-button-collapsible" type="button"><span><span class="ace-text">Close</span><span class="ace-icon ace-icon-control-close" title="Close">Close</span></span></button>` `<% ace.Button(Array(_ "text", "Close",_ "type", "default",_ "icon", "control-close",_ "iconText", "Close",_ "collapsible", "true"_ )) %>`
	Icon-only minimal button.	HTML Classic ASP `<button class="ace-button ace-button-minimal ace-button-icon" type="button"><span><span class="ace-icon ace-icon-control-closesmall" title="Close">Close</span></span></button>` `<% ace.Button(Array(_ "type", "minimal",_ "icon", "control-closesmall",_ "iconText", "Close"_ )) %>`
	To set a button to disabled style use the native disabled attribute in fully quoted form.	HTML Classic ASP `<button class="ace-button" disabled="disabled" type="button"><span>Disabled</span></button>` `<% ace.Button(Array(_ "text", "Disabled",_ "disabled", "disabled"_ )) %>`
		HTML Classic ASP `<button class="ace-button ace-button-caution" disabled="disabled" type="button"><span>Caution disabled</span></button>` `<% ace.Button(Array(_ "text", "Caution disabled",_ "type", "caution",_ "disabled", "disabled"_ )) %>`
	Sizes are set with modifier classes.	HTML Classic ASP `<button class="ace-button ace-button-small" type="button"><span>?</span></button>` `<% ace.Button(Array(_ "text", "?",_ "size", "small"_ )) %>`
		HTML Classic ASP `<button class="ace-button ace-button-medium" type="button"><span>Medium</span></button>` `<% ace.Button(Array(_ "text", "Medium",_ "size", "medium"_ )) %>`
		HTML Classic ASP `<button class="ace-button ace-button-large" type="button"><span>Large</span></button>` `<% ace.Button(Array(_ "text", "Large",_ "size", "large"_ )) %>`
		HTML Classic ASP `<button class="ace-button ace-button-xlarge" type="button"><span>Extra large</span></button>` `<% ace.Button(Array(_ "text", "Extra large",_ "size", "xlarge"_ )) %>`
	To fit a button into a contained area apply truncate. Hovering over the button should reveal full text in a tooltip.	HTML Classic ASP `<button class="ace-button ace-button-truncate" title="Very long text string" type="button"><span>Very long text string</span></button>` `<% ace.Button(Array(_ "text", "Very long text string",_ "truncate", "true"_ )) %>`
	Buttons can be grouped by adding the ace-button-group wrapper element.	HTML Classic ASP `<div class="ace-button-group"> <button class="ace-button" type="button"><span>Three</span></button> <button class="ace-button" type="button"><span>Related</span></button> <button class="ace-button" type="button"><span>Actions</span></button> </div>` `<% ace.ButtonGroup(Array()) ace.Button(Array("text", "Three")) ace.Button(Array("text", "Related")) ace.Button(Array("text", "Actions")) ace.ButtonGroupEnd %>`
	Buttons can be grouped but kept separate by adding the `ace-button-group` wrapper element with the additional class `ace-button-group-separate`.	HTML Classic ASP `<div class="ace-button-group ace-button-group-separate"> <button class="ace-button" type="button"><span>Bulk upload</span></button> <button class="ace-button" type="button"><span>Export to excel</span></button> <button class="ace-button" type="button"><span>Print</span></button> </div>` `<% ace.ButtonGroup(Array("type", "separate")) ace.Button(Array("text", "Bulk upload")) ace.Button(Array("text", "Export to excel")) ace.Button(Array("text", "Print")) ace.ButtonGroupEnd %>`
	Pressed button groups can only have one button pressed at a time. Follow the general behaviour of radio buttons. To set a button to pressed, use the `aria-pressed` attribute set to `true` or `false`.	HTML Classic ASP `<div class="ace-button-group"> <button class="ace-button ace-button-pressed" aria-pressed="true" type="button"><span>Apples</span></button> <button class="ace-button ace-button-pressed" aria-pressed="false" type="button"><span>Oranges</span></button> <button class="ace-button ace-button-pressed" aria-pressed="false" type="button"><span>Bananas</span></button> </div>` `<% ace.ButtonGroup(Array("type", "separate")) ace.Button(Array(_ "text", "Apples",_ "type", "pressed",_ "aria-pressed", "true"_ )) ace.Button(Array(_ "text", "Oranges",_ "type", "pressed",_ "aria-pressed", "false"_ )) ace.Button(Array(_ "text", "Bananas",_ "type", "pressed",_ "aria-pressed", "false"_ )) ace.ButtonGroupEnd %>`
	Indeterminate Loading Buttons can be started, stopped (returned to non-loading state) and toggled between started and stopped. However note it is the application's responsibility to bind and unbind events, for example to prevent further clicks.	HTML Classic ASP `<button class="ace-button" id="IDOFBUTTON" type="button" data-ace-loading="true" role="progressbar"><span>Load</span></button>`
	An example of a small primary loader	HTML Classic ASP `<button class="ace-button ace-button-small" id="IDOFBUTTON" type="button" data-ace-loading="true" role="progressbar"><span>Load</span></button>`

JavaScript

Methods

Function	Arguments	Description	Example
toggleLoading	elementSelector	Toggles button between loading and normal state	`ACE.Buttons.toggleLoading('#IDOFBUTTON')`
startLoading	elementSelector, (optional) progress object with min, max and now props	Sets the button to loading state	Indeterminate loading buttons: `ACE.Buttons.startLoading('#IDOFBUTTON')` Loading buttons with known progress value: `ACE.Buttons.startLoading('#IDOFBUTTON', { 'min': 1, 'max': 3, 'now': 1 })`
updateLoading	elementSelector, (optional) progress object	Updates the 'now' value on a loading button	Loading buttons with known progress value: `ACE.Buttons.startLoading('#IDOFBUTTON', { 'min': 1, 'max': 3, 'now': 2 })`
stopLoading	elementSelector	Sets the button back to non-loading state	`ACE.Buttons.stopLoading('#IDOFBUTTON')`

Design

Button text and icons

Button placement

Button groups

Pressed buttons

Dimensions

Code

JavaScript

Methods

Elements

Foundation

Patterns

Labs

ACE