kopia lustrzana https://github.com/wagtail/wagtail
3.1 KiB
3.1 KiB
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, andmake lint-client
lints JS/CSS.make format
will run all formatting and fixing of linting issues. There is alsomake format-server
andmake 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 behaviour, 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
forfont-size
, because they offer absolute control over text. Additionally, unit-lessline-height
is preferred because it does not inherit a percentage value of its parent element, but instead is based on a multiplier of thefont-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 onblocktranslate
tags to prevent unnecessary whitespace from being added to the translation strings.