# Introduction Welcome to CivicTheme! CivicTheme is an open-source, government-grade design system led by open-governance with a vision. ## 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**](#id-1.-design-system) 2. [**Supporting tools, policies, and guidelines**](#id-2.-supporting-tools-policies-and-guidelines) 3. [**Community of practice**](#id-3.-community-of-practice) ### 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**. * [**Figma**:](https://www.figma.com/design/HwfKa9eD0oq474wffZYzg4/CivicTheme--Design-System-v1.11) The Figma file is a visual representation of CivicTheme's components and design templates, allowing designers to work directly with pre-built UI elements. * [**UI Kit**](https://github.com/orgs/civictheme/projects/1): The UI Kit is a collection of components built with **HTML, CSS, and JavaScript**, aiming for **WCAG 2.2 AA accessibility standards** out-of-the-box. This ensures accessibility compliance across all digital services that use CivicTheme. * [**Storybook**](https://uikit.civictheme.io/?path=/story/welcome--welcome): Storybook provides a live, interactive environment for developers and designers to explore components, understand their behaviour, and integrate them into different projects. ### 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. ### 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: * [Default CivicTheme build](https://default.civictheme.io/) – Latest stable build. Use the "generated content" menu item to explore multiple component variants. * [Government demo](https://government.civictheme.io/) – CivicTheme adapted for government sector content. * [Higher Education demo](https://higher-education-university.civictheme.io/) – Example of CivicTheme tailored for higher education. * [Corporate demo](https://corporate.civictheme.io/) – CivicTheme for corporate industry content. ### Resources * [CivicTheme official site](https://www.civictheme.io/) * [CivicTheme Figma file](https://www.figma.com/design/HwfKa9eD0oq474wffZYzg4/CivicTheme--Design-System-v1.11) * [UI Kit GitHub repository](https://github.com/civictheme/uikit) * [Drupal Theme Project Page](https://www.drupal.org/project/civictheme/) * [Drupal Theme Development repository](https://github.com/civictheme/monorepo-drupal) * [CivicTheme slack channel](https://drupal.slack.com/archives/C039UV0CQBZ) * [CivicTheme Storybook](https://uikit.civictheme.io/?path=/story/welcome--welcome) ### Supported browsers
BrowserLatest supported versionSupported version n-1
Chrome138.x117.x
Firefox141.x119.x
Microsoft Edge138.x118.x
Safari18.x16.x
### Contribute **CivicTheme** continues to evolve as an essential tool for delivering consistent, accessible, and modern digital experiences, driven by its community and contributions. To be part of the evolving journey of CivicTheme's vision, check out our [contribution documentation](/contributing/contribution-model). # Getting help ### Where to get support * [Drupal theme issue queue](https://www.drupal.org/project/issues/civictheme) * [CivicTheme Github repository](https://github.com/civictheme) * [Drupal Slack channel](https://drupal.slack.com/archives/C039UV0CQBZ) #civictheme-designsystem (**note:** you need to first [join Drupal Slack](https://www.drupal.org/join-slack)) * Send an email to ### Where to submit issues and PRs Development of the entire CivicTheme ecosystem is managed in the [CivicTheme GitHub organisation](https://github.com/civictheme/). 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 ](https://en.wikipedia.org/wiki/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](https://www.drupal.org/project/issues/civictheme) * Submit PRs to the [GitHub Drupal monorepo](https://github.com/civictheme/monorepo-drupal) **For Drupal modules:** * submit issues to [the Drupal theme issue queue](https://www.drupal.org/project/issues/civictheme) * submit PRs to [the GitHub Drupal monorepo](https://github.com/civictheme/monorepo-drupal) **For UI Kit:** * Submit issues to [the UI Kit GitHub repository](https://github.com/civictheme/uikit) * Submit PRs to [the UI Kit GitHub repository](https://github.com/civictheme/uikit) **For *****this***** documentation:** * Submit issues to [the documentation GitHub repository](https://github.com/civictheme/docs/) * Submit PRs to [the documentation GitHub repository](https://github.com/civictheme/docs/) If you do not know which part the issues relates to - submit an issue to [the Drupal theme issue queue](https://www.drupal.org/project/issues/civictheme) and it will be moved to the appropriate location by the CivicTheme maintainers. # Security framework {% hint style="info" %} **Need to report a vulnerability?** Find out how on the [Drupal CivicTheme Design System](https://www.drupal.org/project/civictheme) page. {% endhint %} 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. * PHPStan: a static analysis tool for PHP that detects errors in code without running it. Helps catch bugs, type mismatches, and potential issues early, improving code quality and reliability. * PHP Mess Detector: Scans PHP code for potential problems such as bugs, suboptimal code, and maintainability issues. Helps to identify complex, error-prone, or poorly structured code so it can be improved. * PHP Rector: Automates PHP code refactoring and upgrades.Helps to modernise code, fix deprecated features, and enforce coding standards, improving maintainability and compatibility. * Continuous Integration (CI): Every change is validated via automated testing, linting, and standards enforcement. ### 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. * **AI Code Review (CodeRabbit)**: CodeRabbit enhances pull request reviews with automated security checks and best practice enforcement. ### 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 [Drupal CivicTheme Design System](https://www.drupal.org/project/civictheme) 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 * Encouraging community contributions to improve security
# Security update - 1.12.0 Instructions for manual mitigation These instructions require an experienced developer to implement, to be able to test XSS protections and remove the information disclosure issues on entity reference fields. The purpose of these instructions is for users that wish to mitigate the security issues found in CivicTheme (<1.12.0) and manually update their older projects. It is also for those checking their sub-theme for XSS and information disclosure issues. ### Manual instructions ### Key information CivicTheme provides a field API system for retrieving commonly used field values specific to CivicTheme. *We strongly recommend that you use this system solely to retrieve field data for use within components.* Not using this API will mean that the developer is reliant on implementing mitigations for XSS. The following functions are available for use: * `civictheme_get_field_value` - retrieves field values from fields that CivicTheme regularly uses. All field types within CivicTheme are supported and several more. Raise an issue if you require other field types supported. * `civictheme_get_field_referenced_entities` - retrieves and checks access to referenced entities in a field of an entity. Also manages the cacheability metadata for the referenced entities. * `civictheme_get_field_referenced_entity` - retrieves the first referenced entity in a field of an entity. * `civictheme_get_referenced_entity_labels` - retrieves labels of the referenced entities. * `civictheme_embed_svg` - embeds SVG from provided URL. This function does not protect against XSS and relies on appropriate level of user managing SVG Icons. We recommend revieewing the `web/themes/contrib/`civictheme/includes/utilities.inc\` for these utility functions. ### Updates to components We have implemented updates to `heading.twig` and `button.twig` by removing the `raw` filter from the content outputs in these components. Patches below for what change was required of each component: ``` diff --git a/components/01-atoms/heading/heading.twig b/components/01-atoms/heading/heading.twig index a6f95bf4..ab245f70 100644 --- a/components/01-atoms/heading/heading.twig +++ b/components/01-atoms/heading/heading.twig @@ -19,6 +19,6 @@   {% if content %}    -    {{- content|raw -}} +    {{- content -}}    {% endif %} ``` In the latest change this looks like this for `button.twig`: ``` diff --git a/components/01-atoms/button/button.twig b/components/01-atoms/button/button.twig index 708bd62a..332d6ef2 100644 --- a/components/01-atoms/button/button.twig +++ b/components/01-atoms/button/button.twig @@ -45,9 +45,9 @@       } only -%}     {% endset %}     {% if icon_placement == 'before' %} -      {{- icon_markup -}}{{ text|raw }} +      {{- icon_markup -}}{{ text }}     {% else %} -      {{ text|raw }}{{- icon_markup -}} +      {{ text }}{{- icon_markup -}}     {% endif %}   {%- else -%}     {%- include 'civictheme:text-icon' with { ``` These components have changed over time but the intent is to remove raw from content entered data. #### Remove attributes field from iframe paragraph * Create a view to see whether you have any values in Attributes field for Iframe paragraph * Remove the Attributes field (`field_c_p_attributes`) * Delete field.field.paragraph.civictheme\_iframe.field\_c\_p\_attributes * Delete field.storage.paragraph.field\_c\_p\_attributes * Update `\civictheme_preprocess_paragraph__civictheme_iframe` to add any required iframe attributes to the preprocess #### Update Content Author and Approver permission * Remove permission to create, edit Icons media type ### CivicTheme API updates It is the intention of CivicTheme sub-themes that all values used in CivicTheme components should be retrieved using the CivicTheme API and `civictheme_get_field_value` or `civictheme_get_field_referenced_entities` rather than through the Drupal entity field API. CivicTheme uses this API for retrieving all field values for components. * `civictheme_get_field_referenced_entities` * `civictheme_get_field_referenced_entity` * `civictheme_get_field_value` * `civictheme_get_referenced_entity_labels` These changes are adding the build array argument so CivicTheme can manage cacheable metadata but it is easiest to replace each function completely rather than patch in changes. #### Replace `civictheme_get_field_referenced_entities` with updated version ```php /** * Gets the referenced entities in a field of an entity. * * @param \Drupal\Core\Entity\FieldableEntityInterface $entity * The host entity. * @param string $field_name * The entity reference field. * @param array $build * Render array to apply cacheability metadata to. * * @return array * Referenced entities. */ function civictheme_get_field_referenced_entities(FieldableEntityInterface $entity, string $field_name, array &$build = []): array { $trigger_bc = empty($build); if ($trigger_bc) { @trigger_error('Calling ' . __FUNCTION__ . ' without the $build argument is deprecated in civictheme:1.12.0 It will be required in civictheme:1.13.0. Triggered when getting entity for ' . $field_name . '. See https://www.drupal.org/node/3552745', E_USER_DEPRECATED); } if (civictheme_field_has_value($entity, $field_name)) { /** @var \Drupal\Core\Entity\EntityInterface[] $referenced_entities */ $referenced_entities = $entity->get($field_name)->referencedEntities(); if (empty($referenced_entities)) { return []; } $access_checked_referenced_entities = []; foreach ($referenced_entities as $referenced_entity) { $access = $referenced_entity->access('view', NULL, TRUE); $cacheability = $cacheability ?? CacheableMetadata::createFromRenderArray($build); $cacheability->addCacheableDependency($access); $cacheability->addCacheableDependency($referenced_entity); if ($access->isAllowed()) { $access_checked_referenced_entities[$referenced_entity->id()] = $referenced_entity; } } $cacheability->applyTo($build); if ($trigger_bc && \Drupal::service('renderer')->hasRenderContext()) { // The calling code didn't pass a render array that we can attach // cacheable metadata to. There is a render context and $build has had // cacheability metadata added, so we can simply render it, and it will // bubble up to the current theme hook. \Drupal::service('renderer')->render($build); } } return $access_checked_referenced_entities ?? []; } ``` #### Replace `civictheme_get_field_value` with updated version ```php /** * Gets values from fields that CivicTheme regularly uses. * * This function complements the field API system, providing a convenient way to * retrieve commonly used field values specific to CivicTheme. * * If a field type is not listed, and you need to retrieve its value, consider * using the field API system directly. * * @param \Drupal\Core\Entity\FieldableEntityInterface $entity * Entity to check field existence. * @param string $field_name * Field name to get the value for. * @param bool $only_first * Return only the first value of a multi-value field. * @param mixed $default * Default value to return. * @param array $build * Render array to apply cacheability metadata to. * (required for entity reference fields). * @return mixed|null * Whether the field exists and is not empty. * * @SuppressWarnings(PHPMD.BooleanArgumentFlag) * @SuppressWarnings(PHPMD.CyclomaticComplexity) * @SuppressWarnings(PHPMD.ElseExpression) * @SuppressWarnings(PHPMD.StaticAccess) */ function civictheme_get_field_value(FieldableEntityInterface $entity, string $field_name, bool $only_first = FALSE, mixed $default = NULL, array &$build = []): mixed { $value = $default; if (!civictheme_field_has_value($entity, $field_name)) { return $value; } $field = $entity->get($field_name); $field_type = $field->getFieldDefinition()->getType(); switch ($field_type) { case 'boolean': $value = (bool) $field->getString(); break; case 'integer': case 'list_integer': $value = (int) $field->getString(); break; case 'list_string': case 'string': case 'string_long': $value = $field->getString(); $value = Xss::filter($value); break; // Field types where we want to return field item. case 'datetime': case 'daterange': case 'image': case 'link': $list = $field; if (!$list->isEmpty()) { $value = $only_first ? $list->first() : $list; } break; // Field types where we want to return entities. case 'entity_reference': case 'entity_reference_revisions': if ($only_first) { $value = civictheme_get_field_referenced_entity($entity, $field_name, $build); } else { $value = civictheme_get_field_referenced_entities($entity, $field_name, $build); } break; case 'text_long': case 'text_with_summary': case 'text': // Opinionated. // This implementation renders the field if it has a single value. // If the field contains multiple values, it relies on view() to handle // the rendering. if ($only_first) { $field = $field->first(); $field_value = $field->get('value')->getString(); $field_format = $field->get('format')->getString(); $value = empty($field_format) ? $field_value : check_markup($field_value, $field_format); break; } $value = $field->view(); break; } return $value; } ``` ### Replace `civictheme_get_field_referenced_entity` function Update the function with the below: ```php /** * Gets the first referenced entity in a field of an entity. * * @param \Drupal\Core\Entity\FieldableEntityInterface $entity * The host entity. * @param string $field_name * The entity reference field. * @param array $build * Render array to apply cacheability metadata to. * * @return \Drupal\Core\Entity\EntityInterface|null * Referenced entity. */ function civictheme_get_field_referenced_entity(FieldableEntityInterface $entity, string $field_name, array &$build = []): ?EntityInterface { $referenced_entity = NULL; $entities = civictheme_get_field_referenced_entities($entity, $field_name, $build); if (!empty($entities)) { $referenced_entity = reset($entities); if (!$referenced_entity instanceof EntityInterface) { $referenced_entity = NULL; } } return $referenced_entity; } ``` ### Replace `civictheme_get_referenced_entity_labels` function ```php /** * Get labels of the referenced entities. * * @param \Drupal\Core\Entity\FieldableEntityInterface $entity * The host entity. * @param string $field_name * The entity reference field. * @return array * The label(s). * * @SuppressWarnings(PHPMD.StaticAccess) */ function civictheme_get_referenced_entity_labels(FieldableEntityInterface $entity, string $field_name): array { $labels = []; $referenced_entities = civictheme_get_field_value($entity, $field_name) ?? []; foreach ($referenced_entities as $referenced_entity) { if ($referenced_entity instanceof EntityInterface) { $labels[] = Xss::filter((string) $referenced_entity->label()); } } return $labels; } ``` ### Replace `civictheme_embed_svg` ```php /** * Embed SVG from provided URL. * * @param string $url * Local URL or local path to retrieve SVG from. * @param array $css_classes * Array of CSS classes to add. * * @return string|null * Loaded SVG or NULL if unable to load SVG. */ function civictheme_embed_svg(string $url, array $css_classes = []): ?string { $svg_path = DRUPAL_ROOT . (str_starts_with($url, 'http') ? parse_url(str_replace('.png', '.svg', $url), PHP_URL_PATH) : str_replace('.png', '.svg', $url)); if (!file_exists($svg_path)) { return NULL; } $content = (string) file_get_contents($svg_path); if (!empty($css_classes)) { $content = str_replace(',