v7.0.1 — 2022-04-26

Overview

• Accessibility fixes to various templates
• Minor docs updates

Issue List

• CD-359: we ran automated tests on several sites using Check1st and reacted to the test results

Steps to Upgrade

composer require unocha/common_design:^7

If your sub-theme has overridden any of the following templates, you will need to update them manually to integrate the changes:

• navigation/menu--account.html.twig
• navigation/menu--help.html.twig
• navigation/menu--main.html.twig

v7.0.0 — 2022-04-21

Overview

Sass in sub-theme now totally optional. The sub-theme sass has been deprecated and its contents removed. To customize website colors, the sub-theme has a css/brand.css file containing some variables which will dynamically re-color your whole website. To further customize your website we now recommend using Drupal Libraries exclusively to override/extend/replace core and CD base-theme styles. The Sass tools still exist to provide a transition period.

SVG Icon Sprite customization now driven off a template. Beforehand, if you wanted to customize the SVG sprite, you had to implement a preprocess hook. That's no longer the case, and a template override is now available. It's far easier to implement, and brings caching benefits.

Issue List

• CD-355: removal of Sass color variables in base-theme, removal of Sass from sub-theme, added the css/brand.css files to base-theme and sub-theme. #304 #311
• CD-373: migrated SVG overrides from preprocess hook to template override. #309
• CD-380: added configuration to skip the git tag when creating releases. #314

Steps to Upgrade

Run composer require unocha/common_design:^7.0

Verify your SVG icon sprite still functions

We've documented various upgrade paths:

Case 1: site without icon sprite or html template overrides

1. Update the base theme.
2. Optional: copy the following base-theme files into your sub-theme, in case you want to override the SVG sprite in the future:

• templates/layout/html.html.twig — edit the include to reference sub-theme CD Icon template.
• templates/cd/cd-icons/cd-icons.html.twig — edit the include to reference sub-theme SVG sprite.
• img/icons/cd-icon-sprite.svg

Case 2: site with icon sprite override but no html template override

1. Update the base theme.
2. Copy the sub-theme's templates/layout/html.html.twig and templates/cd/cd-icons/cd-icons.html.twig into the site sub-theme.
3. Edit the templates/cd/cd-icons/cd-icons.html.twig to include the site sub-theme's cd-icons-sprite.svg.
4. Remove the relevant SVG inclusion part from the sub-theme hook_preprocess_html().

Case 3: site without icon sprite override but with html template override

1. Update the base theme.
2. Optional: Edit the site sub-theme html.html.twig to add the icons block.
3. Optional: Copy the sub-theme's templates/cd-icons/cd-icons.html.twig into your site's sub-theme.

Case 4: site with icon sprite override and html template override

1. Update the base theme.
2. Edit the site sub-theme html.html.twig to add the icons block.
3. Copy the sub-theme's templates/cd-icons/cd-icons.html.twig into the site sub-theme.
4. Edit the templates/cd-icons/cd-icons.html.twig to include the site sub-theme's cd-icons-sprite.svg.
5. Remove the relevant SVG inclusion part from the sub-theme hook_preprocess_html().

Note: for sites that don't use common_design_subtheme as name for the sub-theme, replace @common_design_subtheme in the templates mentioned above with your theme's machine name accordingly.

Verify your website's branding

If an existing implementation has extended and/or made use of the Sass file _cd-variables.scss then ALL references to those variables need to be converted to CSS Custom Properties (AKA CSS vars). This can generally be done by doing the following:

Renaming variables

All CD variables were changed as little as possible, maintaining all spelling and labeling as before. Thus, it is as close to find-and-replace as possible:

     Remove the $ sign
     ⇣
     $cd-ocha-blue
var(--cd-ocha-blue)
     ⇡
     Replace with var() and a double-dash prefix: --

Note: All custom properties MUST be prefixed with a double dash --. It is a requirement of the CSS specification, not a coding convention that we created.

Defining variables

// ❌ do NOT use Sass vars anymore
$cd-ocha-blue: #1f69b3;

// ✅ define CSS vars inside a root selector
:root {
  --cd-ocha-blue: #1f69b3;
}

Using variables

a {
  // ❌ do NOT reference Sass variables anymore
  color: $cd-ocha-blue;

  // ✅ DO use CSS Vars
  color: var(--cd-ocha-blue);
}

If a site has made use of $implementation- Sass vars, they should be updated to use the --brand- CSS vars instead. All relevant CSS Vars are defined in css/brand.css. A basic find and replace across the whole codebase should be sufficient. The order in which colors are output gives the sub-theme preference:

1. base-theme brand.css to provide all the necessary colors
2. base-theme styles
3. sub-theme styles (empty by default now)
4. sub-theme brand.css for final say on brand colors

Note: the Design System still hard-codes OCHA blue in many cases. You can extend Drupal libraries to override colors with the --brand CSS Vars. Over time we will migrate these components to use the new --brand CSS Vars so that everything takes on your website's brand automatically.

6.0.0 Release 2022-03-09

Overview

We've done some standardization and fundamental security updates to the repo, which require newer version of node.js if you compile Sass for either local development, within CI, or within a container. The Sass linter has been upgraded to keep it 100% compatible with the latest Drupal 9 release. The theme provides some styles to forms now.

Issue List

• CD-238: OCHA Services grid was adjusted to accommodate official translations of various website names #300
• CD-304: Form improvements, to provide basic styling to form elements displayed within the public-facing theme. #254
• CD-329: styelint plugins removed: unit-whitelist and plugin/no-browser-hacks #284
• CD-345: upgrade node.js and npm to maintain OICT security compliance #297
• CD-350: upgrade to stylelint@14 to keep in sync with Drupal 9 core. #295
• CD-367: standardized branch names so that main represents releases, and develop represents bleeding edge work. Adopted Conventional Commits and the versioning tool standard-version which generates a CHANGELOG automatically based on the commits. #283

Steps to Upgrade

• Run composer require unocha/common_design
• ⚠️ BREAKING CHANGE: New minimum supported node.js versions: node.js 16.13.2 LTS and npm 8.1.2 — all development environments must conform to the requirements.
• ⚠️ BREAKING CHANGE: since stylelint 14 contained numerous changes to its linting rules, this might have effects on any pre-existing subtheme implementations. The base theme was updated to pass the linter during the upgrade.
• ⚠️ BREAKING CHANGE: Any subtheme implementation that styles forms might need manual review, or the cd-form component might need to be disabled entirely via libraries-override if it conflicts with your site-specific styles. Drupal.org provides instructions for overriding libraries
• For Drupal sites, the theme_switcher module should be installed and configured so the common_design_subtheme is used for editing entities. This results in aesthetic changes and should improve overall consistency and improve editor UX within a specific site and also between sites using the common_design base theme. For developers, there are now template overrides for Node, Taxonomy term, and user edit forms, and various templates for form fields to add classes.

5.0.0 Release 2021-09-13

Overview

This is a major release because we remove the stylelint-no-browser-hacks plugin because Drupal 9 has removed it.
Refactoring on the Page Title display and markup has changed in the node--full.html.twig template override file.

See CHANGELOG.md

Issue Summary

#260 #261 Dependency updates
#262 #266 Fix page title logic
#264 Use local ponyfill javascript file instead of external CDN
Fixes #268 #269 QA
#271 Replace id with form_id in theme_suggestions_form_alter
#272 Add admin SVG icon to SVG icon sprite
#273 Add Release template format to CONTRIBUTING.md and #275 #276 Pull Request template to repo
#274 Add translation files for Header and Footer UI strings in Arabic, French, and Spanish
#277 Remove stylelint-no-browser-hacks as per Drupal 9 upgrade, see #265

Resolution

Update the node--full and node--*--full template overrides in the sub theme with the logic added to the node--full template in base theme https://github.com/UN-OCHA/common_design/blob/main/templates/content/node--full.html.twig#L91-L103

Impacts

If a node is rendered with the “full” view mode outside of the page or preview contexts (ex: entity reference field), then there will be no title for the node because the title variable will not be set.

The change to the “API” with the new common_design_set_page_title function and the modifications to the common_design_get_block_render_array (removal of the default title using the title resolver for the page title block). This affects implementations that use those functions (refer to SLT8 and RW9 for the page title paragraph type and for the term pages respectively)

v4.1.0 Release 2021-07-22

Overview

Reduce default fonts, include fonts multilingual as optional libraries, remove grid partial, improve cd-grid component

Issue Summary

• CD-210 site manifest in sub theme #247
• CD-301 Details about Annual Release schedule in README #248
• CD-297 Remove base/_grid.scss partial, improve cd-image-grid and Views Grid format #251
• [CD-276] Use drupal libraries to add google fonts #183 / CD-276 multilingual webfonts #253
• add coding standards links to README #256
• Issue #249 browserconfig.xml in sub theme

Resolution

Changed

• Adjust image path in manifest file
• Add details about Manifest and PWA to README
• Add libraries for advanced and multilanguage fonts and README updates to describe usage.
• Add CSS custom property to set the grid size for cd-image-grid component
• Move browserconfig.xml into sub theme, and adjust image path.

Fixed

• Fix Views views-view-grid.html.twig template override so it adds the cd-grid component only when the alignment setting from Views UI is set to "horizontal".

Removed

• Remove Roboto Condensed and Slab fonts and Noto Sans for multilingual from being included by default in styles.css.
• Remove grid partial previously included in styles.scss as it is not in use.

Impacts

Update base theme composer install unocha/common_design

Typography updates, remove gulp, replace sass-lint with stylelint, add e2e tests, add sub theme to base theme

Revise Typography based on design feedback #197
Drupal 9 compatibility #196
Remove Gulp and refactor linting #191 #195 #198 #200
Add sub theme to the base theme #201
Fix issues with sub theme directory scanning #205 and update Components custom namespace based on changes to the API #206 (This requires an update to the Components module ^2.4)
Add E2E tests #177
Remove sass partial override from cd-filter component #203
Add cd-page-title component #204
Remove sass-lint disable rules #207

Roboto 300 weight, cd-form and cd-layout-container edits

#188

component improvements, fix fonts, set page title font size, dependency updates, cd-tag component

Component additions:
cd-tag #140

Component fixes, improvements:
#181 cd-date (IASC), and #182 cd-form required field styles, bold labels (Drupal specific selectors due to dropping Classy)

Fix Fonts #184

Typography
Set page title font size #186

Dependency updates #187 #180

Encode google font URLs and dependency update

#179 to fix CSS aggregation and #180 dependency updates

Full-width header and footer, and component library

What's changed

Visually:

The header and footer are now full-width and there is no longer the light grey background, or “page” framing. The width of the content area is restricted in width, as before, but now there is an improvement to allow for full-width elements within the content area. This can provide an optimal experience for data-rich content like graphs, tables and maps when displayed on larger screens. It can also be a desired visual style for hero images and banners in some cases.

The height of the bottom border of the header has increased, and the main menu items no longer have visual separators. This gives things a little more breathing space when accommodating menu titles of varying length, and modernises slightly the simple yet striking header style of previous iterations.

The typography is being refined, first by defining heading sizes and fonts, in line with brand guidelines. There is a limit on the width of longform text to improve legibility, and with current collaboration from the designers we can achieve a clear and unified content experience.

Due to these changes, the overall look and feel of each implementation may change slightly. We consider it change in the right direction. The system we now have in place allows us to continue collaboration with the design, brand and editor teams, while releasing updates for the basic styles of all implementations using the Common Design design system. An OCHA-wide design system will improve user navigation, overall experience and brand consistency, while also reducing technical debt, development work and costs in the long term.

Technically:

• The visual changes mentioned above may also be pertinent to the subtheme, depending on how it has been customised. And, the visual changes are such that VRT fails.
• Header height increases due to 6px bottom border
• Width increases due to removal of side margins
• Sticky footer for anon users
• Colour and typography changes

Other items of note for developers:

• Node version 12 https://github.com/UN-OCHA/common_design/blob/main/.nvmrc for task runner.
• Replace gulp-sass #133 *See https://humanitarian.atlassian.net/browse/CD-269 for eventual removal of Gulp
• Update gulp postCSS browser versions to "Last 3 versions"
• Drupal 9 Compatible #171
• Remove classy as base theme 378e343
• Folders have been added to organise templates https://github.com/UN-OCHA/common_design/tree/main/templates *If a template is missing it may have been moved, or it may have come from Classy base theme.
• Accessibility and progressive enhancement improvements to cd-dropdown component https://github.com/UN-OCHA/common_design/tree/main/components/cd-dropdown and OCHA Services #134 #138
• OCHA Services moved from header to footer #124
• Translation improvements #150 #120
• Rename variables https://github.com/UN-OCHA/common_design/blob/main/sass/cd/_cd-variables.scss and remove some (eg. $cd-primary replaces $cd-primary-bg-color) https://github.com/UN-OCHA/iasc8/pull/438/files#diff-6d8839b7bf40fad67f206fa82be6ec54611fb2feb897a0baa2757403a537ad6b
• Introduce CSS custom properties
• Use rems for font-sizes https://github.com/UN-OCHA/common_design/blob/main/sass/cd/_cd-variables.scss#L61
• Full-width https://github.com/UN-OCHA/common_design/blob/main/sass/cd/cd-layout/_cd-layout.scss#L25
• Page title #176
• Fonts #144 (ongoing to find best solution)
• Buttons #123 #125
• Logo #130
• Adoption of CubeCSS methodology https://github.com/UN-OCHA/common_design/tree/main/components/cd-flow
• Select_a11y styles included as library
• More Components - See components/README https://github.com/UN-OCHA/common_design/tree/main/components
  and libraries.yml https://github.com/UN-OCHA/common_design/blob/main/common_design.libraries.yml

Part of a wider design system, the Component Library includes HTML/CSS/JS components that integrate OCHA colours and other brand details in line with https://brand.unocha.org
The base theme allows a single source of styles to be applied to multiple sites, while providing a structure to extend or override when customisation is needed.
https://demo.commondesign-unocha-org.ahconu.org/demo

Due to the simplicity of these components, developers and designers, content editors and regional offices can start using them as guidelines for their website content.

The repo encourages pull requests. Exploration of the design system topic is ongoing during weekly calls between the developers and designers. With the content squad also sharing the goal of better consistency and QA, we predict positive collective results over the coming months.

Update steps for subtheme

These will vary depending on implementation. Get in touch for support.

• Update nvm, package.json and gulp files from base theme. Run nvm use and npm i
• Copy variable from base theme _cd-variables.scss into subtheme, but preserve subtheme variables
• Rename variables in subtheme to reflect changes in base theme - Global search and replace based on gulp compilation errors will catch most SASS variable changes.
• Adjust template paths to reflect added layout directory containing page.html.twig override
• Adjust active menu styles in subtheme to reflect increase of border-bottom on header.
• Adjust main menu border or other header elements related to new visual changes.
• Adjust focus outline colour and OCHA Services button override.

For facets

• Move blocks into Facets region, with template override
• Export config
• Update page template override with Facet region present in aside element
• Add SASS partial for cd-filter https://github.com/UN-OCHA/common_design/tree/main/components/cd-filter

For page title

• Adjust page template with new markup
• Add Page Title region to https://github.com/UN-OCHA/common_design/blob/main/common_design.info.yml#L24 if not present
• Move Page Title block and Tabs block to Page Title region - config export needed.
• Move Messages block in highlighted region

Other

• Remove any unnecessary preprocess functions to the .theme file
• Set the base them or subtheme Page title settings, depending on what is needed
• Replace or copy into subtheme components specific to the implementation
• Remove unneeded template overrides if these templates are now in base theme
• Remove unneeded sass partials in favour of base theme components
• Remove layout partial override in favour of base theme layout adjustments or custom layouts
• Update subtheme readme if needed

TODOs

Update subtheme repo to reflect recent updates. https://github.com/UN-OCHA/common_design_subtheme