Make it possible to reuse and customise Wagtail’s fonts with CSS variables. Fix #8406 (#8544)

Co-authored-by: Thibaud Colas <thibaudcolas@gmail.com>

CHANGELOG.txt

@@ -14,6 +14,7 @@ Changelog
  * Use `FormData` instead of jQuery's `form.serialize` when editing documents or images just added so that additional fields can be better supported (Stefan Hammer)
  * Add informational Codecov status checks for GitHub CI pipelines (Tom Hu)
  * Replace `PageRevision` with generic `Revision` model (Sage Abdullah)
+ * Make it possible to reuse and customise Wagtail’s fonts with CSS variables (LB (Ben) Johnston)
  * Fix: Typo in `ResumeWorkflowActionFormatter` message (Stefan Hammer)
  * Fix: Throw a meaningful error when saving an image to an unrecognised image format (Christian Franke)
  * Fix: Remove extra padding for headers with breadcrumbs on mobile viewport (Steven Steinwand)

client/scss/elements/_root.scss

@@ -1,7 +1,4 @@
 :root {
-  --w-font-sans: #{$font-sans};
-  --w-font-mono: #{$font-mono};
-
   @include define-color('color-primary', #007d7e);
   @include define-color(
     'color-primary-darker',

client/scss/settings/_variables.scss

@@ -102,45 +102,8 @@ $system-color-button-text: ButtonText;
 // Our fonts are based off of a list of system fallbacks to ensure
 // that the most 'up-to-date' and available system font is used and rendered consistently as possible across browsers.
 
-$font-sans:
-  // iOS Safari, macOS Safari, macOS Firefox
-  -apple-system,
-  // macOS Chrome
-  BlinkMacSystemFont,
-  // Windows - for all browsers on Windows 7+ (putting Segoe UI before system-ui ensures Segoe UI will be rendered for different languages)
-  'Segoe UI',
-  system-ui,
-  // Targets Android and newer Chrome OS'. (If Roboto is installed on your windows computer Segoe UI will take precedence.)
-  Roboto,
-  // A common fallback font for older macOS'
-  'Helvetica Neue',
-  // Very old Windows versions (special shout-out to whoever is using windows 95)
-  Arial,
-  // A last resort if all else fails, just give us something without serifs :)
-  sans-serif,
-  // All the emojis 👋🙂
-  'Apple Color Emoji',
-  'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
-
-$font-mono:
-  // iOS Safari, MacOS Safari
-  ui-monospace, Menlo, Monaco,
-  // Windows
-  'Cascadia Mono',
-  'Segoe UI Mono',
-  // Linux
-  'Roboto Mono',
-  'Oxygen Mono', 'Ubuntu Monospace',
-  // Android
-  'Source Code Pro',
-  // Firefox
-  'Fira Mono',
-  // Last resort Android/others
-  'Droid Sans Mono',
-  'Courier New', monospace,
-  // All the emojis 👋🙂
-  'Apple Color Emoji',
-  'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+$font-sans: theme('fontFamily.sans');
+$font-mono: theme('fontFamily.mono');
 
 // Legacy icon font, to be removed in the near future.
 $font-wagtail-icons: wagtail;

client/src/tokens/typography.js

@@ -1,22 +1,40 @@
-// Note: Tailwind does not automatically escape font names.
-// If a font name contains an invalid identifier (like a space), we wrap it in quotes to escape the invalid characters.
-// Font stack optimised for built-in fonts of each major operating system, with support for emojis.
+/**
+ * # Typography
+ * Note: Tailwind does not automatically escape font names.
+ * If a font name contains an invalid identifier (like a space), we wrap it in quotes to escape the invalid characters.
+ */
 
+/**
+ * System UI Font stack for primary usage.
+ * Optimised for built-in fonts of each major operating system, with support for emojis.
+ */
 const systemUIFontStack = [
+  // iOS Safari, macOS Safari, macOS Firefox
   '-apple-system',
+  // macOS Chrome
   'BlinkMacSystemFont',
+  // Windows - for all browsers on Windows 7+ (putting Segoe UI before system-ui ensures Segoe UI will be rendered for different languages)
   '"Segoe UI"',
   'system-ui',
+  // Targets Android and newer Chrome OS'. (If Roboto is installed on your windows computer Segoe UI will take precedence.)
   'Roboto',
+  // A common fallback font for older macOS'
   '"Helvetica Neue"',
+  // Very old Windows versions (special shout-out to whoever is using windows 95)
   'Arial',
+  // A last resort if all else fails, just give us something without serifs :)
   'sans-serif',
+  // All the emojis 👋🙂
   'Apple Color Emoji',
   '"Segoe UI Emoji"',
   '"Segoe UI Symbol"',
   '"Noto Color Emoji"',
 ];
 
+/**
+ * System UI Font stack for mono-space usage.
+ * Optimised for built-in fonts of each major operating system, with support for emojis.
+ */
 const monoFontStack = [
   // iOS Safari, MacOS Safari
   'ui-monospace',
@@ -49,8 +67,10 @@ const fontFamily = {
   mono: monoFontStack,
 };
 
-// Key is equal to the pixel size of the rem value.
-// These values are used in combinations create typography defaults
+/**
+ * Key is equal to the pixel size of the rem value.
+ * These values are used in combinations create typography defaults
+ */
 const fontSize = {
   14: '0.875rem',
   15: '0.9375rem',
@@ -70,7 +90,9 @@ const fontWeight = {
   extrabold: 800,
 };
 
-// These are set to ems to be relative to the font size
+/**
+ * These are set to ems to be relative to the font size.
+ */
 const letterSpacing = {
   tighter: '-0.05em',
   tight: '-0.025em',

client/src/tokens/typography.stories.tsx

@@ -16,8 +16,15 @@ export default {
 
 export const FontFamilies = () => (
   <div>
-    <p>Wagtail’s UI font is a system font stack:</p>
-    <pre>{fontFamily.sans.join(', ')}</pre>
+    <p>Wagtail’s UI fonts use system font stacks:</p>
+    <div className="w-font-sans">
+      <strong>Font sans (default)</strong>
+      <pre>{fontFamily.sans.join(', ')}</pre>
+    </div>
+    <div className="w-font-mono">
+      <strong>Font mono</strong>
+      <pre>{fontFamily.mono.join(', ')}</pre>
+    </div>
   </div>
 );
 

client/tailwind.config.js

@@ -56,7 +56,10 @@ module.exports = {
       LinkText: 'LinkText',
       ButtonText: 'ButtonText',
     },
-    fontFamily,
+    fontFamily: {
+      sans: 'var(--w-font-sans)',
+      mono: 'var(--w-font-mono)',
+    },
     fontSize,
     fontWeight,
     lineHeight,
@@ -112,6 +115,17 @@ module.exports = {
       });
       addComponents(scale);
     }),
+    /**
+     * CSS Custom properties defined from our design tokens.
+     */
+    plugin(({ addBase }) => {
+      addBase({
+        ':root': {
+          '--w-font-sans': fontFamily.sans.join(', '),
+          '--w-font-mono': fontFamily.mono.join(', '),
+        },
+      });
+    }),
   ],
   corePlugins: {
     ...vanillaRTL.disabledCorePlugins,

docs/advanced_topics/customisation/admin_templates.rst

@@ -91,6 +91,21 @@ To replace the welcome message on the dashboard, create a template file ``dashbo
 
     {% block branding_welcome %}Welcome to Frank's Site{% endblock %}
 
+.. _custom_user_interface_fonts:
+
+Custom user interface fonts
+===========================
+
+To customise the font families used in the admin user interface, inject a CSS file using the hook :ref:`insert_global_admin_css` and override the variables within the ``:root`` selector:
+
+
+.. code-block:: css
+
+    :root {
+        --w-font-sans: Papyrus;
+        --w-font-mono: Courier;
+    }
+
 .. _custom_user_interface_colours:
 
 Custom user interface colours

docs/releases/4.0.md

@@ -19,6 +19,7 @@ depth: 1
  * Drop support for Safari 13 by removing left/right positioning in favour of CSS logical properties (Thibaud Colas)
  * Use `FormData` instead of jQuery's `form.serialize` when editing documents or images just added so that additional fields can be better supported (Stefan Hammer)
  * Add informational Codecov status checks for GitHub CI pipelines (Tom Hu)
+ * Make it possible to reuse and customise Wagtail’s fonts with CSS variables (LB (Ben) Johnston)
 
 ### Bug fixes