wagtail/docs/contributing/ui_guidelines.md

UI Guidelines

Wagtail’s user interface is built with:

• HTML using Django templates
• CSS using Sass and Tailwind
• JavaScript with TypeScript
• SVG for our icons, minified with SVGO

Linting and formatting

Here are the available commands:

• make lint will run all linting, make lint-server lints templates, make lint-client lints JS/CSS.
• make format will run all formatting and fixing of linting issues. There is also make format-server and make format-client.

Have a look at our Makefile tasks and package.json scripts if you prefer more granular options.

HTML guidelines

We use djhtml for formatting and Curlylint for linting.

• Write valid, semantic HTML.
• Follow ARIA authoring practices, in particular No ARIA is better than Bad ARIA.
• Use classes for styling, data- attributes for JavaScript behavior, IDs for semantics only.
• For comments, use Django template syntax instead of HTML.

CSS guidelines

We use Prettier for formatting and Stylelint for linting.

• We follow BEM and ITCSS, with a large amount of utilities created with Tailwind.
• Familiarise yourself with our stylelint-config-wagtail configuration, which details our preferred code style.
• Use rems for font-size, because they offer absolute control over text. Additionally, unit-less line-height is preferred because it does not inherit a percentage value of its parent element, but instead is based on a multiplier of the font-size.
• Always use variables for design tokens such as colours or font sizes, rather than hard-coding specific values.
• We use the w- prefix for all styles intended to be reusable by Wagtail site implementers.

JavaScript guidelines

We use Prettier for formatting and ESLint for linting.

• We follow a somewhat relaxed version of the Airbnb styleguide.
• Familiarise yourself with our eslint-config-wagtail configuration, which details our preferred code style.

Multilingual support

This is an area of active improvement for Wagtail, with ongoing discussions.

• Always use the trimmed attribute on blocktrans tags to prevent unnecessary whitespace from being added to the translation strings.