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.

HTML guidelines

We use djhtml for formatting and Curlylint for linting.

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.

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.