wagtail/docs/contributing/ui_guidelines.md

UI Guidelines

Wagtail’s user interface is built with:

• HTML using Django templates.
• CSS using Sass and Tailwind.
• 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 templates 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-torchbox 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 colors 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.