|
|
@@ -36,6 +36,59 @@ We use [Prettier](https://prettier.io/) for formatting and [Stylelint](https://s
|
|
|
- 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.
|
|
|
|
|
|
+### Stylesheets
|
|
|
+
|
|
|
+Most of our styles are combined into a single main stylesheet, `core.css`. This is the recommended approach for all new styles, to reduce potential style clashes, and encourage reuse of utilities and component styles between views. Imports within `core.scss` are structured according to ITCSS. There are two major exceptions to the ITCSS structure:
|
|
|
+
|
|
|
+- Legacy vendor CSS in `vendor/` is imported in the order it was loaded in before adding in the main stylesheet, to avoid compatibility issues. If possible, those styles should be converted to components and loaded further down the cascade.
|
|
|
+- Legacy layout-specific styles in `layouts/` are imported at the very end of the file, matching how styles were previously loaded across multiple stylesheets. If possible, those styles should be converted to components or utilities and loaded further up the cascade.
|
|
|
+
|
|
|
+When creating new styles, always prefer components, adding a new stylesheet in the `components` folder and importing it in `core.scss`.
|
|
|
+
|
|
|
+### Global styles
|
|
|
+
|
|
|
+For all of our styles, we use:
|
|
|
+
|
|
|
+- A very old version of `normalize.css` as a CSS reset.
|
|
|
+- `box-sizing: border-box`, with elements always inheriting the `box-sizing` of their parent.
|
|
|
+- Global CSS variables for colors, so they can be changed by site implementers.
|
|
|
+- Global CSS variables for font family, so they can be changed by site implementers.
|
|
|
+- A `--w-direction-factor` CSS variable, set to `1` by default and `-1` for RTL languages, to allow reversing of calculations of physical values (transforms, background positions).
|
|
|
+
|
|
|
+### Tailwind usage
|
|
|
+
|
|
|
+We use [Tailwind](https://tailwindcss.com/) to manage our design tokens via its theme, and generate CSS utilities. It is configured in `tailwind.config.js`, with a base configuration intended to be reusable in other projects.
|
|
|
+
|
|
|
+Wagtail uses most of Tailwind’s core plugins, with an override for them to create [Logical properties and values](https://rtlstyling.com/posts/rtl-styling#css-logical-properties) styles while still using Tailwind’s default utility and design token names.
|
|
|
+
|
|
|
+With utility classes, we recommend to:
|
|
|
+
|
|
|
+- Keep their number to a reasonable maximum, creating component styles instead if the utilities are inter-dependent, or if they are frequently reused together.
|
|
|
+- Avoid utilities relating to font size, weight, or other typographic considerations. Instead, use the higher-level type scale as defined in `typography.js`.
|
|
|
+
|
|
|
+### Sass usage
|
|
|
+
|
|
|
+We keep our Sass usage to a minimum, preferring verbose vanilla CSS over advanced Sass syntax. Here are specific Sass features to completely avoid:
|
|
|
+
|
|
|
+- Placeholders / `@extend`. Leads to unexpected cascading of styles.
|
|
|
+- Color manipulation. All of our colors are defined in JavaScript via Tailwind, to generate CSS variable definitions and documentation consistently.
|
|
|
+
|
|
|
+And Sass features to use with caution:
|
|
|
+
|
|
|
+- Sass nesting. Avoid relying on Sass nesting specifically, and overly specific selectors. Most styles can be written with either one or two levels of nesting, 3 for specific UI states, and 4 in the most complex scenarios only.
|
|
|
+- Parent selector (`&`) interpolation. Only use interpolation in class names sparingly, so we can more easily search for styles across the project.
|
|
|
+- Sass variables. Prefer Tailwind theme variables to reuse our design tokens, or CSS variables when a specific property changes based on state. Sass variables should only be used as shorter aliases for those scenarios, or as local component variables.
|
|
|
+- Mixins. Only create new mixins if the styles can’t be written as reusable component or utility styles.
|
|
|
+- Sass math. With most of our design tokens defined in Tailwind, loaded via PostCSS, we use `calc` functions for math operations rather than Sass.
|
|
|
+
|
|
|
+### Forced colors mode
|
|
|
+
|
|
|
+Also known as Windows High Contrast mode, or Contrast Themes. This is a feature of Windows for users to override websites’ styles with their own, so text is more readable. We intend to fully support it in all of our styles. Here are recommended practices:
|
|
|
+
|
|
|
+- Add additional borders where the background color would otherwise convey the position of specific elements, particularly for page regions and components layered above the page.
|
|
|
+- Overrides with `@media (forced-colors: active)` should only be used when there is no simpler alternative. Write CSS for WHCM support from the get-go rather than with sweeping overrides.
|
|
|
+- Never use `forced-color-adjust: none`. It compromises compatibility with a wide range of custom themes, and should only be needed if a component relies on a specific color hue to work (which is an anti-pattern).
|
|
|
+
|
|
|
## JavaScript guidelines
|
|
|
|
|
|
We use [Prettier](https://prettier.io/) for formatting and [ESLint](https://eslint.org/) for linting.
|
|
|
@@ -90,6 +143,16 @@ This is an area of active improvement for Wagtail, with [ongoing discussions](ht
|
|
|
|
|
|
- Always use the `trimmed` attribute on `blocktranslate` tags to prevent unnecessary whitespace from being added to the translation strings.
|
|
|
|
|
|
+### Right-to-left language support
|
|
|
+
|
|
|
+We support right-to-left languages, and in particular viewing the Wagtail admin interface in a horizontally mirrored layout. Here are guidelines to guarantee support:
|
|
|
+
|
|
|
+- Write styles with [logical properties and values](https://rtlstyling.com/posts/rtl-styling#css-logical-properties) whenever possible.
|
|
|
+- For styles that can only be written with physical properties (translations, background positions), use the `--w-direction-factor` variable equal to 1 or -1 so the value reverses based on the `dir` attribute of the element or page.
|
|
|
+- As a last resort, use `[dir='rtl']` style if there is no other way to write styles.
|
|
|
+
|
|
|
+Make sure to also reverse the direction of any position calculation in JavaScript, as there is no support of logical values in DOM APIs (x-axis offsets always from the left).
|
|
|
+
|
|
|
## Icons
|
|
|
|
|
|
We use inline SVG elements for Wagtail’s icons, for performance and so icons can be styled with CSS. View [](icons) for information on how icons are set up for Wagtail users.
|
Thibaud Colas