Project background images

This section aims to provide some help to developers willing to propose additional project background images.

TL;DR: Take an existing image like beach-daytime, search occurrences of it in the code and do the same.

Image format & size

Image is provided in two sizes:

1680×850 for smaller resolutions
2400×850 for bigger resolutions

If your original image is a photo, there is a high chance that it has been save in JPEG format. However, in order to save bandwidth we should convert it to WebP instead.

It can be done with the following command, assuming that the image is already in the 2400×850 resolution:

$> cwebp -preset photo -mt -m 6 -pass 10 -af my-image.jpg -o my-image-2400px.webp

Or, if you have a bunch of images:

$> find . -name '*.jpg' -exec bash -c \
    'cwebp -preset photo -mt -m 6 -pass 10 -af \
        $1 -o ${1%.jpg}-2400px.webp' _ {} \;

Now we can crop the original image down to a 1680×850 pixels:

$> cwebp -preset photo -mt -m 6 -pass 10 -af \
  -crop 360 0 1680 850 \
  my-image.jpg -o my-image-1680px.webp

Or if you have a bunch of images:

$> find . -name '*.jpg' -exec bash -c \
    'cwebp -preset photo -mt -m 6 -pass 10 -af \
        -crop 360 0 1680 850 \
        $1 -o ${1%.jpg}-1680px.webp' -- {} \;

Note: the image is automatically cropped to center the image. You may need to adjust the x position of the -crop parameter depending on the background image — for example to favor dark/blurry zone over vibrant colors.

Image dominant color

Even if the background image is relatively small, it can take some time to load on the browser. In order to limit the flickering and offer a smooth transition, a solid color is displayed. T his color should be the dominant color of the image. You can use the following command to extract such information:

$> convert my-image-1680px.webp -scale 1x1\! -format '%[pixel:u]' info:-

For example it will output the following information:

Decoded /tmp/magick-2917Aek1hh7mfh3h. Dimensions: 1680 x 850 . Format: lossy. Now saving...
Saved file /tmp/magick-2917YRYRx5cxgPOm
srgba(76,52,34,1)%

We can then take the dominant color from the last line: rgb(76, 52, 34).

The color is expected to have enough contrast when used with the same color with 7% opacity on a white background. The color needs to be adjusted manually to have a contrast ratio of at least 4.5:1.

Image definition in SCSS

Now that you have two .webp versions of an image, and its dominant color, you can insert the definition in src/themes/common/css/project-background/_background.scss alongside the existing ones. Be nice, don’t forget the attributions!

You will need to write a new scss file (it will expose the CSS custom properties for the image) and declare it in the src/webpack.common.js. The file name should be the same than the choosen key in the background definition file. It will be referenced later as the identifier of the background.

// _background.scss
$definitions: (
    // […],
    my-image:
    (
        // Photo by John Doe
        // https://example.com/john.doe-photography/
        image-2400px: url(#{$project-background-images-path}/my-image-2400px.webp) no-repeat,
        image-1680px: url(#{$project-background-images-path}/my-image-1680px.webp) no-repeat,
        color: rgb(76, 52, 34),
        size: 100%
    ),
    // […]
);

// my-image.scss
@use 'background';

.project-with-background {
    @include background.css-custom-properties('my-image');
}

// webpack.common.js
const project_background_themes = [
    // […],
    "my-image",
    // […],
];

Image definition in PHP

Identifier of the background should be declared in the following locations:

In the HeaderBackgroundRepresentation::identifier annotation, so that we expose the expected values in the OpenAPI representation.
In the ProjectBackgroundSelection::ALLOWED constant, so that we can propose the new image in project administration.