Where to get support

• Drupal theme issue queue

• CivicTheme Github repository

• #civictheme-designsystem (note: you need to first )

• Send an email to [email protected]

Where to submit issues and PRs

Development of the entire CivicTheme ecosystem is managed in the .

This allows to develop the Drupal theme and modules at the same place and use advanced CI configuration for testing.

The code from theis automatically published to Drupal.org with all commit and author information preserved.

For Drupal theme:

• Submit issues to

• Submit PRs to the

For Drupal modules:

• submit issues to

• submit PRs to

For UI Kit:

• Submit issues to

• Submit PRs to

For this documentation:

• Submit issues to

• Submit PRs to

If you do not know which part the issues relates to - submit an issue to and it will be moved to the appropriate location by the CivicTheme maintainers.

CivicTheme's vision

Build an enterprise-grade atomic design system & community of practice to deliver common UI patterns & governance infrastructure to accelerate consistent, accessible, brand-aligned, research-backed UX.

The origin story of CivicTheme started from having experienced the pains of the frequent reinvention of solutions and inconsistencies in design across multiple projects, resulting in inefficiencies and fragmented user experiences. A unified, world-class design system, co-created with the community, is essential to standardise solutions, enhance user experience, and drive innovation by addressing common problems and desired outcomes.

For every citizen.

Install CivicTheme

Alternatively, you can download the from Drupal.org and place into the desired location.

The CivicTheme security framework outlines the CivicTheme approach to developing, reviewing, and maintaining CivicTheme and its related assets in accordance with secure-by-design principles.

It describes the measures, tools, and governance processes used to protect our codebase, users, and community from potential security threats.

CivicTheme is an open-source, government-grade design system comprising multiple components (design assets, UI Kit, and a Drupal theme). Security and compliance are fundamental to CivicTheme’s mission of enabling reliable, consistent, and accessible digital experiences for government and public services.

Note: CivicTheme is an open source codebase, not a hosted service. Implementing organisations are responsible for the security of their own infrastructure and deployments. This policy focuses on the security of CivicTheme’s code and release process.

Supported versions

We support the current release of CivicTheme and the accompanying UI Kit.

Continuous monitoring

Security monitoring is an integral part of the CivicTheme development process. GitHub’s built-in security scanning is enabled across repositories to automatically detect vulnerabilities in code and dependencies. Scans run regularly on commits and pull requests, generating alerts for review, prioritisation, and resolution.

Linting and static code analysis tools

A suite of linting and static analysis tools supports ongoing quality assurance and helps maintain secure coding standards. These tools automatically run on every commit to detect coding and security issues early.

These include:

• Drupal Practice: ensures compliance with Drupal’s best practices and secure coding guidelines. This helps maintain a consistent, high-quality, and secure codebase.

• PHP CodeSniffer: automatically detects violations of coding standards in PHP, JavaScript, and CSS files. Helps ensure consistent code style, enforces best practices, and can catch potential issues early in development.

• ShipShape: Analyses Drupal code to ensure it follows Drupal coding standards and best practices. Helps detect errors, security risks, and maintainability issues, supporting consistent, high-quality code.

Third-party validation

CivicTheme relies on external dependencies that are carefully managed to maintain a strong security posture. This proactive approach ensures that all third-party components meet the same high security standards as the rest of the CivicTheme codebase.

• Dependabot: GitHub Dependabot monitors third-party libraries, alerts the team to vulnerabilities, and automatically generates pull requests with safe updates. Front-end dependencies, such as those within the UI Kit, are also monitored through Dependabot to ensure they remain up to date and secure.

• Composer Security Checker: works alongside Dependabot to scan PHP project dependencies for known security vulnerabilities and alert the team to packages that need updating.

• CodeQL Scanning: GitHub’s CodeQL engine runs static analysis on all commits and pull requests to detect common vulnerabilities in PHP and JavaScript.

Drupal Security Advisory

CivicTheme is committed to transparency and responsible disclosure when managing security vulnerabilities. As such, CivicTheme has opted into the Drupal Security Advisory. This ensures that vulnerabilities affecting the theme can be responsibly reported, tracked, and communicated to users.

By participating in this program, we commit to following the Drupal Security Team’s processes for assessing, prioritising, and releasing security updates, helping maintain a secure environment for all users of the theme.

Reporting a vulnerability

Find out how to report a vulnerability on the page.

Future security enhancements

We are continually improving our security processes.

Planned future developments include deeper static analysis, expanded communication channels for security advisories, and enhanced automation in our CI/CD pipeline for proactive testing and vulnerability detection.

These initiatives reinforce our commitment to maintaining a robust, secure, and transparent open-source ecosystem.

Ongoing commitment

CivicTheme commits to:

• Supporting the current version

• Responding quickly to valid vulnerability reports

• Adopting industry best practices in security scanning and review

• Maintaining transparency through public changelogs and advisories

CivicTheme partnerships and collaboration

CivicTheme is an open-source design system governed by a diverse community of government agencies, digital agencies, and individual contributors. The open-governance model ensures that CivicTheme grows in a way that benefits the wider community while maintaining consistency, accessibility, and government-grade standards.

For maintenance details, please refer to project README.md file.

What are Organisms? In CivicTheme, organisms are relatively complex components composed of groups of molecules and atoms working together as a cohesive unit, based on Brad Frost's Atomic Design principles. These larger, more sophisticated interface sections form distinct, recognizable portions of the interface.

Organisms in CivicTheme include components such as headers, footers, navigation menus, and content listings, all designed to ensure accessibility, consistency, and reusability across digital services. These organisms are the functional building blocks of CivicTheme pages, combining multiple atoms and molecules to create meaningful interface sections while ensuring a consistent, accessible, and flexible design system across projects. Each organism follows WCAG 2.2 AA standards and is optimised for both design and development, with implementations available in Figma and Storybook.

This section is under development

CivicTheme provides one layout: 3 Columns Layout

When managing your layout (layout builder) within display settings of your content type, you are able to configure whether the content is to be constrained or whether the content is to go page edge to page edge.

Edge-to-edge vs Constrained Content

Edge-to-edge content means that the content and background elements extend the full width of the browser window, from the left edge to the right edge of the viewport. This creates an immersive, modern design where components can utilize the entire screen width. This style is commonly used for landing pages, hero sections, and full-width image galleries.

Constrained content limits the content width to a maximum container size (1248 pixels), centering it within the viewport with margins on either side on larger screens. This improves readability and provides a more traditional page layout that's easier to scan on wide displays.

Sidebar Management

When using Layout Builder's sidebar columns, users need to be careful to ensure they don't conflict with theme region sidebar blocks. Blocks placed in the theme's left and right sidebars can overlap with blocks placed in Layout Builder's sidebars, potentially causing duplication or layout issues. It's important to have a clear strategy for managing which blocks appear in which system to maintain consistent layouts across your site.

Deprecated Layouts

There are two deprecated layouts that should not be used:

• Single Column

• Single Column contained

These layouts are in the process of being removed in the coming release.

The layout configuration is defined in the civictheme.info.yml.

The layout can be viewed within .

• Configuration MUST be stored in the civictheme theme's config/install and config/optional directories.

• All machine names MUST be prefixed with civictheme_ for:

  • Content types

  • Vocabularies

  • Text formats
• UI MUST NOT refer to CivicTheme .

• page or article SHOULD NOT be used as a prefix for the name of a content type unless absolutely necessary, instead: News article , Blog page

• Field names MUST be:

  • Prefixed with field_c_<first_letter_of_entity_type>_

  • Given generic names based on their purpose and SHOULD be shared across multiple bundles

• Vocabularies MUST be:

  • Named using plural nouns

  • Named using contextual information to distinguish between vocabularies used for specific purposes: Blog topics instead of just Topics

CivicTheme theme utilises the components that are defined within CivicTheme UI kit.

We access these components via component namespaces.

Using CivicTheme UI kit components

The idea of separating the CivicTheme UI kit and Drupal templates is to create a reusable set of components that can be used in multiple CMS systems.

After setting up a component and structuring the twig file (see ), you can include this new component in a Drupal template with an include statement. See the civictheme/templates directory for how CivicTheme components have been included.

Overriding CivicTheme SDC Components

Only themes can override components (modules cannot override). For a theme to override a component, use the replaces key within the mytheme.component.yml file.

Both components must have schemas defined within their YML files, and the schemas' props and slots must match.

The value of the replaces key must refer to the other component using the machine name of the module/theme and the machine name of the component, delimited with a colon (:). For example:

In this example, civictheme is the name of the theme that contains the component to be replaced, and button is the machine name of that component.

Best Practice: Copy the entire component directory from CivicTheme to your sub-theme as a starting point for the CSS and Twig files you'll be modifying. Ensure you keep the same directory name as the original component.

If you need to provide custom variables to your component, you derive these variables through the preprocess hook system Drupal provides. Look at the files in civictheme/includes directory for how the CivicTheme components are preprocessed in Drupal.

But, what about default field templates

There is a drawback (or advantage as it aligns more closely with modern UX development workflows) to CivicTheme in that the architecture is based at the component level rather than then field level.

Outputting individual fields on the page will result in bare bones output as CivicTheme theme is relying upon the developer to provide these field values to components rather than utilising a field formatter.

Paragraphs are the primary mechanism for linking components up with Drupal, and we have implemented a significant number within CivicTheme. These paragraphs can be created via paragraph fields within new content types and then organised within layout builder to quickly create a new content type.

What are Atoms?

In CivicTheme, atoms are the smallest, most fundamental building blocks of the design system, based on Brad Frost’s Atomic Design principles. These individual elements are simple, self-contained, and non-reducible, forming the foundation of all components. Atoms in CivicTheme include basic HTML elements such as buttons, form inputs, and typography elements, all designed to ensure accessibility, consistency, and reusability across digital services.

These atoms are the foundation of CivicTheme, and they combine to form more complex components like molecules and organisms, ensuring a consistent, accessible, and flexible design system across projects. Each atom follows WCAG 2.2 AA standards and is optimised for both design and development, with implementations available in and Storybook.

Component namespaces have changed with the release of CivicTheme 1.11 which migrated CivicTheme components to use Single Directory Components.

Current Namespace Format

All CivicTheme components now use the format civictheme:<component_name> for example civictheme:button or civictheme:accordion. There is no longer nesting of components into their atomic directories.

Sub-theme Namespacing

In a sub-theme, a new component is namespaced with the sub-theme's machine name. For example: civictheme_subtheme:new_button

However, when overriding a CivicTheme component, the sub-theme uses the original CivicTheme namespace civictheme:button to refer to this overridden component. This ensures that the override properly replaces the base theme's component.

Single Directory Components

For more information about the Single Directory Components specification, see the .

Particle

Particle is the most basic unit of measurement, using pixels to tie to the design grid which is in pixels as well.

Depending on the context, most of the values will be using conversion to rem with the rem() function.

ct-particle() function can be used to base element measurements off the particle.

For spacing, use ct-spacing()

The Automated List Component enables editors to create content lists and embed them on any page.

It uses a civictheme_automated_list paragraph, whose field values are processed by a View preprocessing function. This function maps these values as arguments to a pre-configured civictheme_automated_list view.

The component provides configurations via paragraph to a view allowing content type restrictions, show/hide pagination, altering the number of items and filter configuration options.

It is possible to replace the default civictheme_automated_list view with a more custom one required for a specific site via hook_civictheme_automated_list_view_name_alter() (see for details).

CivicTheme also provides support for filters in an exposed form. For views with only 1 exposed filter, Single Filter component (tag based) is enabled, but as soon as there is more than one exposed filter - the Group Filter component (with dropdown filters) is enabled automatically.

Managing colors

Website colors can be specified via:

• Color Selector

CivicTheme UI kit contains a large number of variables that modify all areas of the theme.

Variables allow for modification of:

• Theme and component specific colors

• Typography including line-height, font-size, font-weight and which fonts are used

What are Molecules? In CivicTheme, molecules are combinations of atoms that work together as a functional unit, based on Brad Frost's Atomic Design principles. These components are created by joining multiple atoms to form simple, reusable interface elements with distinct functionality.

Molecules in CivicTheme include components such as search fields, navigation items, and card components, all designed to ensure accessibility, consistency, and reusability across digital services. These molecules serve as the connective tissue of CivicTheme, bridging atoms and more complex organisms, ensuring a consistent, accessible, and flexible design system across projects. Each molecule follows WCAG 2.2 AA standards and is optimised for both design and development, with implementations available in and Storybook.

Topics

Topics are generally used to group information by topic or subject. Out-of-the-box, CivicTheme comes with several topics set up - you just need to edit them to the topics you'd like.

Managing Topics

You should be logged in as a user with Site administrator role to modify topics.

1. Navigate to the Administration → Structure → Vocabularies → Topics

2. Click on “Add” or “Edit” term.

3. Provide Topic details

4. Click “Save” to save changes.

Using Topics

Topics can be used within Automated list content component group information.

Below you can see an example of three News card showing three different topics - Scholarships, International students, and Research within an Automated list.

[screenshot of the usage of the here]

See Automated list component page for more details.

Product requirements

• CivicTheme Drupal theme MAY be used out of the box without any customisations.

• CivicTheme Drupal theme MUST NOT be changed for customisations. If customisations are required - a consumer theme MUST be created and used as a sub-theme of the CivicTheme theme.

• CivicTheme Drupal theme MUST be fully compatible with GovCMS SaaS:

  • MUST NOT have any modules

  • MUST NOT rely on any libraries

Creating a sub-theme from the CivicTheme theme

CivicTheme provides a starter theme and a script to generate a child theme for you to get started with.

Run the following command from within civictheme theme directory:

php civictheme_create_subtheme.php <theme_machine_name> "Human theme name" "Human theme description" /path/to/theme_machine_name

This will generate a sub-theme in path/to/theme_machine_name theme directory with everything ready to be installed and compiled.

Enabling sub-theme

Enable the theme in UI or with Drush:

Compiling sub-theme assets

Run the following command from within your sub-theme directory:

Remove examples from civictheme_starter_kit

CivicTheme 1.11 saw the upgrade to SDCs which came with a namespace change.

The existing example components need to be removed so that civictheme sub-themes built with this tool work correctly.

We will address this issue in CivicTheme 1.12. As a workaround, please delete the following directories from your new sub-theme manually (unless you have added some code changes):

Overview

CivicTheme's build system is a custom asset compilation pipeline designed specifically for Drupal themes. Built around build.js, it provides a simplified, fast approach to managing theme assets while prioritising speed and auditability over complex optimisation features.

The system is engineered to handle the unique requirements of government digital services, ensuring consistent asset delivery across different environments while maintaining the flexibility needed for custom theme development.

CivicTheme uses four different styles of menu in the base theme. These are placed by block in different regions of the page.

You can control the component / style for the menu with the theme hook suggestion which can be configured in the Block configuration form.

Primary Navigation

The dropdown menu is the primary navigation for the site.

For this menu to be themed correctly the menu block must be configured with menu__civictheme_primary_navigation theme hook suggestion in the HTML and style options of the Block configuration form.

Site assets refer to the collection of files and resources that are essential for the visual appearance, functionality, and overall user experience of a website.

This section explains working with assets in the context of your custom sub-theme. All commands and path are related to your sub-theme directory.

Compiling and serving assets

All assets are compiled using npm run dist based on the supplied .

This section contains comprehensive documentation for developing and customising CivicTheme for Drupal.

Installation

For installation instructions, see .

CivicTheme provides 50+ components out of the box with a comprehensive system to modify, extend and create new components to fit your needs.

Twig components created with the CivicTheme UI kit are designed to be CMS-agnostic: they can be used by any application that can use Twig templates.

There are no CMS-specific mechanisms used in the UI kit.

Modifying components colours

CivicTheme comes with an extensive variables and colour customisation system to enable you to change the look and feel.

CivicTheme has several unique architectural approaches for developing themes that promote component-centric development and maintainability. Understanding these systems is essential for building sites that work effectively within the CivicTheme ecosystem.

Overview

CivicTheme's development approach is built around these core systems:

• Component-centric architecture - Organised folders for styles, JavaScript, and templates

• Template separation - Component Twig templates separated from Drupal *.html.twig files

• Preprocess functions - Custom functions to populate component template properties

• Color system - Custom color overrides and theming capabilities

• Build system - Custom asset compilation and development workflow

System Documentation

Each system has detailed documentation that explains implementation patterns and best practices:

Learn about CivicTheme's custom build system, including asset compilation, configuration, and development workflows.

Explore the color override system and how to customise CivicTheme's design tokens.

Understand the component-centric approach, including template separation, preprocess functions, and how to map Drupal data to component properties.

Discover how Drupal entities are mapped to component templates and properties.

Related Documentation

Component Development

• - How to use CivicTheme UI Kit components in Drupal

• - Component namespace system and organisation

• - Asset management and component structure

Learning Path

To effectively work with CivicTheme systems:

1. Start with the basics: Read to understand component separation

2. Understand the build system: Review for development workflow

3. Learn component mapping: Study for data flow patterns

4. Customise appearance: Explore for theming

Key Benefits

Learning these systems enables you to:

• Build component-centric sites that are maintainable and scalable

• Create reusable patterns that work across different projects

• Leverage CivicTheme's ecosystem effectively

• Maintain consistent design and development standards

Getting Help

• - Community resources and support

• - How to contribute to the ecosystem

• - Source code and issues

Overview

CivicTheme separates its component Twig files from its Drupal implementation. This separation requires preprocess functions to extract data from Drupal entities, process it as necessary, and map it to the expected properties of the UI Kit Twig file. This approach encourages building CivicTheme components in a reusable fashion where the HTML is more generalised and less Drupal-specific.

Quick Start

Prerequisites

• A CivicTheme subtheme

• Basic understanding of Drupal preprocess functions

• Familiarity with Twig templating

Basic Implementation

1. Create a custom include file for your field processing logic

2. Implement a preprocess hook to call your custom function

3. Update the Twig template to reference the CivicTheme component

Utilities

CivicTheme provides utilities to simplify preprocess function development:

• - Helper functions for common Drupal operations

Implementation Example

The following example demonstrates how to map a Drupal field to display as a CivicTheme tag component. This covers the fundamentals of gathering data from an entity in a preprocess function, passing it through the *.html.twig template, and setting it on the civictheme:tag component.

Step 1: Theme File

File: subtheme.theme

What this does:

• Includes the custom field processing logic

• Calls the custom preprocess function when the field preprocess hook is triggered

Step 2: Custom Field Processing

File: includes/custom_field.inc

What this does:

• Checks that the correct field is being processed

• Retrieves the node attached to the field and validates its type

• Uses the civictheme_get_field_value utility to extract the field value

• Adds the processed value to the custom_value

Step 3: Twig Template

File: templates/field/field--node--field-c-n-custom.html.twig

What this does:

• References the CivicTheme tag component

• Passes all available properties through to the component

• Can be modified to reference custom components if needed

Best Practices

File Organisation

• Place custom code in dedicated *.inc files specific to the feature being implemented

• Use descriptive file names that clearly indicate the purpose

• Keep preprocess functions focused and single-purpose

Template Structure

As much HTML as possible should live in the components. The Drupal Twig templates should act as connectors to the components. It should be common for Drupal *.html.twig templates to contain only an include of a component Twig file.

Data Processing

• Always validate field names before applying custom processing

• Use CivicTheme utilities for common operations

• Ensure proper type checking for entities and fields

• Follow Drupal coding standards and best practices

Next Steps

• Explore the for additional helper functions

• Review other component implementations for patterns and approaches

• Consider contributing improvements to the mapping system

CivicTheme code of conduct

We ask that all members of our community, in any space (virtual or physical), adhere to this Code of Conduct, promoting understanding, empathy, and personal awareness of all individuals, including those from the Drupal and greater technical communities, even when disagreements arise.

Our pledge

We pledge to create a welcoming, harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, experience level, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our standards

Positive behaviours:

• Use welcoming and inclusive language.

• Be respectful of differing viewpoints and experiences.

• Accept constructive criticism gracefully.

• Focus on what benefits the community.

Unacceptable behaviours:

• Sexualised language or imagery, and unwelcome advances.

• Trolling, insulting, or derogatory comments.

• Personal or political attacks.

• Harassment, public or private.

Participation guidelines

• Listen and engage actively: Read the conversation backlog before joining. Assume good intent, as participants come from diverse backgrounds.

• Promote understanding and empathy: Engage with others respectfully, especially those you may disagree with. Strive to increase personal awareness of diverse perspectives.

• Respect other experiences: Speak from your experience, not for others. Don’t invalidate someone’s story.

Handling off-topic discussions and sharing

• Stay on topic: Avoid spamming, thread hijacking, or excessive off-topic conversation, especially during meetings.

• Sharing content: Do not share CivicTheme content without explicit permission from all participants involved.

• Reporting issues: Screenshots for harassment reporting are allowed without permission, but avoid using them to shame others.

Conflict and disruptive behaviour management

• Address conflicts directly: Where safe, address issues in the space where they arise, or contact an admin for help.

• Admin support: Admins or Community Managers can help when conflicts escalate.

• Tiered response system for disruptive behaviour:

  • Tier 1

Our responsibilities

Project maintainers are responsible for enforcing this code of conduct. They may remove, edit, or reject contributions or ban contributors for inappropriate behaviour.

Scope

This code of conduct applies within project spaces and in public spaces where a community member represents CivicTheme (e.g., official emails or social media).

Enforcement

Instances of unacceptable behaviour may be reported by contacting the team at . The team will review and investigate all complaints confidentially.

Attribution

This code of conduct is adapted from the Contributor Covenant, version 1.4, Drupal Diversity & Inclusion’s Participation Guidelines, and CivicTheme community input.

Feedback

If you have feedback or questions about our code of conduct, please join our and chat to us there, or contact us via !

When you’re ready to start contributing, follow CivicTheme's contribution model to ensure your work aligns with the standards for small, medium, or major contributions. Create a new branch to isolate your work:

• Small contributions: Small fixes, minor design tweaks, or documentation improvements.

• Medium contributions: Adding new features or extending components.

CivicTheme provides a customisable utilising a flex-based system.

UI kit grid system uses a series of containers, rows, and columns to layout and align content.

It’s built with flexbox and is fully responsive.

The system is adapted from the .

Example grid system markup

Component overview

Contributing in Figma

CivicTheme UI kit provides a system for easily consuming and extending typography mixins and variables.

Fonts

The default font-families are defined in a map $ct-fonts-default:

This map can be extended using $ct-fonts map (fonts can be stored with the library or linked to a remote location):

CivicTheme component library

CivicTheme is built using atomic design principles, offering a hierarchy of components ranging from foundational styles to complex, reusable patterns. Below, you'll find a complete breakdown of the components, categorised into Base, Atoms, Molecules, and Organisms.

For a visual list of our components, please check out the .

CivicTheme comes with pre-set Block Content blocks configuration. Since Drupal does not support running install hooks in themes, a custom content provisioning script has to be used.

When to provision content

Content provisioning is needed in two scenarios:

1. During initial setup - When first installing CivicTheme

Component overview

This is the preferred installation method for setting up CivicTheme on GovCMS SaaS. The automated script handles most of the setup process for you.

Before you begin

• Get access to GitLab project

• Check that support ticket to enable config imports was actioned

• Check that production has your user added with administrator role

• Check that you have all available on your machine

• Check that you have NPM 10+ and NodeJS 22+ available on your machine

• Read this whole page to make sure you understand the steps

Prerequisites

• GovCMS Project: You must have a GovCMS project / scaffold already set up and installed locally (i.e., you have run ahoy install).

• Ahoy: ahoy must be installed and configured for your project (i.e., you can run ahoy commands).

• Docker: Docker must be running, as ahoy typically interacts with Docker containers.

What the script does

The script will perform the following actions:

• Download and extract the specified CivicTheme version into themes/custom/civictheme.

• Run initial CivicTheme provisioning commands.

• Clear Drupal caches.

• Enable CivicTheme and set it as the default theme temporarily.

After the script completes successfully, your new subtheme will be active and ready for customisation in themes/custom/<your_subtheme_machine_name>.

Download the script

From your GovCMS project root directory, run:

Note: Download the script to your GovCMS project root directory on your host machine (not inside a Docker container).

Run the script

Execute the script from your GovCMS project's root directory. You'll need to provide values for all the required arguments.

Command structure

Arguments

Content provisioning option (-n flag)

The -n flag allows you to skip the automatic provisioning of content blocks during installation. This is particularly useful when you want to avoid performing a content forklift with GovCMS.

When to use -n:

• If you plan to manually provision blocks locally first, export the configuration, and then provision in production

• If you want to avoid doing a full content forklift migration

• If you prefer to have more control over when and how content blocks are created

Workflow when using -n:

1. Run the script with -n to skip content provisioning

2. Manually provision blocks through the theme settings locally

3. Export the block configuration using drush cex

4. Deploy the configuration to production

For detailed instructions on content provisioning, see .

Example commands:

Standard installation (with content provisioning):

Installation without content provisioning:

Post-installation steps

1. Build front-end assets

2. Commit built assets

   • Modify .gitignore file in your new theme and remove the following line:

   • Commit the built assets to your repository

Deployment

1. Push your changes to the remote repository

2. Wait for deployment to complete

3. If you used the -n flag, provision content in production following the

Next steps

• (alternative method)

Paragraph is a fundamental text element that presents content in structured blocks, enabling clear communication of information using CivicTheme's typography system.

When to use:

Use the paragraph component when you need to present textual content in a structured format. Paragraphs are essential for:

• Main body content across web pages

• Descriptive text within components like cards, callouts, and banners

• Explanatory information alongside forms and interactive elements

• Terms and conditions, privacy policies, and other legal content

• Instructional content and step-by-step guides

When not to use:

Do not use the paragraph component when:

• A heading would be more appropriate for section titles or page headings

• A list (ordered or unordered) would better present information in a scannable format

• Information can be better presented through tables, graphics, or other visual formats

• Content requires special formatting such as code snippets or blockquotes

Best practice guidelines:

• Readability: Keep paragraphs concise—ideally 3-5 sentences—to improve readability and comprehension. Break longer content into multiple paragraphs.

• Logical structure: Start with the most important information and use paragraphs to group related ideas together, following a logical flow.

• Plain language: Write in plain language, avoiding jargon and complex terminology where possible. This aligns with the Australian Government Style Manual guidelines for clear communication.

• Appropriate styling: Use the right size and weight variant for the context. Lead copy (larger paragraphs) works well as introductions, while body copy is suitable for main content.

Variations:

CivicTheme provides various paragraph styles to serve different content needs:

• Size variants: Extra large, large, regular, small

• Weight variants: Regular, bold

• Style variants: Regular, underline

These variants can be combined to create different text presentations suitable for different contexts, such as lead paragraphs, body text, captions, and footnotes.

Accessibility:

This component meets WCAG 2.2 AA accessibility guidelines according to the CivicTheme v1.7.0 Accessibility Assessments.

This ensures all paragraph text has sufficient contrast, can be resized up to 200% without loss of content, and maintains readability when text spacing is adjusted.

Security:

Security data not available for this component.

Component inspiration and uplift:

This component has been modelled after the Body component in the former Australian Government Design System (AGDS). CivicTheme has uplifted the component in the following ways:

• All typography uses the commercially free Lexend font family as the primary web font, which is specifically designed to improve reading fluency and character recognition.

• Body copy is restricted to 12-15 words per line, in line with Web Content Accessibility Guidelines recommendations of 80 characters (or less) per line.

• Paragraph breaks have been refined to span 1.5 times the height of a traditional line break, improving readability through appropriate white space.

• Anchored links use a background colour on hover state, rather than a standard underline or colour change, enhancing visibility of interactive elements.

The sans-serif Lexend font family with variable, extended scaling specifically aims to improve reading fluency, addressing the finding that over 60% of people experience some reading difficulty.

User research on this component:

★★★★☆ Confidence rating = High (Informed by design system best practices and accessibility standards)

While there is no specific user research data available exclusively for the paragraph component in CivicTheme, its design is informed by well-established typography and readability standards. The component incorporates research findings about reading patterns, optimal line length, and spacing considerations that have been validated across numerous studies.

The choice of the Lexend font family was backed by specific research showing its effectiveness for reading fluency. Research led by Dr. Bonnie Shaver-Troup in 2000 demonstrated that sans-serif fonts with expanded scaling improve character recognition and reduce cognitive noise, benefiting a wide range of readers.

Known issues:

• Line height considerations: In some contexts, the standard line height may need adjustment when paragraph text is displayed alongside other components with specific spacing requirements.

• Mobile text scaling: On extremely small screens, some paragraph variations may benefit from further size adjustments to maintain optimal readability.

• Multilingual support: When displaying content in languages that use different writing systems, additional considerations for font rendering and spacing may be needed.

More research needed:

More user research is needed in the following areas:

• Performance impact of font loading strategies for the Lexend variable font family across different browsers and devices

• User preferences regarding optimal line length across different contexts and content types

• Effectiveness of different paragraph styles for improving comprehension of complex information

• Reading patterns and preferences for multilingual users accessing content in multiple languages

Help improve this component:

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

• Contribute to our paragraph component discussion

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

• Propose a change to the paragraph component

Check out our to learn more.

Resources:

• Storybook

• GitHub

References:

• The Reading Teacher - Research on reading fluency and text formatting

• Lexend.com - Research on font readability and cognitive processing

• Australian Government Style Manual - Guidelines for clear writing and content structure

• Nielsen Norman Group - Research on reading patterns and optimal text presentation

Changelog:

The paragraph component has evolved through various iterations of the CivicTheme design system to improve readability, accessibility and usability. Key changes include refinements to spacing, responsive behavior, and typography settings.

Contact us:

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

Accordion

The Accordion component provides a space-efficient way to display content in collapsible sections. This is ideal for FAQs, instructional content, and for reducing page length.

Using component

The "Title" will appear as a text on the collapsed Accordion panel header.

The "Content" will appear and the content area of the Accordion panel. If the Accordion is not set to be expanded, the content will be hidden initially.

Expanding Accordion panels

By default, Accordion panels are collapsed. To expand any Accordion panel, check the "Expanded" checkbox. [screenshot of admin UI here]

This will result in accordion looking like this [need to update this phrase] [screenshot of FE UI here]

To expand all panels, check the "Expand all" checkbox. This will override the values set in "Expanded" checkbox for each Accordion panel.

Styling

Theme

Every component in CivicTheme, such as the ["Content"] component, can be shown as a Light or Dark theme component variant. This allows you to build more engaging landing pages with a mix of light and dark components. Use "Theme" radio button selector to change between themes.

Vertical spacing

Vertical spacing adds space before, after or both before and after a component. It is used to visually separate a component from other components when they are vertically stacked on the page. Use "Vertical spacing" dropdown to chose the appropriate values.

You may need to adjust the vertical spacing on adjacent components to create visual balance.

Background

Setting a background on a component can make the component visually stand-out on the page. Check the "Background" checkbox to apply a background to the component.

[Note: not all components have a background, in the case where the Theme sets the background colour of the component. In these cases do not include this section]

Configuring

The component can be configured on the theme settings page located at /admin/appearance/settings/<site-name>. You would need to be logged in as a user with a Site administrator role in order to making such changes.

Summary length

The Summary length setting allows to set the length of the content shown as the summary on the card. For cases when the card is used to display the referenced content with large amount of content, the automated summary length trimming to a pre-set length can help to avoid cards of the large size.

When the length is set, the content will be trimmed to the set length of characters and an ellipsis (…) will be added to the end of the text

On the theme settings page:

1. Scroll down to the 'Components' section and select the Promo card.

2. Enter the number of characters to trim into the Summary length field or enter 0 to disable this f

3. Press Save configuration

[screenshot of the admin form with the Promo card tab selected]

CivicTheme can be installed on GovCMS SaaS using either an automated script or manual installation process.

Installation methods

Automated installation (recommended)

The automated installation script is the preferred method for setting up CivicTheme on new GovCMS SaaS project. It handles most of the setup process automatically, including:

• Downloading and extracting CivicTheme

• Configuring required modules

• Creating your custom subtheme

• Optionally provisioning content blocks

For those who prefer more control over the installation process or cannot use the automated script, the manual installation guide provides step-by-step instructions for:

• Setting up your local environment

• Installing CivicTheme and dependencies

• Creating and configuring your subtheme

• Building and deploying assets

Post-installation steps

Instructions on how to provision CivicTheme's default content blocks and menus, whether you're using automated or manual installation.

Before you begin

Regardless of which installation method you choose, ensure you have:

• Access to GitLab project

• Support ticket to enable config imports actioned

• Administrator role added to your user in production

• All installed

Where to get help

See section for support options and resources.

Next steps

After installation, it is recommended that you read the documents on how CivicTheme works and how to customise your sub-theme installation:

High level definition

Field Description provides supplementary information below form field labels to help users understand input requirements and context, with configurable sizing to support various form layouts.

When to use

A horizontal filtering component that allows users to apply a single filter attribute at a time to refine content displayed on a page.

When to use

Use the Single Filter component when:

• You need to provide users with a straightforward way to filter content by a single attribute or category

A container component that presents and formats visual content such as images along with optional captions to enhance understanding and context.

When to use

Use the Figure component when you need to:

• Display content images that require captions or additional context

A tooltip provides contextual information or explanatory text when users hover over, focus on, or tap an element.

When to use

Use tooltips when:

• You need to provide additional information about UI elements that may not be immediately obvious to users