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
  • 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

Heading

Headings provide hierarchical structure to content, allowing users to quickly understand and navigate information on a page.

When to use

Use headings to:

  • Create a clear hierarchy and structure for your content

  • Help users scan and navigate content quickly

  • Break up large blocks of text to improve readability

  • Establish relationships between sections of content

  • Support SEO by clearly structuring your content

When not to use

Do not use headings when:

  • You want to emphasise text without creating a new section or topic (use other text styling instead)

  • You need decorative text that doesn't serve a structural purpose

  • You want to create visual hierarchy without semantic meaning

  • You simply want larger or bolder text without indicating a new section


Best practice guidelines

  • Maintain hierarchy: Always use headings in the correct order (H1, H2, H3, etc.) without skipping levels to maintain a logical content structure

  • Be descriptive: Headings should accurately describe the content that follows

  • Keep it concise: Aim for short, scannable headings (ideally under 80 characters)

  • Consistency matters: Use similar phrasing patterns for headings at the same level

  • Avoid orphaned headings: Don't place headings at the bottom of pages or sections without following content

  • Limit H1 usage: Generally use only one H1 per page, representing the main page title

  • Consider SEO: Include relevant keywords naturally, but avoid keyword stuffing

  • Mobile considerations: Ensure headings remain readable at smaller screen sizes

These guidelines are derived from established content design principles and accessibility standards for government websites, including those from the Australian Government Style Manual.

Variations


Accessibility

This component meets WCAG 2.2 AA accessibility guidelines, with the following key results based on the Accessibility Assessments file:

WCAG Criterion
Level
Status
Notes

1.3.1 Info and Relationships

A

Pass

Headings are properly marked up to convey structure

1.4.3 Contrast (Minimum)

AA

Pass

Heading text meets the minimum contrast ratio of 4.5:1

1.4.4 Resize text

AA

Pass

Headings remain readable when text is resized up to 200%

1.4.12 Text Spacing

AA

Pass

Headings remain visible/readable with adjusted text spacing

2.4.6 Headings and Labels

AA

Pass

Headings accurately describe topic or purpose

2.4.7 Focus Visible

AA

Pass

Focus is visible when navigating using a keyboard

All tests for link headings also pass accessibility requirements, ensuring that interactive headings are properly accessible.

Security

No specific security considerations apply to this component as it is primarily presentational and does not process user data.

Component inspiration and uplift

This atomic element has been modelled after the Headings component in the former Australian Government Design System (AGDS). CivicTheme has uplifted the component in the following manner:

  • All headings use the commercial-free Lexend font family as the primary web font, designed with variable, extended scaling to improve reading fluency and character recognition

  • Supports a complete hierarchy from H1 to H6

  • Headings are available in two states: default (without link) and link (with link)

  • Previous styling included display headings, which have been removed in favour of a more logical H1-H6 structure that aligns better with SEO principles

  • Simplified states by embedding the Link component inside Heading when needed, which automatically applies link interaction states to the Heading

These uplifts align with the Digital Service Standard requirements for clear, accessible content structure (Criteria 3: Leave no one behind) and build trust in design (Criteria 5) through consistent, recognisable patterns.


Research on this component

★★★★☆ Confidence rating = High (Informed by extensive testing and established patterns)

While specific user research data isn't available exclusively for the Heading component, this component benefits from extensive research and established patterns in digital content design. Headings represent one of the most well-researched elements in digital interfaces.

Research consistently shows that:

  • Users scan content rather than reading word by word, making properly structured headings critical for comprehension

  • Clear heading hierarchy significantly improves information findability

  • Screen reader users heavily rely on headings to navigate content efficiently

  • Properly structured headings improve SEO performance

The component follows established best practices derived from extensive government and industry research into content readability and accessibility.

Known issues

  • Responsive consistency: When headings wrap to multiple lines on mobile devices, the visual hierarchy can sometimes appear inconsistent, particularly with longer headings

  • Alignment variations: In certain contexts, heading alignment (left, center, right) may cause readability issues if not applied consistently

  • Heading links: When headings contain links, users sometimes have difficulty identifying the clickable area, particularly when only part of the heading is linked

More research needed

More user research would be beneficial in the following areas:

  • Optimal heading sizes and spacing across different device types and screen sizes

  • User preferences for heading styles in different content contexts (formal documentation vs. news content vs. service content)

  • How heading styles impact reading comprehension and retention for different user groups

  • The effectiveness of various heading formats in multilingual contexts

Help improve this component

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

  • Contribute to discussions about heading implementation on the CivicTheme GitHub repository

  • Submit examples of effective heading implementations on your CivicTheme site

  • Propose improvements to the heading styles or structure based on user research

  • Report any accessibility or usability issues you encounter with this component


Resources

  • Storybook

  • GitHub

References

Changelog

Version
Date
Changes

1.0.0

Initial release

Base heading styles established

1.7.0

2024-03-20

Updated to support WCAG 2.2

1.8.0

2024-07-23

Renamed "Headings" to "Heading" component

Contact us

PreviousText fieldNextLink

Last updated 1 month ago

Was this helpful?

Check out our to learn more.

Australian Government Style Manual.

W3C Web Accessibility Initiative.

Nielsen Norman Group.

Lexend.

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

contributing section
Figma
headings and subheadings
headings
How Users Read on the Web
Reading research
Getting Help