Move HTML and CSS guidelines to a single "UI guidelines" page

docs/contributing/css_guidelines.rst

@@ -1,172 +0,0 @@
-CSS coding guidelines
-===========================
-
-Our CSS is written in `Sass <https://sass-lang.com/>`_, using the SCSS syntax.
-
-Linting and formatting SCSS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Wagtail uses `stylelint <https://stylelint.io/>`_ for linting,
-and `Prettier <https://prettier.io/>`_ for formatting.
-You'll need Node.js and npm on your development machine.
-Ensure project dependencies are installed by running ``npm install --no-save``
-
-Tailwind CSS
--------------
-
-Wagtail uses utility classes via `Tailwind <https://tailwindcss.com/>`_, generated based on values set in the ``tailwind.config.js`` file.
-
-To use these utilities you will need to prefix your class names with ``w-`` to avoid interfering with other predefined styles of similar names.
-
-
-Linting code
-------------
-
-Run the linter from the wagtail project root:
-
-.. code-block:: console
-
-    $ npm run lint:css
-
-
-The linter is configured to check your code for adherence to the guidelines
-below, plus a little more.
-
-Formatting code
----------------
-
-For Prettier auto-formatting, run:
-
-.. code-block:: console
-
-    $ npm run format
-
-If you want to autofix linting errors:
-
-.. code-block:: console
-
-    $ npm run lint:css -- --fix
-
-Changing the linter configuration
----------------------------------
-
-The configuration for the linting rules is managed in an external
-repository so that it can be easily shared across other Wagtail projects
-or plugins. This configuration can be found at
-`stylelint-config-wagtail <https://github.com/wagtail/stylelint-config-wagtail>`_.
-
-Styleguide Reference
-~~~~~~~~~~~~~~~~~~~~
-
-Formatting
-----------
-
--  Use hex color codes ``#000`` unless using ``rgba()`` in raw CSS
-   (SCSS' ``rgba()`` function is overloaded to accept hex colors as a
-   param, e.g., ``rgba(#000, .5)``).
--  Use ``//`` for comment blocks (instead of ``/* */``).
--  Use single quotes for string values
-   ``background: url('my/image.png')``
--  Avoid specifying units for zero values, e.g., ``margin: 0;`` instead
-   of ``margin: 0px;``.
--  Strive to limit use of shorthand declarations to instances where you
-   must explicitly set all the available values.
-
-Sass imports
-------------
-
-Leave off underscores and file extensions in includes:
-
-.. code-block:: scss
-
-    // Bad
-    @import 'components/_widget.scss'
-
-    // Better
-    @import 'components/widget'
-
-Pixels vs. ems
---------------
-
-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``.
-
-Specificity (classes vs. ids)
------------------------------
-
-Always use classes instead of IDs in CSS code. IDs are overly specific and lead
-to duplication of CSS.
-
-When styling a component, start with an element + class namespace,
-prefer direct descendant selectors by default, and use as little
-specificity as possible. Here is a good example:
-
-.. code-block:: html
-
-    <ul class="category-list">
-        <li class="item">Category 1</li>
-        <li class="item">Category 2</li>
-        <li class="item">Category 3</li>
-    </ul>
-
-.. code-block:: scss
-
-    .category-list { // element + class namespace
-
-        // Direct descendant selector > for list items
-        > li {
-            list-style-type: disc;
-        }
-
-        // Minimal specificity for all links
-        a {
-            color: #f00;
-        }
-    }
-
-Class naming conventions
-------------------------
-
-Never reference ``js-`` prefixed class names from CSS files. ``js-`` are
-used exclusively from JS files.
-
-Use the SMACSS ``is-`` `prefix <https://smacss.com/book/type-state>`__
-for state rules that are shared between CSS and JS.
-
-Misc
-----
-
-As a rule of thumb, avoid unnecessary nesting in SCSS. At most, aim for
-three levels. If you cannot help it, step back and rethink your overall
-strategy (either the specificity needed, or the layout of the nesting).
-
-Examples
---------
-
-Here are some good examples that apply the above guidelines:
-
-.. code-block:: scss
-
-    // Example of good basic formatting practices
-    .styleguide-format {
-        color: #000;
-        background-color: rgba(0, 0, 0, .5);
-        border: 1px solid #0f0;
-    }
-
-    // Example of individual selectors getting their own lines (for error reporting)
-    .multiple,
-    .classes,
-    .get-new-lines {
-        display: block;
-    }
-
-    // Avoid unnecessary shorthand declarations
-    .not-so-good {
-        margin: 0 0 20px;
-    }
-    .good {
-        margin-bottom: 20px;
-    }

docs/contributing/developing.rst

@@ -15,7 +15,7 @@ If you'd prefer to set up all the components manually, read on. These instructio
 Setting up the Wagtail codebase
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The preferred option is to install the correct version of Node using Node Version Manager (nvm), which will always align the version with the supplied  ``.nvmrc`` file in the root of the project. See nvm's `installation instructions <https://github.com/creationix/nvm>`_.
+The preferred option is to install the correct version of Node using `Node Version Manager (nvm) <https://github.com/creationix/nvm>`_ or `fnm <https://github.com/Schniz/fnm>`_, which will always align the version with the supplied  ``.nvmrc`` file in the root of the project.
 Alternatively, you can install `Node.js <https://nodejs.org/>`_ directly, ensure you install the version as declared in the project's root ``.nvmrc`` file.
 
 You will also need to install the **libjpeg** and **zlib** libraries, if you haven't done so already - see Pillow's `platform-specific installation instructions <https://pillow.readthedocs.org/en/latest/installation.html#external-libraries>`_.
@@ -45,7 +45,7 @@ Install the tool chain for building static assets:
 
 .. code-block:: console
 
-    $ npm install --no-save
+    $ npm ci
 
 Compile the assets:
 

docs/contributing/html_guidelines.rst

@@ -1,20 +0,0 @@
-HTML coding guidelines
-======================
-
-We use `Django templates <https://docs.djangoproject.com/en/stable/ref/templates/language/>`_ to author HTML.
-
-Linting HTML
-~~~~~~~~~~~~
-
-We use `curlylint <https://www.curlylint.org/>`_ to lint templates and `djhtml <https://github.com/rtts/djhtml>`_ to format them.
-If you have installed Wagtail's testing dependencies (``pip install -e .[testing]``), you can check your code by running ``make lint``, and format your code by running ``make format``. Alternatively you can also run
-``make lint-client`` for checking and ``make format-client`` for formatting frontend (html/css/js) only files.
-
-Principles
-~~~~~~~~~~
-
-* Write `valid HTML <https://validator.w3.org/nu/>`_. We target the HTML5 doctype.
-* Write `semantic HTML <https://html5doctor.com/element-index/>`_.
-* Consult `ARIA Authoring Practices <https://w3c.github.io/aria-practices/>`_, in particular `No ARIA is better than Bad ARIA <https://w3c.github.io/aria-practices/#no_aria_better_bad_aria>`_.
-* Attach JavaScript behavior with ``data-`` attributes, rather than classes or IDs.
-* For comments, use Django templates syntax instead of HTML.

docs/contributing/index.rst

@@ -62,8 +62,7 @@ More information
     styleguide
     general_guidelines
     python_guidelines
-    html_guidelines
-    css_guidelines
+    ui_guidelines
     javascript_guidelines
     documentation_guidelines
     documentation-modes

docs/contributing/ui_guidelines.md

@@ -0,0 +1,35 @@
+# UI Guidelines
+
+Wagtail’s user interface is built with:
+
+- **HTML** using [Django templates](https://docs.djangoproject.com/en/stable/ref/templates/language/).
+- **CSS** using [Sass](https://sass-lang.com/) and [Tailwind](https://tailwindcss.com/).
+- **SVG** for our icons, minified with [SVGO](https://jakearchibald.github.io/svgomg/).
+
+## 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](https://github.com/rtts/djhtml) for formatting and [Curlylint](https://www.curlylint.org/) for linting.
+
+- Write [valid](https://validator.w3.org/nu/), [semantic](https://html5doctor.com/element-index/) HTML.
+- Follow [ARIA authoring practices](https://w3c.github.io/aria-practices/), in particular [No ARIA is better than Bad ARIA](https://w3c.github.io/aria-practices/#no_aria_better_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](https://prettier.io/) for formatting and [Stylelint](https://stylelint.io/) for linting.
+
+- We follow [BEM](http://getbem.com/) and [ITCSS](https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/), with a large amount of utilities created with [Tailwind](https://tailwindcss.com/).
+- Familiarise yourself with our [stylelint-config-torchbox](https://github.com/wagtail/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 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.

wagtail/utils/setup.py

@@ -83,7 +83,7 @@ class check_bdist_egg(bdist_egg):
                         "************************************************************",
                         "The front end assets for Wagtail are missing.",
                         "To generate the assets, please refer to the documentation in",
-                        "docs/contributing/css_guidelines.rst",
+                        "docs/contributing/developing.rst",
                         "************************************************************",
                     ]
                 )