CivicTheme
  • Docs
  • Changelog
  • Getting started
    • Introduction
    • Installation
    • Getting help
    • Security policy
    • Partnerships
  • Installation
    • Drupal theme
  • Contributing
    • Contribution model
    • Contribution basics
    • Small contribution spec
    • Medium contribution spec
    • Major (RFC-level) contribution spec
    • Code of conduct
    • Figma contributions
  • Components
    • Component list
    • Atoms
      • Button
      • Chip
      • Content link
      • Check box
      • Field description
      • Field message
      • Fieldset
      • Label
      • Radio
      • Select
      • Textarea
      • Text field
      • Heading
      • Link
      • Paragraph
      • Popover
      • Quote
      • Table
      • Tag
      • Text list
    • Molecules
      • Accordion
      • Attachment
      • Breadcrumb
      • Callout
      • Event Card
      • Field
      • Figure
      • Group filter
      • Logo
      • Map
      • Navigation card
      • Next step
      • Pagination
      • Promo card
      • Search
      • Service card
      • Single filter
      • Snippet
      • Subject Card
      • Table of Contents
      • Tabs
      • Tag List
      • Tooltip
      • Video Player
    • Organisms
      • Alert
      • Banner
      • Campaign
      • Footer
      • Header
      • List
      • Message
      • Mobile Navigation
      • Navigation
      • Promo
      • Side Navigation
      • Skip link
      • Slider
      • Social links
  • Content Authoring
    • Overview
    • Global settings
      • Favicon
      • Header
        • Site slogan
        • Header logos
        • Primary navigation
        • Secondary navigation
      • Banner
      • Search
      • Link
      • Skip link
      • Side navigation
      • Signup
      • Footer
        • Footer logo
        • Social links
        • Footer navigation
        • Acknowledgement of Country
        • Copyright
      • Colours
    • Content types
      • Page
        • Configure the banner
      • Event
      • Alert
    • Content components
      • Accordion
      • Automated list
      • Attachment
      • Callout
      • Campaign
      • Content
        • Quote
      • iFrame
      • Manual List
        • Event card
        • Event reference card
        • Navigation card
        • Navigation reference card
        • Promo card
        • Promo reference card
        • Publication card
        • Service card
        • Subject card
        • Subject reference card
        • Snippet
      • Map
      • Next step
      • Promo
      • Slider
      • Webform
    • Vocabularies
      • Topics
      • Site sections
    • User accounts & roles
Powered by GitBook
On this page
  • When to use
  • When not to use
  • Best practice guidelines
  • Variations
  • Accessibility
  • Security
  • Component inspiration and uplift
  • User research on this component
  • Known issues
  • More research needed
  • Help improve this component
  • Resources
  • References
  • Changelog
  • Contact us

Was this helpful?

Edit on GitHub
Export as PDF
  1. Components
  2. Atoms

Button

A Button is an interactive element that triggers an action when clicked or tapped, providing a clear call-to-action for users.

Buttons provide users with the ability to submit an action or follow a link to another location.

When to use

Use the button component when you need users to:

  • Submit a form

  • Trigger an action like opening a modal, starting a process, or revealing hidden content

  • Navigate to another page or section of the site

  • Download a file

  • Confirm an action or decision

Buttons are appropriate when the action is a key task or primary user journey on the page.

When not to use

Do not use the button component when:

  • The action is of secondary importance on the page - consider using a link instead

  • You need to create a link within a paragraph of text - use a text link instead

  • You need to create a complex interactive element - consider using a more specialised component

  • The action would be better represented by a different component like a dropdown menu, toggle switch, or checkbox


Best practice guidelines

  • Action-oriented labels: Use clear, concise, and action-oriented text that describes what will happen when the button is clicked (e.g., "Submit application" rather than "Click here")

  • Hierarchy: Use primary buttons for the most important actions, secondary buttons for alternative options, and tertiary buttons for less important functions

  • Size appropriate to context: Choose the appropriate button size (large, regular, small) based on the context and importance of the action

  • Consistent placement: Place buttons consistently throughout the interface to create predictable patterns for users

  • Adequate spacing: Ensure sufficient space between buttons and other elements to prevent accidental clicks, especially on mobile devices

  • Visual feedback: Provide clear visual feedback for all interactive states (hover, focus, pressed/active, disabled)

  • Icons with purpose: If using icons within buttons, ensure they enhance understanding and provide visual reinforcement of the action

  • Accessible colour contrast: Maintain sufficient colour contrast between the button and its background, as well as between the button text and button background

  • Responsive design: Ensure buttons work well across all screen sizes and devices

Variations

  • Primary buttons: Used for the most important actions on a page

  • Secondary buttons: Used for alternative or secondary actions

  • Tertiary buttons: Used for less important functions or in space-constrained situations

  • Button sizes: Available in large, regular, and small options

  • Icon placement: Options include icons to the right, left, or no icon

  • Button states: Default, focus, hover, pressed, and disabled

  • Directional variants: Forward (right arrow), back (left arrow), and external (external link icon)


Accessibility

This component has been assessed against WCAG 2.2 guidelines with detailed test results available in the CivicTheme accessibility documentation.

Summary of the most recent accessibility test results:

WCAG Criterion
Level
Status
Notes

1.4.3 Contrast (Minimum)

AA

Pass

1.4.4 Resize text

AA

Pass

1.4.11 Non-text Contrast

AA

Pass

1.4.12 Text Spacing

AA

Pass

2.1.1 Keyboard

A

Pass

2.4.4 Link Purpose (In Context)

A

Pass

2.4.7 Focus Visible

AA

Pass

2.5.8 Target Size (Minimum)

AA

Fail

The size of targets for pointer inputs does not meet the minimum 24×24 CSS pixel requirement

3.2.2 On Input

A

Pass

3.2.3 Consistent Navigation

AA

Pass

3.2.4 Consistent Identification

AA

Pass

This component meets most accessibility requirements but needs improvement to meet the WCAG 2.2 target size criteria.

Security

No specific security considerations have been identified for this component beyond standard web security practices.

Component inspiration and uplift

This component has been modelled after the Buttons component in the former Australian Government Design System (AGDS). It has been uplifted by Salsa Digital, as the custodian of the CivicTheme Design System, in the following ways:

  • Size variations: All CivicTheme buttons come in large, regular and small options. The regular-sized buttons are based on GOLD Design System size guidelines and are intended to be the most commonly used format. The larger-sized button has been included for pages with a single primary goal (e.g., a campaign landing page).

  • Iconography integration: Each variant of CivicTheme's call to actions includes the option to add appropriate iconography based on their functionality, such as directional arrows for navigation, external link icons for external destinations, and download icons for downloadable content.

  • Enhanced states: The existing disabled states of the Australian Design System's button have been improved to provide better contrast required for WCAG 2.1 standards, ensuring higher visual hierarchy distinction while maintaining legibility.


User research on this component

★★★★☆ Confidence rating = High (Informed by general design pattern research)

While specific user research data conducted by CivicTheme for this component is not available, the button component is one of the most thoroughly researched UI elements across digital platforms. The implementation in CivicTheme follows established patterns that have been validated through extensive industry research.

General research findings consistently show:

  • Users expect buttons to look and behave in familiar ways, with clear visual affordances that indicate they can be clicked

  • Primary buttons with strong visual styling receive higher engagement rates

  • Users prefer buttons with clear, action-oriented labels

  • Buttons with appropriate size and spacing reduce error rates, especially on mobile devices

More specific user research for the CivicTheme button component would be beneficial to validate these general findings within the specific context of government websites.

Known issues

  • Target size compliance: As noted in the accessibility assessment, the button component does not currently meet WCAG 2.2 criterion 2.5.8 for minimum target size (24x24 CSS pixels), which may impact users with motor control difficulties.

  • Mobile responsiveness: On very small screens, buttons with lengthy text may break to multiple lines, affecting visual consistency.

  • Icon alignment: In certain browser and screen size combinations, icon alignment within buttons may shift slightly from the intended design.

More research needed

Additional research would be beneficial in the following areas:

  • User preference and effectiveness of different button sizes across various device types

  • Performance of different icon placements (left, right) for specific user tasks

  • Optimal button placement for multi-step processes in government service contexts

  • Button label effectiveness for government-specific actions and terminology

  • Impact of button styling on user trust and confidence when performing critical actions

If you have conducted user research that addresses these areas, you can submit your findings to help improve this component.

Help improve this component

To help make this component more useful and up-to-date, you can:

  • Contribute to our button component discussion on GitHub

  • Submit your user research findings to help improve the button component

  • Propose a change to address the target size accessibility issue

  • Suggest improvements to the component documentation


Resources

  • Storybook

  • GitHub

References

  • W3C Web Content Accessibility Guidelines (WCAG) 2.2

  • Nielsen Norman Group: Button UX Design Best Practices, Types and States

  • Australian Government Design System (AGDS) Button Component Guidelines

  • Web Accessibility Initiative (WAI) ARIA Authoring Practices

Changelog

Version
Date
Changes

1.8.0

23 Jul 2024

Renamed Buttons to Button

1.7.0

20 Mar 2024

Updated to WCAG 2.2 compliance testing

1.6.0

[Date]

[Changes]

Contact us

PreviousAtomsNextChip

Last updated 1 month ago

Was this helpful?

Check out our to learn more.

If you have a question about the CivicTheme design system or need our help, visit the page for guidance.

contributing section
Figma
Getting Help