UI Guidelines¶

Wagtail’s user interface is built with:

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.

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 behaviour, IDs for semantics only.
For comments, use Django template syntax instead of HTML.

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.

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.

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.