infrastructure/web-assets
1
4
Fork 3
Code Issues 3 Pull Requests 1 Projects Releases 41 Wiki Activity
Page: v2 guidelines and notes
Pages
CSS and Sass guidelines Development utilities Home Version tracker v2 guidelines and notes
5 v2 guidelines and notes
Márton Lente edited this page 2024-09-27 14:26:06 +02:00
Table of Contents

Web Assets v2 guidelines and notes

Web Assets v2 is a major update, with cleanup, usage, and visual improvements for the framework. It has breaking cleanup and naming changes. This document lists and details changes to the source files, documentation, and components to help migrating to v2, and work with version 2 onwards.

For a detailed history of changes, see #94690 issue, that covers most changes.

Dependencies

  • Added Boostrap 5 as dev dependency to use its Utilities API for generating custom Web Assets utilities.
  • Updated npm Sass build pipeline for Bootstrap 5 Utlitites API.
  • Initialized migrating Bootstrap 4 partials to custom Web Assets components, and deprecating Bootstrap 4 partials.

Documentation

  • Added Readme section 'Development utilities' to document new development utilities.
  • Added Reference page section 'Colours' to document and show colour system usage.
  • Fixed Reference page HTML markup validation errors, so that components can be copy-pasted as is.
  • Moved single-responsibility abstractions to deprecated partial for cleaning up repetitions.

Improvements and new features

Improvements are listed by their importance, starting with global changes. Breaking changes come before non-breaking changes within sections.

Namings

  • Added or unified abbreviations for more consistent and shorter class and variable namings. Changes and new conventions are listed in the following table for reference:
Old New Comment
background bg
blender-web-assets bwa
button btn
extra-large xl
extra-small xs
font-size fs
font-weight fw
icon icon No change
image img Change with caution
large lg
line-height lh
medium md
small sm
text text No change
  • Changed Boostrap 4 based naming conventions to Bootstrap 5 inspired naming schemes (e.g. changed ml-* to ms-*). For a full list of old and new naming pairs see the search-and-replace-map-v2-upgrade.txt dev-utils migration helper file.

Units

  • Matched rem to px units for easier calculations (by setting font-size: 62.5% on the root html element). 1.0rem equals 10px.
  • Changed --spacer = 1.6rem to align with old 18px based spacings, and help working with the new 4px baseline grid.
  • Mapped explicit spacing values to rem or --spacer equivalents. Converted explicit rem values to --spacer-based calculations. Changes and new conventions are listed in the following table for reference:
Px value Rem value Closest spacer value
(--spacer = 1.6rem)
1px .1rem
2px .2rem
3px .3rem --spacer-1
4px .4rem --spacer-1
5px .5rem --spacer-1
6px .6rem --spacer-2
7px .7rem --spacer-2
7.5px .75rem --spacer-2
8px .8rem --spacer-2
9px .9rem --spacer-2
10px 1.0rem --spacer-2
12px 1.2rem 0.75 --spacer
12.5px 1.25rem --spacer
15px 1.5rem --spacer
16px 1.6rem --spacer
18px 1.8rem --spacer
20px 2.0rem --spacer-4
24px 2.4rem --spacer-4
25px 2.5rem --spacer-4
30px 3.0rem 2 --spacer
32px 3.2rem 2 --spacer
35px 3.5rem 2 --spacer
36px 3.6rem 2 --spacer
40px 4.0rem --spacer-5
48px 4.8rem --spacer-5
50px 5.0rem --spacer-5
56px 5.6rem --spacer-5
60px 6.0rem 4 --spacer
100px 10.0rem 6 --spacer
180px 18.0rem 10 --spacer
460px 46.0rem 30 --spacer
560px 56.0rem 35 --spacer

For a full list of old and new units pairs see the search-and-replace-map-v2-upgrade-units.txt dev-utils upgrade helper file.

Themes

TODO: consider moving section 'Themes' to Readme

Web Assets v2 extends full support for dark, light and system-preferred themes. If enabled, users can select their preferred colour scheme when using web apps that run on Web Assets v2.

Enable themes

Theme support is disabled by default. Follow the steps below to enable theme support in projects:

  1. Compile the _theme_system.sass partial as part of the project Sass build pipeline. theme_system.sass is not compiled by default.
  2. Compile the 20_theme.js script as part of the project JavaScript build pipeline, or include the script to the project.
  3. Place the following toggle theme button snippet in your project's navigation markup to enable theme selection support:
<button class="js-toggle-theme-btn"><i class="js-toggle-theme-btn-icon i-adjust"></i></button>

The theme system is enabled if the above markup is present on the page. 4. (Optional:) Flickering can happen when loading themes on pages with long loading times. To prevent this, the bundled dev-utils/init-theme.min.js development utility JavaScript snippet can be added to your document <head>. It isn't part of the project JavaScript build pipeline and doesn't conflict with 20_theme.js (as the snippet runs as an IIFE).

Configure themes

The theme system can be configured accordingly to the project's specific needs with the following options:

  • The theme system defaults to system-preferred colour behaviour, if active. Dark and Light themes can be set to default by setting the following attributes on the root html element: [data-theme="dark"] or [data-theme="light"] accordingly.
  • The dark or light themes can be forced on a per element basis by assigning theme-dark or theme-light classes to the component.

Components

  • Changed all explicit height values starting from 4px to spacer-based calculations for improved vertical rhythm.
  • Added baseline-based vertical spacings to implement 4px baseline grid for improved vertical rhythm.
  • Added modular line-heights for improved vertical rhythm. New line-heights are multiplies of --spacer.
  • Changed font-sizes to classical typographic scale values.
  • Changed font-family from Heebo to Inter to better support Blender's visual branding.
  • Added font-size definitions for h4 and h5 elements to cover all HTML headings elements.
  • Initialized cleanup of Sass variables for changing to CSS3 custom properties.
  • Changed Sass calculations to CSS3 calculations.
  • Moved component-specific mixins to component partials.
  • Added subtle transition effect to the components using the details element.
  • Changed explicit transition-speeds to variable-based transition speeds.
  • Refactored component cards class namings.
  • Added component checkbox toggle-bar.

Upgrade to v2

Filesystem

When upgrading, use the bundled v2-upgrade.sh helper script in /dev-utils to accelerate the process and minimize manual changes needed on the project level. The v2-upgrade.sh is based on v2's new search-and-replace.sh script in the same directory. For details on how to use the latter, see the Readme.

  1. If Web Asset's v2 branch is not yet merged into main, add the branch=v2 definition to the project's .gitmodules config, for example:
[submodule "web-assets"]
  branch = v2
  path = web-assets
  url = https://projects.blender.org/infrastructure/web-assets.git
  1. Update Git submodule web-assets: git submodule update --remote web-assets
  2. cd to dev-utils in the web-assets directory within the project. For example: cd web-assets/dev-utils
  3. Run the script in dry-mode, with -n flag. Pass in the directory to process, for example: ./v2-upgrade.sh -d /home/user/blender-project -n
  4. If everything looks correct, run the script: ./v2-upgrade.sh -d /home/user/blender-project

Adjust the above snippets to match Web Asset Git submodule's naming within the project (e.g. it's often called assets_shared).

After finishing the above, consider running the search-and-replace.sh script also by passing in the bundled search-and-replace-map-v2-upgrade-units.txt map to resolve post-upgrade issues coming from the changed units scale between px and rem, introduced in v2. Then, make the necessary project-specific changes.

Database (WordPress)

Some WordPress projects have classes and style definitions in the database. Use the bundled wp-search-and-replace.php script to accelerate the upgrade as a database equivalent of the actions above.

  1. Call the script, and run the wp_search_and_replace function in your template, like this in dry-mode:
<?php
$wp_search_and_replace_path = get_template_directory() . '/assets_shared/dev-utils/wp-search-and-replace.php';
$map_file_name_path = get_template_directory() . '/assets_shared/dev-utils/search-and-replace-map-v2-upgrade-wp.txt';

include $wp_search_and_replace_path;
wp_search_and_replace($map_file_name_path, $dry_mode = true);
?>

  1. If everything looks correct, run the function without the $dry_mode = true argument.

  2. Repeat steps 1. and 2. by passing in search-and-replace-map-v2-upgrade-post-wp.txt as $map_file_name_path to resolve post-upgrade issues.

Roadmap

TODO