Add icon--directional class to mirror icons for RTL languages

client/scss/components/_icons.scss

@@ -100,3 +100,13 @@ use[href='#icon-spinner'] {
 .icon-wagtail__wordmark {
   fill: theme('colors.text-context');
 }
+
+// Icons mirroring for RTL languages to match the rest of the Wagtail UI.
+// Automatically mirror child elements of SVG icons marked with
+// icon--directional. This will be applied to the children of the <symbol>
+// elements in the icons sprite, ensuring all usages of the icons will be in the
+// correct direction.
+.icon--directional * {
+  transform: scaleX(var(--w-direction-factor));
+  transform-origin: center;
+}

client/scss/elements/_elements.scss

@@ -18,7 +18,10 @@
 :root,
 :host,
 [dir='ltr'] {
-  // Flips the direction of `transform` declarations, based on whether the UI is LTR or RTL.
+  // Flips the direction based on whether the UI is LTR or RTL. Used for:
+  // - `transform` / `background-position` declarations for layout
+  // - icons mirroring.
+  // - Any other styles built with physical properties or values to mirror for RTL languages.
   --w-direction-factor: 1;
 }
 

docs/advanced_topics/icons.md

@@ -30,9 +30,10 @@ Draw or download an icon and save it in a template folder:
 
 The `svg` tag should:
 
--   Set the `id="icon-<name>"` attribute, icons are referenced by this name
--   Set the `xmlns="http://www.w3.org/2000/svg"` attribute
--   Set the `viewBox="..."` attribute
+-   Set the `id="icon-<name>"` attribute, icons are referenced by this name.
+-   Set the `xmlns="http://www.w3.org/2000/svg"` attribute.
+-   Set the `viewBox="..."` attribute, and no `width` and `height` attributes.
+-   If the icon should be mirrored in right-to-left (RTL) languages, set the `class="icon--directional"` attribute.
 -   Include license / source information in a `<!--! -->` HTML comment, if applicable.
 
 Set `fill="currentColor"` or remove `fill` attributes so the icon color changes according to usage.

docs/contributing/ui_guidelines.md

@@ -53,7 +53,7 @@ For all of our styles, we use:
 -   `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).
+-   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) and mirroring of icons and visuals with directional elements like arrows.
 
 ### Tailwind usage
 
@@ -164,8 +164,9 @@ Icons are SVG files in the [Wagtail admin template folder](https://github.com/wa
 When adding or updating an icon,
 
 1. Run it through [SVGO](https://jakearchibald.github.io/svgomg/) with appropriate compression settings.
-2. Manually remove any unnecessary attributes.
+2. Manually remove any unnecessary attributes. Set the `viewBox` attribute, and remove `width` and `height` attributes.
 3. Manually add its `id` attribute with a prefix of `icon-` and the icon name matching the file name. Keep the icon as named from its source if possible.
 4. Add or preserve licensing information as a HTML comment starting with an exclamation mark: `<!--! Icon license -->`. For Font Awesome, we want: `<!--! [icon name] ([icon style]): Font Awesome [version] -->`. For example, `<!--! triangle-exclamation (solid): Font Awesome Pro 6.4.0 -->`.
 5. Add the icon to Wagtail’s own implementation of the `register_icons` hook, in alphabetical order.
 6. Go to the styleguide and copy the Wagtail icons table according to instructions in the template, pasting the result in `wagtail_icons_table.txt`.
+7. If the icon requires [right-to-left mirroring](https://rtlstyling.com/posts/rtl-styling#bidirectional-icons), add the `class="icon--directional"` attribute.