Supported versions

We follow a N and N-1 supported version model.

We support the current and prior minor release of CivicTheme and their accompanying UI Kit. This means that if the latest release is 1.8.1 we are supporting the following:

• 1.8.1 (latest release)

• 1.7.4 (last minor release)

But we are not supporting 1.8.0 or 1.7.3 and below. In addition to the above model, we will also make available security release patches for the 1.4 version of CivicTheme and 0.9 version due to the difficulty in updating from these models.

Reporting a vulnerability

The CivicTheme team and community take all security bugs in CivicTheme seriously. We appreciate your efforts to responsibly disclose your findings, and will make every effort to acknowledge your contributions.

If you’ve found a vulnerability, we would like to know so we can fix it. Email civictheme@salsa.digital with details of the vulnerability.

Alternatively, information is provided below for disclosing security vulnerability for the Drupal theme and UI Kit.

How to report

• Use the GitHub Security Advisory "Report a Vulnerability" tab to report the ema

• Emailing us at civictheme@salsa.digital

• Contacting us on Slack

What to detail in a disclosure

• a brief description of the vulnerability

• the CivicTheme version(s) the vulnerability affects

• repository / website where the vulnerability can be observed

• non-destructive steps to replicate the bug

The security team will may ask for additional information or guidance. Report security bugs in third-party modules to the person or team maintaining the module.

Drupal Theme security disclosures

Use the CivicTheme’s Drupal Project Report a Security Issue issue tracker.

What happens when a vulnerability is reported

When the security team receives a security bug report, they will assign it to a primary handler. This person will coordinate the fix and release process, involving the following steps:

• Confirm the problem and determine the affected versions

• Audit code to find any potential similar problems

• Prepare security releases for supported versions

• Prepare patches for earlier supported versions

Notifications and releases

We will provide notifications of security releases and vulnerabilities through the following channels:

• slack: #civictheme-designsystem

• CivicTheme Project on Drupal.org

• CivicTheme UI Kit on GitHub

Where to get support

• Drupal theme issue queue

• CivicTheme Github repository

• Drupal Slack channel #civictheme-designsystem

• Send an email to civictheme@salsa.digital

Where to submit issues and PRs

Development of the entire CivicTheme ecosystem is managed in the CivicTheme GitHub organisation.

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

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

For Drupal theme:

• Submit issues to the Drupal theme issue queue

• Submit PRs to the GitHub Drupal monorepo

For Drupal modules:

• submit issues to the Drupal theme issue queue

• submit PRs to the GitHub Drupal monorepo

For UI Kit:

• Submit issues to the UI Kit GitHub repository

• Submit PRs to the UI Kit GitHub repository

For this documentation:

• Submit issues to the documentation GitHub repository

• Submit PRs to the documentation GitHub repository

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

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.

Partnering with CivicTheme

If you would like to collaborate on CivicTheme, particularly for large contributions like developing a version for another technology (e.g., React, Vue, etc.), the following guidelines will help ensure a smooth process and productive partnership:

1. Proposal submission

Before any major development begins, it’s important to present your idea to the broader CivicTheme community for consideration. This will ensure that the proposed work aligns with the current vision and standards of CivicTheme. To initiate a partnership:

• Submit a proposal: Provide an outline of your partnership idea via GitHub (e.g., in the form of an RFC or issue) or directly reach out to the CivicTheme team at info@civictheme.io.

• Include details such as:

  • Goal: What is the purpose of your proposal (e.g., creating a React version of CivicTheme)?

  • Scope: What components or parts of the system would this impact?

  • Resources: How will your team contribute (e.g., developers, designers, testers)?

  • Timeline: Provide a rough estimate of timeframes for the proposed work.

2. Community and governance review

Once the proposal is submitted, it will be reviewed by the CivicTheme governing body, which includes key stakeholders from government agencies, digital agencies, and the broader CivicTheme community.

The review process includes:

• Discussion and feedback: Your proposal will be discussed in community meetings and may receive feedback or suggestions for modification.

• Community involvement: Depending on the scope of the proposal, input from the broader community may be solicited to ensure the change aligns with CivicTheme's goals.

3. Partnership meeting

For large-scale contributions like developing a React version of CivicTheme, it will be necessary to hold a partnership meeting with the CivicTheme core team and stakeholders. This meeting will allow for deeper discussion on:

• Technical approach: How will the new version (e.g., React) be structured, and what are the technical requirements?

• Alignment with CivicTheme principles: Ensuring that the new version adheres to the same accessibility, design standards, and component structure as the original.

• Governance and maintenance: Defining responsibilities for ongoing maintenance and updates, and ensuring the new version has long-term support.

• Community benefits: Evaluating how the new version will support the wider CivicTheme community and government users.

The CivicTheme governing body will provide feedback and give approval before moving forward.

4. Development and implementation

Once the partnership has been approved, development can proceed with continued community involvement:

• Open development: Keep the development of the new version open and transparent, using GitHub for version control, issues, and pull requests.

• Regular updates: Provide regular progress updates to the CivicTheme community, either through GitHub, Slack, or dedicated community meetings.

• Collaboration: CivicTheme is built on collaboration, so invite input and feedback from other developers and contributors during the development process.

5. Testing and quality assurance

CivicTheme adheres to government-grade standards for accessibility, security, and performance. Any new partnership should ensure that:

• The new version (e.g., React) follows the WCAG 2.2 AA accessibility guidelines.

• It is tested for cross-browser and cross-device compatibility.

• The new components match the design and behaviour of existing CivicTheme components.

Community testing and feedback will be encouraged to maintain the highest standards of quality.

Why partner with CivicTheme?

Partnering with CivicTheme offers numerous benefits:

• Contribute to the open-source community: Your work will be part of a growing ecosystem used by government agencies and organisations to deliver accessible, consistent digital experiences.

• Shape the future of CivicTheme: Your partnership could drive the expansion of CivicTheme into new technologies, helping it reach a wider audience and be more adaptable across platforms.

• Collaborate with experts: Work alongside a community of government, digital agency, and open-source experts, sharing insights and knowledge to build something impactful.

Get involved

If you're interested in partnering with CivicTheme, start by submitting your proposal or reaching out to discuss your ideas:

• Submit a proposal via GitHub or contact us directly at info@civictheme.io.

• Join the CivicTheme Slack Channel to participate in ongoing discussions and engage with the community.

We welcome contributions from all who want to collaborate on building better, more inclusive digital solutions.

Summary

Partnerships are key to CivicTheme’s growth and sustainability. Whether you’re developing a new version for React or expanding existing functionality, collaboration with the CivicTheme governing body ensures alignment with the broader vision and standards. By following the process outlined here, your partnership can help CivicTheme thrive and benefit the entire community.

Frameworks supported

Supported browsers

CivicTheme Drupal installation guide

CivicTheme is available as a Drupal theme that enables rapid creation of accessible and consistent digital experiences. This guide walks you through the steps to install and set up CivicTheme in a Drupal project using Composer, Drush, and other typical Drupal tools.

1. Install CivicTheme via Composer

To begin, you'll need to install CivicTheme using Composer, the recommended package manager for Drupal projects.

Run the following command in your Drupal root directory:

This command will add CivicTheme as a dependency in your project, download the theme, and ensure it’s available for use in your Drupal installation.

2. Enable the CivicTheme theme

Once CivicTheme is installed, you can enable it using Drush (Drupal's command-line tool). This will set CivicTheme as the default theme for your site.

Run the following Drush commands:

• drush then civictheme: This command enables the CivicTheme theme.

• drush config-set system.theme default civictheme: This command sets CivicTheme as the default theme for your site.

3. Compile frontend assets (optional)

If you plan to modify the theme's frontend assets (like SCSS or JavaScript), you will need to install the theme’s dependencies and compile the assets.

Navigate to the CivicTheme directory:

Install the required Node.js packages:

Now, compile the assets using the build script:

If you’re actively developing the theme and need live reloading, you can run the following to automatically recompile assets as you work:

Note: The build process will generate CSS and JavaScript files based on the SCSS and JS located within the theme. If you're not planning to customize these files, this step is optional.

4. Configure the theme (optional)

CivicTheme includes a flexible configuration system that allows you to customize various theme settings through the Drupal UI.

To access these settings:

1. Go to Appearance in your Drupal admin.

2. Find CivicTheme and click on Settings.

Here, you can adjust layout options, branding (logos, colors), and other style settings to fit your specific project needs.

5. Managing dependencies and updates

As CivicTheme evolves, you’ll want to keep it up to date to receive the latest features and security fixes. You can update the theme through Composer by running the following command:

This will update the theme to the latest stable version available.

6. Useful development commands

Clear Cache: Drupal’s cache system may sometimes prevent immediate reflection of your changes. Clear the cache using:

Rebuild Theme Assets: If you’ve modified SCSS or JS files and need to recompile assets:

Export Configuration: If you've made theme configuration changes through the Drupal UI, don’t forget to export the configuration to keep everything in sync:

7. Explore CivicTheme components

CivicTheme provides a collection of atomic design components that can be used across your Drupal site. Each component is designed to be accessible and customizable to meet your project’s needs.

You can explore CivicTheme’s components via its Storybook instance:

By integrating these components into your Drupal site, you ensure a consistent and accessible user experience that adheres to WCAG 2.2 AA standards.

Contributing to CivicTheme for Drupal

CivicTheme is an open-source project that relies on community contributions. Whether you're fixing a bug, adding new components, or improving documentation, your help is appreciated.

Subtheme implementation

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:

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:

Updating your Drupal theme

Run the below steps locally:

Update CivicTheme base theme code:

1. Run updates and export the configuration
2. Check if any new regions have been introduced.

3. Re-provision the site with updated configuration.

4. Check that everything looks good.

5. Commit exported configuration files and deploy to the non-production environment for testing.

Tooling update

CivicTheme comes with a starter kit, which contains tooling required to build and integrate sub-theme TWIG, CSS and JS assets into Drupal. This tooling is mostly JS-based and requires regular maintenance.

CivicTheme may ship an update to tooling requiring your sub-themes to update their own tooling. Refer to update notes and update tooling configuration as described.

Although unique scenarios may arise depending on your sub-theme customisations, the most common use case involves regenerating your sub-theme:

1. Move your custom sub-theme directory elsewhere

3. Commit changes

4. Copy your custom sub-theme back

5. Use your git diff tool to accept/decline changes

Usually, you would preserve your own components and assets directories, as they would contain most of the sub-theme customisations, and accept the rest of changed files as updates.

Feedback

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.

CivicTheme overview

CivicTheme is an open-source design system developed through an open-governance model, driven by a collaboration of government agencies, digital agencies, and community members who actively use the product. It was created to enable governments and organisations to rapidly build modern, consistent, and compliant digital experiences.

CivicTheme's development is shaped by contributions from the community, ensuring it evolves to meet the needs of various sectors. Initially developed as a Drupal theme, CivicTheme aspires to support a broader range of languages and frameworks in the future.

Key components of CivicTheme

CivicTheme is comprised of three key components:

1. Design system

CivicTheme is built around the principles of atomic design, meaning it provides a scalable, reusable set of components that can be combined to build digital interfaces. The Design System exists as both a visual guide in Figma and a component library in Storybook.

2. Supporting tools, policies, and guidelines

CivicTheme is more than just a design system; it also offers a set of supporting tools, policies, and guidelines to ensure a smooth development process, maintain consistency, and promote best practices. This includes:

• Development guidelines to ensure proper integration of CivicTheme components.

• Accessibility standards to ensure components meet government-grade compliance.

• Policies to guide contributions and ensure that every addition aligns with CivicTheme’s inclusive and open-source nature.

3. Community of practice

At the heart of CivicTheme is a community of practice composed of government agencies, digital agencies, and individual contributors. This community actively uses, maintains, and improves CivicTheme.

• CivicTheme relies on community contributions to grow and evolve, with an open-governance model that invites users to participate in shaping the design system.

• Contributors can engage through CivicTheme’s GitHub repositories, its Slack channel, and other community forums to provide feedback, submit enhancements, or suggest new components.

Expanding beyond drupal

Although CivicTheme originated as a Drupal theme, it is designed to be flexible and adaptable to support other frameworks and content management systems in the future. Currently, the Drupal theme provides all the necessary configurations to integrate CivicTheme’s UI Kit components with Drupal CMS. The components aim to meet WCAG 2.2 AA standards, as compliance and accessibility are core features.

Demo sites

To explore CivicTheme in action, you can view a variety of demo sites tailored to different industries:

Resources

Component overview

Existing patterns/components

Interactions and behaviours

Accessibility considerations

User research

Security requirements

Submission details

Feedback

Component overview

Existing patterns/components

References and inspiration

Interactions and behaviours

Accessibility considerations

User research

Security requirements

Technical considerations

Submission details

Feedback

Component overview

Existing patterns/components

References and inspiration

Interactions and behaviours

Accessibility considerations

User research

Security requirements

Technical considerations

Submission details

Feedback

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:

git checkout -b feature/your-feature-name

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

• Medium contributions: Adding new features or extending components.

• Major contributions: Major changes requiring the RFC process.

Regardless of the contribution type, be sure to:

• Write clean, modular code that is easy to maintain.

• Follow established design patterns to ensure consistency with existing components.

• Prioritize accessibility and usability in your changes to meet CivicTheme’s government-grade standards.

Viewing your changes

While developing, you can view your changes in real-time with the development server running:

npm run dev

Make sure to:

• Test your changes across multiple devices and browsers.

• Ensure that the new feature or bug fix works for both desktop and mobile experiences.

• Verify that your changes are responsive and maintain the same level of accessibility.

Commit and push your changes

Once you’ve completed your contribution and confirmed everything works as expected, commit your changes:

git add .
git commit -m "Add new button component with hover state"

Use descriptive commit messages to make it easy for others to understand the purpose of your changes. Then, push your branch to your GitHub repository:

git push origin feature/your-feature-name

Creating a pull request (PR)

After pushing your branch, create a pull request (PR) on GitHub to submit your contribution. This will initiate the review process.

1. Navigate to the CivicTheme repository and click new rull request.

2. Title your PR clearly to describe what it addresses.

3. Link any related issues (e.g., "Fixes #123") to provide context.

4. Describe the changes in detail, explaining what was changed and why.

5. Include screenshots or examples if applicable, especially for design-related changes.

Once submitted, the CivicTheme core team will review your PR.

Code review and feedback

Your PR will go through a review process, during which CivicTheme maintainers and contributors will provide feedback or suggestions. Be prepared to:

• Address requested changes promptly by making updates to your branch.

• Ensure you re-test after making changes to avoid breaking existing functionality.

• Be open to feedback and discussions to improve the quality of the contribution.

Once all feedback is addressed and tests are passing, your contribution will be merged into the main project.

Stay updated

It’s important to keep your fork in sync with the latest updates from the CivicTheme repository to avoid conflicts and ensure you’re working with the most up-to-date code.

To pull the latest changes from upstream:

git fetch upstream
git merge upstream/main

Resolve any conflicts that may arise and push the updated branch back to your repository.

Contributing further

CivicTheme encourages continuous contributions. Whether it’s adding new features, fixing issues, or improving documentation, your input helps the community grow. Regular contributions not only enhance CivicTheme but also give you the opportunity to:

• Build your skills.

• Learn from experienced developers and designers.

• Grow within the CivicTheme community.

Summary of key commands

Feedback

We're always looking at ways to improve our documentation for contributions and rely on your feedback to ensure an enjoyable contribution experience. The best way to give us feedback is to join our Slack channel and chat to us there, or contact us via email!

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.

• Show empathy towards others.

Unacceptable behaviours:

• Sexualised language or imagery, and unwelcome advances.

• Trolling, insulting, or derogatory comments.

• Personal or political attacks.

• Harassment, public or private.

• Publishing others’ private information without permission.

• Conduct inappropriate in a professional setting.

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.

• Challenge ideas, not people: Ask questions and focus on the ideas being discussed without personal attacks.

• Inclusive language: Use stated names and pronouns, and respect others' identities. If unsure, ask respectfully in private.

• Lurkers welcome: Participation is valued, even if just observing. Introduce yourself when joining.

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: User is welcomed, asked to review participation guidelines, and read the backlog.

  • Tier 2: User is gently reminded to stay on topic or follow participation guidelines.

  • Tier 3: Moderator privately messages the user, explaining the issue and offering suggestions for improvement.

  • Tier 4: If behaviour persists, the user is kicked from Slack for at least 24 hours.

• Non-tiered response (immediate ban): Intentionally disruptive users, engaging in bullying or harassment, may be kicked without following the tiered process. Repeated offenses will result in a permanent ban.

• Re-admittance after kick: Users kicked from Slack can message the moderator or another admin to request re-admittance. The kick is not a ban, and disruptive individuals can receive guidance on improving their behaviour and using more inclusive, sensitive language.

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 info@civictheme.io. 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 Slack channel and chat to us there, or contact us via info@civictheme.io!

Intended audience

This content authoring documentation is written with Site Editors, Content Administrators and Site Builders in mind.

Prerequisites

You should be comfortable using WYSIWYG editor and adding/editing content via the web interface.

Having prior content administration experience with Drupal or GovCMS is a bonus.

Prior HTML/CSS knowledge or coding experience is not required.

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 Figma file.

Base components

The foundation of CivicTheme includes variables and tokens that ensure consistency in design, enabling scalable, maintainable, and reusable components.

• Colours

• Background

• Elevation

• Fonts

• Grid

• Icon

• Image

• Item list

• Layout

• Spacing

These base elements define the core design framework, supporting the styling and layout for all components within CivicTheme.

Atoms

Atoms are the simplest, most basic building blocks in CivicTheme. They represent single UI elements and are designed for high reusability across various contexts.

• Back to top

• Button

• Chip

• Content link

• Form control

  • Checkbox

  • Field description

  • Field message

  • Fieldset

  • Label

  • Radio

  • Select

  • Textarea

  • Textfield

• Heading

• Link

• Paragraph

• Popover

• Quote

• Table

• Tag

• Text list

• Toggle

Molecules

Molecules combine two or more atoms to form functional UI elements. These components are slightly more complex and include grouped elements with interactive behaviour.

• Accordion

• Attachment

• Breadcrumb

• Callout

• Event card

• Field

• Figure

• Group filter

• Logo

• Map

• Navigation card

• Next Step

• Pagination

• Price card

• Promo card

• Publication card

• Search

• Service card

• Single filter

• Snippet

• Subject card

• Table of contents

• Tabs

• Tag list

• Tooltip

• Video player

Organisms

Organisms are highly structured, composite components consisting of multiple atoms and molecules working together. These components define the most complex reusable patterns.

• Alert

• Banner

• Campaign

• Carousel

• Footer

• Header

• List

• Message

• Mobile navigation

• Navigation

• Promo

• Side navigation

• Skip link

• Slider

• Social links

Why this hierarchy matters

The clear categorisation of components within CivicTheme supports:

1. Reusability: Ensures consistent implementation across various projects.

2. Maintainability: Simplifies updates and modifications with minimal disruption.

3. Scalability: Easily extendable for new use cases, frameworks, or jurisdictions.

By adhering to atomic design principles, CivicTheme empowers designers and developers to create accessible, compliant, and scalable digital experiences for governments globally.

For more details, explore the Figma File.

This page is in development.

Contributing to CivicTheme follows a clear process to ensure that all additions meet community and technical standards. This guide will help you understand the various levels of contributions—small, medium, and major—along with the associated requirements and steps for each.

Overview of the contribution process

Before you start contributing to CivicTheme, review our contribution model. This model shows you how to consider your contributions so that they can be routed and managed properly.

CivicTheme welcomes contributions in various forms, from small enhancements to more complex components. The process is designed to assess whether an existing component fulfils the needs, or if a new contribution is necessary. Contributions are categorised into three levels:

• Small contribution

• Medium contribution

• Major contribution

This document outlines each level of contribution and provides guidance on how to determine the most appropriate level for your proposed changes.

Small contribution

A small contribution typically involves minimal changes, such as small adjustments to existing components or minor bug fixes. This type of contribution is most often used when:

• A solution already exists in the component library.

• The existing component can be easily extended with minimal code changes.

What we need from you:

• Minimal documentation: Provide a brief description of the change, what it fixes or improves, and any references to related issues. User guides will be updated, including compliance, security, or research sections.

• Testing: Ensure your changes do not break existing functionality. Provide tests or manual testing instructions, and ensure you've thoroughly tested prior to submitting.

• Code quality: Maintain consistent code style with the existing CivicTheme codebase.

When to propose a small contribution:

• If a component or solution already exists and only minor tweaks are needed.

• If the functionality of a component is extended without affecting its broader use.

Example small contributions:

• Fixing a CSS alignment issue on an existing button.

• Adding a small utility class to a component for accessibility.

How to submit:

• Follow the basic contribution guidelines and submit your pull request (PR) via GitHub.

• Reference related issues or discussions if applicable.

Medium contribution

A medium contribution is necessary when your proposed changes require extending an existing component or creating a new feature that addresses a specific need but does not yet have a broader application.

What we need from you:

• Documentation: Provide a detailed explanation of the contribution, including use cases, and reference designs or discussions.

• Testing: Provide thorough test cases to ensure the contribution works in all expected environments, ensuring you've tested your changes prior to submitting.

• Broader Use: Clarify if the new feature can evolve for wider usage across the CivicTheme system.

When to propose a medium contribution:

• If the existing component cannot be extended easily and requires more significant changes.

• If others can potentially reuse the new feature, but it is initially being built for a specific purpose.

Example medium contributions:

• Adding a new input field type to the form component with validation.

• Creating a new, reusable layout option for a specific website section.

How to submit:

• Provide more detailed documentation in the PR, explaining the purpose and broader application possibilities.

• Ensure full test coverage and reference any designs or issues.

• Submit via GitHub with a link to the related issue or proposal.

Major contribution (RFC process)

Major contributions involve significant changes to CivicTheme, such as new components, removing existing features, or altering fundamental design principles. These changes require broader community discussion and approval through the RFC process.

When to use the RFC process for major contributions:

• Introducing new components or patterns.

• Adding new API surface areas or modifying major existing APIs.

• Removing features already released.

• Creating new conventions or design principles.

What we need from you:

• Comprehensive documentation: A detailed breakdown of the problem, proposed solution, and how the contribution fits into the broader CivicTheme structure. Include mockups, wireframes, or other design assets if applicable.

• Broader use: Ensure the new component is designed with reuse in mind, following design principles that support various use cases across the system.

• Extensive testing: Rigorous testing in various environments and edge cases is required to ensure the component is robust and can be maintained. Please provide test cases that reviewers can test as well.

When to propose a major contribution:

• If there is no existing component or solution that can be easily extended or adapted.

• If the new component is expected to be used broadly across different applications or sites.

Example major contributions:

• Creating an entirely new navigation component for CivicTheme.

• Proposing a large design system change that requires updates to multiple components.

How to submit:

• Open a discussion in the CivicTheme community forums, Drupal.org, or GitHub discussions to gather feedback before coding begins.

• Submit a detailed proposal and follow the community approval process.

• Once approved, develop the contribution, ensuring thorough documentation and testing before submitting a PR on GitHub.

Hardcoding vs contributing

In some cases, a solution may only be applicable to a single website or application. In such instances, hardcoding the solution directly may be more efficient than contributing a reusable component. However, whenever possible, contributions should aim for reusability within the broader CivicTheme ecosystem.

When to hardcode:

• When a solution is too specific to be reused across other projects or cannot be made generic.

Example:

• Adding a one-off feature or custom styling for a single website section that does not fit CivicTheme's broader design principles.

By following this guide, you can ensure your contributions to CivicTheme are aligned with the project's goals and community standards. Contributions, whether small or large, help improve the system and provide value to all CivicTheme users.

Ensure you follow the appropriate process based on the type of contribution you're making and provide all necessary documentation and testing before submitting your work.

Contribution FAQs

Feedback

We're always looking at ways to improve our model for contributions, and rely on your feedback to ensure an enjoyable contribution experience. The best way to give us feedback is to join our Slack channel and chat to us there, or contact us via email!

The header section appears at the top of your website. It comprises:

1. Site slogan

2. Header logos

3. Secondary navigation

4. Primary navigation

Configuring the Header

When you apply the Theme, it's applied to all four above mentioned sections of the header.

To apply the Light or Dark theme to the Header go to /admin/appearance/settings/<site-name> and use the radio buttons.

In this section you can also configure the Logo type.

Header examples

The examples below illustrate the Light and Dark theme applied to the header.

Note: the below examples only illustrate the Light and Dark theme, these don't give examples of the Header logo options. Go to the Header logo page for more logo examples.

Light theme desktop

Light theme mobile

Dark theme Inline (logo) desktop

Dark theme Inline (logo) mobile

Dark theme Inline stacked (logo) desktop

Dark theme Inline stacked (logo) mobile

Global settings such as Favicon, Colours, Logos, Site Slogan, Header, Footer, Navigation, character limits on cards, and more, can be configured in the "Settings" section.

Accessing the CivicTheme settings page

You must be logged in with the "Site administrator" role to access this page.

1. Go to /admin/appearance/settings/<theme-name>

The Favicon is used in the browser tab. It's the small icon which is often a representation of the logo of brand.

Add / update a Favicon to your site

1. Go to the theme settings page /admin/appearance/settings/<site-name>

2. Find the 'Page element display' at the top of the page and ensure the checkbox is filled (the 'Favicon' section won't display if the 'Page element display' box isn't filled).

3. Then do one of the following

   1. Check the box the 'Use the favicon supplied by the theme'

   2. Paste the relative path in the 'Path to custom icon'

   3. Select Choose file to upload a new favicon.

Contributing in Figma

Contribution criteria

The CivicTheme atomic design system is built on a set of UI building blocks. All of the CivicTheme components, patterns, icons and solutions are:

• Compliant with Australian Government design system

• Built with WCAG 2.2 AA compliance in mind to meet accessibility standards

• Adaptable with GovCMS Drupal 10 out-of-the box

• Responsive

Consider the criteria below before submitting your contribution for consideration:


• Purpose: New designs should address specific needs, enhance user experience, and add value. They should either extend existing patterns or create new ones.

• User researched and tested: Your contribution should be backed by user research and testing.

• Accessibility tested: Your design should meet WCAG 2.2 AA accessibility standards or higher.

• Atomic design: Contributions should comply with atomic design principles to maintain consistency and modularity whilst aligning to existing design direction.

How to contribute

Once you've established the type of contribution you wish to make, submit your design idea via GitHub to ensure transparency and community discussion.

1. Create a GitHub account (if you don’t have one).

2. Go to the CivicTheme UI Kit Project and check for existing issues related to your idea.

3. If your idea isn't listed, create a new issue, using the relevant specification, and we’ll review it.

Contribution formats

Ideally, design contributions should be supplied as fully realised Figma files and submitted via GitHub; however, we know this is not always possible, so there are other options.

With that in mind, the CivicTheme team will consider contributions in many formats:

• Figma file: A copy of the full CivicTheme Figma file, or a stand-alone file that we can merge into the main file.

• Illustration file: If you are adding illustrations or iconography to the UI kit, please provide an illustration file (.svg, .png, or .jpg).

• Wireframe or sketches: This can be a photo of that napkin you sketched your ideas on when inspiration hit.

Working with Figma

If you’re working with a copy of the CivicTheme Figma file, once you’ve finished making changes, you need to export the file in .fig format. To do this, go to "File" and select "Save as .fig." This will save the file on your local drive.

When saving the file, please use the prefix CivicTheme_Design_ then add your name to the end of the file name as shown below.

Example: CivicTheme_Design_[YourName].fig

Submitting your design contributions

Submitting via GitHub:

1. Select contribution type:

   • If it’s a small contribution, such as minor tweaks or updates, select "Bug" or "Minor enhancement" as the issue type.

   • For medium or major contributions, select "Feature request."

2. Title:

   • Include "Design contribution" in the title, along with the specific focus of your contribution. For example:

     • “Design contribution - Template - Homepage - Mobile” or,

     • “Design contribution - Navigation component - Desktop”

3. User story:

   • Fill out the "User Story" section in the issue template to describe the context and reasoning for your contribution. Be clear about the problem you're addressing and the proposed solution.

4. Description:

   • Provide a detailed description of your contribution. Include:

     • Page and name: Reference the page and component name from the Figma file where changes have been made. For example:

       • Page 05 Mobile Templates | Template - Homepage - Mobile.

     • Rationale: Explain the reasoning behind your change. Why is it necessary? How does it improve CivicTheme's design system?

     • Supporting evidence: If your contribution is research-backed (e.g., user testing, accessibility standards), provide relevant links or documentation.

     • Testing: Indicate whether the change has been tested and provide results if applicable (e.g., design QA, browser/device testing).

5. Contribution type:

   • For small contributions, provide a brief summary of changes.

   • For medium contributions, specify if the component can be reused or extended.

   • For major contributions, ensure the description aligns with the broader CivicTheme design principles and can be applied across multiple contexts.

Feedback

We're always looking at ways to improve our model for contributions, and rely on your feedback to ensure an enjoyable contribution experience. The best way to give us feedback is to join our Slack channel and chat to us there, or contact us via email!

The "Site slogan" displays in the header. It's an optional feature.

Add / update the Site slogan

1. Go to /admin/appearance/settings/<site-name>.

2. Scroll down to the 'Components' section and select "Site slogan".

3. Enter your slogan in the 'Content' field.

4. Scroll down and select 'Save configuration'.

CivicTheme allows several Header logo configurations.

You can add up two logos, a Primary and a Secondary logo. The Secondary logo is useful in the case of dual branding, e.g. your Department logo and the Commonwealth Coat of Arms.

Once you have uploaded your logo you can then select how you want the logo/s to display in the Header.

When you set the Header Theme, Light or Dark, you need to consider the logos you've uploaded. If you use the Light theme, your logo needs to be dark enough to be visually accessible on the light background. If you use the Dark theme, you need to ensure you're logo is light enough that it will be visually accessible on a dark background.

Adding / updating logos

The process is the same for the Primary and the Secondary logo.

1. Go to /admin/appearance/settings/<site-name>.

2. Scroll down to Components.

3. Select Logo.

4. Fill in the alt text for the logo first (so you don't forget later).

1. Open the Primary logo dropdown and take note of which logos need to be added for which use: Light and Dark theme, desktop and mobile use.

2. Select Choose file and follow the steps to add the logo. Do this for every logo type for the Primary logo.

1. If you're using a Secondary logo, open the Secondary logo dropdown and follow the same steps.

2. Scroll to the bottom and select 'Save configuration'.

Configure the Header logos

Logo type

Depending on the space within your site's 'Header', you can select how the Logo/s display.

The following table illustrates the different Logo styles using example logos:

• Default

• Stacked (requires two logos)

• Inline

• Inline stacked (requires two logos)

Logo examples in the Header

Light theme desktop

Light theme mobile

Dark theme Inline stacked (logo) desktop

Dark theme Inline stacked (logo) mobile

Summary

The site wide-banner is created using a custom 'Banner' block. The block allows you to select an image display type, set a theme, add a background image with an optional blend mode, and a featured image.

CivicTheme provides one site-wide banner block out of the box. This banner block is shown on every page by default. You can edit this existing Banner block to use on your site or create a new one.

You can override parts of the site-wide banner on a per-page basis. You can also add banner components to the banner on a per-page basis.

Depending on the size of the site you may require more than one site-wide banner block to be used on different sections of the site. If this is the case, the site administrator will need to select which parts of the site to display which banner block.

Editing the site-wide banner block

1. Go to Structure > Block layout or /admin/structure/block/block-content

2. Select the 'Custom block library' tab.

3. Look for 'Banner' in the list of blocks (or use the 'Block type' filter and filter for 'Banner') and select 'Edit'.

Banner block fields

1. 'Block description' is the name of the block. It doesn't display anywhere on the website front end. This can be renamed if you wish.

2. Set the 'Type'. This will be set to 'Default'. Changing to 'Large' will create a diagonal crop effect on the bottom of the background image and change the shape of the featured image (if you have added one).

3. Select a 'Theme', Light or Dark. This affects the background image and the text on the banner. Note: if you choose to add certain banner components (such as a 'Content' component) to individual page banners whilst still inheriting some aspects of the site-wide banner, you will need to pay attention to the theme you have selected on the site-side banner and the theme you select on the components as the text colour on the banner may be affected.

4. Add a background image. By default your CivicTheme site will display a solid colour in the banner background area. The colour will depend on the theme and colours you've chosen for the site. You can override the background colour by adding an image. The theme chosen above will affect this image.

5. Select a 'Blend mode'. This is optional and creates subtle filters on the background image.

6. Add a 'Featured image' if you wish. This will display on the right side of the banner, on top of the background image.

Creating a new banner block

1. Go to Structure > Block layout or /admin/structure/block/block-content

2. Select the 'Custom block library' tab.

3. Click the 'Add custom block' button.

4. Select 'Banner'.

5. Give the block a name in 'Block description' then follow the instructions to edit an existing banner from step 5.

Example banners

The below banner demonstrates:

1. 'Type' set to 'Large'. Note the diagonal crop effect on the bottom of the background image, the shape of the feature image and the coloured block effect behind it.

2. 'Theme' set to 'Dark'.

3. Background image added.

4. 'Blend mode' set to 'Soft light'.

5. 'Featured image' added.

The banner below demonstrates:

1. 'Type' set to 'Default'. Note the effect this has on the background image and the feature image compared to the example above.

2. 'Theme' set to 'Light'. Note the change to the background image and the text colour.

3. Background image added. This is the same background image as the example above.

4. 'Blend mode' set to 'None'.

5. 'Featured image' added. This is the same featured image as the example above.

The Primary navigation is the main navigation for your website. It appears at the top of the page on the desktop below the Secondary navigation.

Creating menu links

How your roles and permissions have been configured will determine who can access and configure the menus. If your roles and permissions are out of the box, then only the Site Administrator (and Administrator) can edit the menus.

The instructions below presume the tech team have already created a Primary navigation, even if there are no menu items in it.

1. Go to Structure > Menus > Primary navigation /admin/structure/menu

2. Find the Primary navigation and select Edit menu

3. If there are no menu links present, select the + Add link button to add your first Menu link.

4. Continue to add menu links

   1. Each new link will be added to the top of the menu and have a default weight of 0.

   2. From there you need to place the link in the correct order.

Ordering menu links

It's recommended to order the menu links as you create them, especially if you have a large menu.

There are two ways to order your menu links:

1. Use the handles to drag the links around to reorder

2. Using row weights to set the weight.

Use handles

Simply grab the handle and drag to the required position. Nest child menu links below the appropriate parent link.

Use row weights

Click Show row weights to change from handles to weights. Open the dropdown to show the weight.

• The lower the weight (e.g. -10) the higher the link will appear in the menu

• The higher the weight (e.g. 10) the lower the link will display in the menu.

Weights are also applied to child menu links.

Enabling menu links

To show a menu link item in the navigation the Enabled checkbox must be filled.

If you want to hide the link from the menu, uncheck the box. If you hide a menu link, any child menu links will also be hidden from the menu.

Configuring the menu style

CivicTheme has three menu styles:

• None

• Dropdown

• Drawer

Note: at the time of writing, the styles None and Dropdown are broken. Examples will be added when these are fixed.

To configure the menu style:

1. Go to the Primary navigation setting at /admin/appearance/settings/[site-name]

2. Scroll down and click to open Navigation

3. In the Dropdown type select the desired style

4. Save the configuration

Drawer

Editing menu settings from the node (page) itself

You can also access menu settings for an individual page from the page itself.

1. Go to the page in question, and enter edit mode

2. On the right side of the edit interface click to open Menu settings

3. Add a Menu link. This is the link that will display in the navigation. If possible, it should match the page title. If the page title is very long you may consider shortening the Menu link.

4. Add a description if desired. The description displays when a user hovers over the Menu link.

5. Select the Parent link by opening the dropdown. If the menu is very large it can be challenging to find the right parent, and it might be easier to do this part in the Primary navigation settings as above.

6. Assign a weight. Again, if the menu is large it might be easier to go to the Primary navigation settings and use the handles to drag it to the right position or view the row weights for the entire menu to know which weight to assign.

The Secondary navigation appears at the very top of the page on the desktop, above the Primary navigation.

This page is in development.

Link options

Open links in a new window

Will open all internal and external links in a new window.

Open external links in a new window

Will only open external links in a new window. Internal links will open in the same window. This is the most common behaviour.

Override external link domains

There might be a reason to treat an external link like an internal link and open it in the same window. If so, follow the instructions and add one domain to exclude per line.

How to change the Link settings

1. Go to /admin/appearance/settings/<site-name>

2. Scroll down to the 'Component' section.

3. Select 'link'.

The 'Skip link' section is an accessibility feature that allows people using assistive technology to skip navigation links by using the 'Skip to main content' button.

Light theme

This illustrates the Light theme skip link and a Light theme menu.

Dark theme

This illustrates the Light theme skip link and a Dark theme menu.

Change the Skip link colour

1. Go to /admin/appearance/settings/<site-name>.

2. Scroll down to the 'Components' section and select 'Skip link'.

3. Select the Theme.

4. Scroll down and select 'Save configuration'.

The Signup component allows you to place a site-wide or per-page sign up block on your site.

This is a Block type of Component. Signup is preconfigured out of the box, you can choose to use it as is or customise the content.

Add a Signup component

1. Go to Content > Blocks > Custom block library or /admin/content/block.

2. Select "Add content block" then "Component".

3. Fill in the "Block description". This is used only to reference the block, it doesn't display on the front end.

4. Open the "Components" dropdown and select "Promo".

5. Fill in the "Title" and "Content". These both display on the front end.

6. Add the "Link URL" and "Link text".

Edit Signup component

1. Go to Content > Blocks > Custom block library or /admin/content/block.

2. Find the relevant "Component" block type. You can filter by'Block description" and/or "Block type".

3. Select "Edit", make the required changes, and "Save".

Styling

Theme

Every component in CivicTheme, such as the "Signup" 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 theme 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.

Configuring

Because the Signup is a Block, you can configure it to display globally. For example, if you want to display the Signup just above the footer on every page, you can configure to display in the Content bottom region.

You must be logged in with the "Site Administrator" role to do this.

1. Go to Structure > Block layout or /admin/structure/block

2. Scroll down to Content bottom

3. Select "Place block"

1. A pop up will open, enter the name of your block.

2. Select "Place block".

1. A pop up will open. In here you can configure the block to stop it displaying on certain pages.

Example of Signup with 'Content bottom' placement

Like the header logo, the footer logo can be configured in a number of different ways. If you have uploaded two logos to your site, on mobile devices they will always stack if you select a logo style that displays two logos.

Configuring the footer logo

The same logos are used in the header and the footer. These instructions presume you have already added logos to the site and just need to configure the display.

1. Go to /admin/appearance/settings/<site-name> or "Appearance" in the menu, find your site and select "Settings".

2. Scroll down the page until you see the "Components" section, and select "Footer".

3. Select from the "Logo type" options:

   • Default

   • Stacked (requires two logos)

   • Inline

   • Inline stacked (requires two logos)

Examples

This table shows the layout of the logos at a glance. In all cases, two logos have been uploaded to the site, but the Footer logo settings determine if both logos or only the Primary logo displays.

Logo examples in the footer

Light theme 'Default' desktop

If you have uploaded two logos to your site and you select 'Default', only the Primary logo displays.

Light theme 'Default' mobile

Social media links and partial footer menu shown here for context.

Light theme 'Stacked' desktop

Light theme 'Stacked' mobile

Dark theme 'Inline' desktop

Dark theme 'Inline' mobile

If you have uploaded two logos to your site, and you select 'Inline', only the Primary logo will display.

Dark theme 'Inline stacked' desktop

Dark theme 'Inline stacked' mobile

If two logos have been added to your site, they will 'stack' when 'Inline' style is selected.

The Footer is a global element that sits at the bottom of every page on your site. Common Footer elements are Logos, Social links, Footer navigation, Acknowledgement of Country, Copyright and Privacy information.

The Footer is created using a series of Blocks. Build your footer using Block types of "Component", "Social Links" and "System".

Some Blocks used in the Footer area available out of the box. You can configure certain settings to suit.

Create Blocks

Before you can build your Footer you need to create all the blocks that will make up the Footer.

From the list below, follow the steps to create the Blocks you wish to use.

The instructions on how to place the Blocks in the correct region are on each page.

Configuring the footer

You will need to be logged in as the "Site Administrator" role.

1. Go to /admin/appearance/settings/<site-name> or Appearance in the menu, find your site and select "Settings".

2. Scroll down the page until you see the "Components" section, and select "Footer".

Theme

Use the Theme radio buttons to set the footer in Light or Dark theme.

Note: the Theme you set here for the global Footer configuration must match the Theme you set on the Blocks you're using to create the Footer. For example, you must set the "Social links" Block to Dark if you set your Footer Theme to Dark.

Background

You can choose to display a background image on your footer. However, keep in mind that a detailed image could create issues with accessibility if the written content in the footer can't be read on top of the image.

1. In the "Footer background image path" section, upload a background image, or paste in the path to the image if it's already in the media library.

Footer examples

Note: The footer column headings are switched off in these examples, further screenshots to come to illustrate the footer column headings.

Light theme Default desktop

Light theme Default mobile

Light theme Stacked desktop

Light theme Stacked mobile

Dark theme Inline desktop

Dark theme Inline mobile

Dark theme Inline stacked desktop

Dark theme Inline stacked mobile

CivicTheme allows you to change the colour of all elements from the configuration page without additional development.

To enable this functionality, check "Use Colour Selector". If not selected, the default CSS will be used.

There are 2 visual themes available: Light and Dark. These are the visual themes consisting of Palette Colours that every component can be shown as.

Palette Colours are named after the purpose of the colour: Heading defines the colour of all headings, while Background defines the background colour.

Some colours are represented in different variants: Border light, Border, Border dark. This is to allow more visual variety on component colours.

Every component has a mapping to a set of designated colours based on the element the component uses.

Brand colours

The Brand colours use predefined formulas that automatically update the Palette colours. In other words, if you change the brand colours then the corresponding dependents will automatically update.

This is used as a short-hand to set 14 Palette colours using only 3 Brand colours. It also allows us to quickly produce Palette colours if only Brand colours are provided.

Brand colours is only a "helper" tool. Every Palette colour value produced from the Brand colour can be overridden.

To see which Brand colours drive which Palette colour, check the "Show dependents" checkbox under the Brand colour.

This page is in development.

Out-of-the-box, CivicTheme comes with 3 content types:

• Page

• Event

• Alert

These are the most common content types that you need to start. You can add more content types as necessary.

Page

The 'Page' content type is the most flexible content type.

Choose from a wide range of CivicTheme out-of-the-box components to build pages.

Event

The 'Event' content type allows you to add event pages that display event details, date, location and map.

Alert

You can add an 'Alert' to any page or section of your site. A horizontal Alert bar will display at the top of the webpage above the Header.

You can create a social links block and apply it site-wide, or apply it on a per-page basis.

CivicTheme comes with a set of social media icons for Facebook, LinkedIn and Twitter. You can upload other social media icons for different platforms. These must be in SVG format to ensure your brand colours will be applied.

Note on theme settings: If you set your social media link block to display in the footer aligned with the footer logo, you need to ensure you set the theme, Lightor Dark,the same for the logos and the social links.

Create a Social links block

1. Go to the Content > Blocks, or /admin/structure/block/block-content

2. Click Add custom block

3. Select 'Social links block'

4. Select the 'Light' or 'Dark' theme

5. Choose an exisiting icon (for Facebook, LinkedIn or Twitter), or, upload a new icons for other social media platforms (note: these must be .svg files)

Edit existing social links block

If you need to add, remove, or edit a social media icon or link, or change the theme:

1. Go to Content > Blocks, or /admin/structure/block/block-content

2. Find the 'Social links' block

3. Select 'Edit'

This page is in development

This page is under development.

The 'Page' content type is the most flexible content type.

This content type allows you to choose from a wide range of CivicTheme out-of-the-box components to build a striking landing page or a simpler content page. The style of the page depends totally on how you use the components.

Create a Page

1. Go to /admin/content

2. Select Add content\
3. Select 'Page'\

You now have a page with a Content tab and a Banner tab.

Set up the page essentials

Most fields are empty when the page is first created. There are some compulsory fields that must be filled before you can save the page, and some other important items to configure now.

Note there is a Content tab and a Banner tab. Go to Banner to read more about configuring a per-page banner.

1. Add the page title in the Title field

2. Add the Summary. This displays in teasers and within links.

3. If you want a 'Table of contents' to display, select the checkbox. The TOC will display at the top of the page.

Components

CivicTheme has many out-of-the-box components.

Go to Components to learn how to configure components to build your page.

Appearance

Add a thumbnail image, set the vertical spacing, hide sidebar and tags.

Thumbnail

Add an image for cards and teasers that link to this page. Every time you link to this page using a component that has an image field, it will use this image.

Vertical spacing

Vertical spacing allows you to add some extra white space at the top or bottom of the page, or both.

• Top: between the bottom of the banner and top of the H1

• Bottom: above the footer

• Both: both of the above.

Open the Vertical spacing dropdown and select from None, Top, Bottom, Both.

Hide sidebar

Select this if you want to hide the sidebar. This will cause the content and components to display full width of the page, removing the default gutter, or sidebar, on the left and right sides.

Menu settings, Last updated date, URL alias and Promotion options

Find these settings on the right side of the interface.

Menu settings

To place the page within the site menu, open the 'Menu settings' section. By default the page is not in the menu.

1. Check 'Provide menu link' to open the menu link fields.

2. Enter the 'Menu link title'. This is usually the page name and will display in the menus.

3. Add a description if you like, this displays when hovering over the menu link.

4. Open the 'Parent link' dropdown and select the parent of this page.

5. The 'Weight' determines the order in which each page displays below their parent page. The lower the weight the higher the position in the menu. You can also configure the order of the site menu in /admin/structure/menu.

Last updated date

By default the 'Last updated date' is checked to display on the page. It will automatically display the last published date. Uncheck the box if you don't want to display the last updated date.

If you want to customise the date, use the date picker.

URL alias

The URL alias is set to generate automatically. It uses the page title and the menu structure to create the URL alias.

To override the automatic URL alias, uncheck the box and add the alias to the URL alias field.

Authoring information

Automatically records who created the page and on which date. There is usually no need to modify this setting.

Promotion options

Promote to the front page (homepage) to display a teaser or card and stick at the top of lists.

Alerts provide information for site users using a horizontal bar at the top of the screen. Common examples are announcements, notices, warnings, downtime alerts or any other alerts that you want your site visitor to see right away at the top of the page.

Depending on which "type" you select, the Alert background colour will be different:

Alerts can be set to appear on all pages on the site or only on selected paths. They can also be scheduled to appear only within a specific date range.

Once a website user dismisses an Alert by pressing on the close Button (x), the alert will no longer appear when a user visits this page again. The alert, however, will be displayed again if the content changes (e.g. if some important information needs to be added to an existing Alert).

You can use the Event content type to create events that span across multiple dates.

When you add an Event, there are 2 tabs: Content and Event.

The fields for the Content tab are shown below:

The fields for the Event tab are shown below:

You can see the final output for an Event with a Map component below:

CivicTheme comes with many out-of-the-box components you can use to build your website.

Which component to use

There is no right or wrong component to use, it depends entirely on what you're trying to output.

To get started, we recommend clicking on the Storybook links below to visualise each component and experiment with some basic configurations. This will help you decide which component fits your needs.

To read guidelines on how to configure and implement each component, click on the link in the Documentation column below.

Summary

The Accordion component allows you to add collapsible sections of content. You can specify the default state (expanded or collapsed) in the Accordion settings.

This section shows you how to add accordions.

Below you can see two accordions, one in its expanded form, and the other one collapsed.

Step 1 - Add the Accordion component

Click on “Add Accordion” as shown below.

Step 2 - Add an Accordion panel

Add content for your Accordion using the fields shown below.

1. Title - Add the title.

2. Content - Add the body text.

3. Expanded - Check this box to force the Accordion panel to be expanded by default.

4. Add Accordion panel - Click this button to add additional Accordion panels.

5. Expand all - Check this box to force all Accordion panels to be expanded by default.

Summary

The Automated List Component displays content that is automatically curated according to predefined criteria and presented in various "teaser" variants: Promo card, Navigation card, Snippet.

This section shows you how to add an Automated list.

Below is an automated list. The content is being pulled from existing pages and displayed as `Promo card` components.

How to add an automated list

Step 1: Go to the page you'd like to add the automated list to (or create a new page) and in the Content tab, Components section, select Automated list from the dropdown list.

Step 2: Fill in the information for the Content tab as per below.

1. List type - controls how the content is aggregated . Out-of-the-box, CivicTheme comes with one list type. However, site administrators can set up different types of lists, that can then be selected from this dropdown.

2. Content type - filter content by the content types.

3. Metadata - further filter content by topic or site section.

4. Limit - how many results to display: unlimited or limited to the specified number.

5. Filters - choose to display filters at the top of the the automated list component.

Step 3: Fill in the information for the Fields tab as per below.

1. Title - You can add a title to the automated list, such as 'Latest news'.

2. Content - You can also add introductory text to the automated list.

3. Link above - Aadd a link at the top of the automated list. See the screenshot below for an example.

4. Link below - You can also add a link below the automated list.

The screenshot above shows an automated list limited to three results, with the title of 'Latest news'. It also has a 'link above', which is highlighted.

Step 4: Fill in the information for the Appearance tab as per below.

1. Theme - Select light or dark theme.

2. Vertical spacing - Add vertical spacing to the component if you'd like. Choices are none, top, bottom or both)

3. Background colour - Check the box to apply a default background colour from your colour palette.

4. Columns - Select how many columns to display (e.g. the screenshot above of 'Latest news' has three columns)

5. Items - Choose whether to display the list items as Navigation cards or Promo cards, and whether the cards will use the light or dark theme.

Select the 'Banner' tab to customise the banner on a per-page basis.

By default all pages on your site will inherit the site-wide banner settings.

Banner type and Banner theme

If you want to deviate from either of these site-wide settings, select the relevant radio button.

Override the Banner title

You can override the title that displays in the banner by entering a new title in the 'Banner title' field.

Adding a Banner title doesn't override the breadcrumb or the URL alias. They will use the Page title unless you manually configure them differently.

Hide breadcrumb

The breadcrumb displays by default. Check 'Hide breadcrumb' to hide it.

Background

Your site will inherit the site-wide background. If you want to change this on your page, open the Background widget and upload a new background. You can also update the 'Blend mode' on the background.

Featured image

If your site-wide banner has a Featured image, it means that every child page will have a Featured image, you can't remove the featured image on a per-page basis. However you can change the image on a per-page basis in the 'Featured image' widget.

If there are any pages you don't want a Featured image on, you will need to ensure your site-wide banner does not have a Featured image.

Add components to the banner

There are two types of components you can add to the banner. 'Banner components' which display on the banner itself. And 'Bottom banner components' which display below the banner.

Banner components

You can add the following components to the banner and they will display within the banner itself:

Bottom banner components

You can add the following components to the bottom of the banner.