Auto-generate docs for most important design tokens

client/src/tokens/colors.stories.tsx

@@ -2,7 +2,7 @@ import React from 'react';
 import colors, { Hues, Shade } from './colors';
 
 const description = `
-Wagtail’s color palette is structured as design tokens, available as CSS classes.
+Wagtail’s typographic styles are made available as separate design tokens, but in most scenarios it’s better to use one of the predefined text styles.
 `;
 
 interface PaletteProps {
@@ -57,13 +57,21 @@ const Palette = ({ color, hues }: PaletteProps) => (
   </div>
 );
 
-/**
- * Displays all icons within our sprite.
- */
-const ColorPalette = () => (
+export default {
+  title: 'Foundation / Colors',
+  parameters: {
+    docs: {
+      extractComponentDescription: () => description,
+    },
+  },
+};
+
+export const ColorPalette = () => (
   <>
     <p>
-      View <a href={getContrastGridLink()}>Contrast Grid</a>
+      View <a href={getContrastGridLink()}>Contrast Grid</a>. Here is our full
+      color palette, with contrasting text chosen for readability of this
+      example only.
     </p>
     {Object.entries(colors).map(([color, hues]) => (
       <div key={color}>
@@ -73,21 +81,3 @@ const ColorPalette = () => (
     ))}
   </>
 );
-
-export default {
-  title: 'Foundation / Colors',
-  parameters: {
-    docs: {
-      extractComponentDescription: () => description,
-    },
-  },
-  // argTypes: {
-  //   color: {
-  //     description: 'Only intended for demo purposes',
-  //   },
-  // },
-};
-
-export const AllColors = (args) => <ColorPalette {...args} />;
-
-AllColors.args = {};

client/src/tokens/typeScale.js

@@ -1,70 +0,0 @@
-// eslint-disable-next-line @typescript-eslint/no-var-requires
-const plugin = require('tailwindcss/plugin');
-
-// TypeScale plugin:
-// This plugin generates component classes using tailwind's configuration for each object inside of the typeScale const.
-// If the tailwind config is using a prefix such as 'w-' this will be included in the compiled css class eg. .w-h1
-module.exports = plugin(({ addComponents, theme }) => {
-  const headingBaseStyles = {
-    fontWeight: theme('fontWeight.bold'),
-    color: theme('colors.primary.DEFAULT'),
-    lineHeight: theme('lineHeight.tight'),
-  };
-
-  const typeScale = {
-    '.h1': {
-      fontSize: theme('fontSize.30'),
-      fontWeight: theme('fontWeight.extrabold'),
-      color: theme('colors.primary.DEFAULT'),
-      lineHeight: theme('lineHeight.tight'),
-    },
-    '.h2': {
-      fontSize: theme('fontSize.24'),
-      ...headingBaseStyles,
-    },
-    '.h3': {
-      fontSize: theme('fontSize.22'),
-      ...headingBaseStyles,
-    },
-    '.h4': {
-      fontSize: theme('fontSize.18'),
-      ...headingBaseStyles,
-    },
-    '.label-1': {
-      fontSize: theme('fontSize.16'),
-      fontWeight: theme('fontWeight.bold'),
-      color: theme('colors.primary.DEFAULT'),
-      lineHeight: theme('lineHeight.tight'),
-    },
-    '.label-2': {
-      fontSize: theme('fontSize.15'),
-      fontWeight: theme('fontWeight.semibold'),
-      color: theme('colors.primary.DEFAULT'),
-      lineHeight: theme('lineHeight.tight'),
-    },
-    '.label-3': {
-      fontSize: theme('fontSize.14'),
-      fontWeight: theme('fontWeight.medium'),
-      color: theme('colors.primary.DEFAULT'),
-      lineHeight: theme('lineHeight.tight'),
-    },
-    '.body-text': {
-      fontSize: theme('fontSize.16'),
-      fontWeight: theme('fontWeight.normal'),
-      lineHeight: theme('lineHeight.normal'),
-    },
-    '.body-text-large': {
-      fontSize: theme('fontSize.18'),
-      fontWeight: theme('fontWeight.normal'),
-      lineHeight: theme('lineHeight.normal'),
-    },
-    '.help-text': {
-      fontSize: theme('fontSize.14'),
-      fontWeight: theme('fontWeight.normal'),
-      color: theme('colors.grey.400'),
-      lineHeight: theme('lineHeight.tight'),
-    },
-  };
-
-  addComponents(typeScale);
-});

client/src/tokens/typography.js

@@ -86,6 +86,71 @@ const lineHeight = {
   normal: '1.5',
 };
 
+const headingBaseStyles = {
+  fontWeight: 'fontWeight.bold',
+  color: 'colors.primary.DEFAULT',
+  lineHeight: 'lineHeight.tight',
+};
+
+/**
+ * Wagtail’s type scale styles, written with Tailwind theme function values,
+ * but in vanilla JS so the type scale can be reused outside of Tailwind.
+ */
+const typeScale = {
+  'w-h1': {
+    fontSize: 'fontSize.30',
+    fontWeight: 'fontWeight.extrabold',
+    color: 'colors.primary.DEFAULT',
+    lineHeight: 'lineHeight.tight',
+  },
+  'w-h2': {
+    fontSize: 'fontSize.24',
+    ...headingBaseStyles,
+  },
+  'w-h3': {
+    fontSize: 'fontSize.22',
+    ...headingBaseStyles,
+  },
+  'w-h4': {
+    fontSize: 'fontSize.18',
+    ...headingBaseStyles,
+  },
+  'w-label-1': {
+    fontSize: 'fontSize.16',
+    fontWeight: 'fontWeight.bold',
+    color: 'colors.primary.DEFAULT',
+    lineHeight: 'lineHeight.tight',
+  },
+  'w-label-2': {
+    fontSize: 'fontSize.15',
+    fontWeight: 'fontWeight.semibold',
+    color: 'colors.primary.DEFAULT',
+    lineHeight: 'lineHeight.tight',
+  },
+  'w-label-3': {
+    fontSize: 'fontSize.14',
+    fontWeight: 'fontWeight.medium',
+    color: 'colors.primary.DEFAULT',
+    lineHeight: 'lineHeight.tight',
+  },
+  'w-body-text': {
+    fontSize: 'fontSize.16',
+    fontWeight: 'fontWeight.normal',
+    lineHeight: 'lineHeight.normal',
+  },
+  'w-body-text-large': {
+    fontSize: 'fontSize.18',
+    fontWeight: 'fontWeight.normal',
+    lineHeight: 'lineHeight.normal',
+  },
+  'w-help-text': {
+    fontSize: 'fontSize.14',
+    fontWeight: 'fontWeight.normal',
+    color: 'colors.grey.400',
+    lineHeight: 'lineHeight.tight',
+  },
+};
+
 module.exports = {
   systemUIFontStack,
   monoFontStack,
@@ -94,4 +159,5 @@ module.exports = {
   fontWeight,
   letterSpacing,
   lineHeight,
+  typeScale,
 };

client/src/tokens/typography.stories.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import { fontFamily, typeScale } from './typography';
+
+const description = `
+Wagtail’s color palette is structured as design tokens, available as CSS classes.
+`;
+
+export default {
+  title: 'Foundation / Typography',
+  parameters: {
+    docs: {
+      extractComponentDescription: () => description,
+    },
+  },
+};
+
+export const FontFamilies = () => (
+  <div>
+    <p>Wagtail’s brand font is a system font stack:</p>
+    <pre>{fontFamily.sans.join(', ')}</pre>
+  </div>
+);
+
+export const TypeScale = () => (
+  <table>
+    <caption>All text styles</caption>
+    <thead>
+      <tr>
+        <th scope="col">Style</th>
+        <th scope="col">Class</th>
+      </tr>
+    </thead>
+    <tbody>
+      {Object.keys(typeScale).map((textStyle) => (
+        <tr key={textStyle}>
+          <td>
+            <span className={`${textStyle} w-mt-4`}>
+              {textStyle.replace('w-', '')}
+            </span>
+          </td>
+          <td>
+            <code>{`.${textStyle}`}</code>
+          </td>
+        </tr>
+      ))}
+    </tbody>
+  </table>
+);

client/tailwind.config.js

@@ -10,6 +10,7 @@ const {
   fontWeight,
   letterSpacing,
   lineHeight,
+  typeScale,
 } = require('./src/tokens/typography');
 const { breakpoints } = require('./src/tokens/breakpoints');
 const {
@@ -22,7 +23,6 @@ const { spacing } = require('./src/tokens/spacing');
 /**
  * Plugins
  */
-const typeScale = require('./src/tokens/typeScale');
 const scrollbarThin = require('./src/plugins/scrollbarThin');
 
 /**
@@ -91,6 +91,20 @@ module.exports = {
     plugin(({ addVariant }) => {
       addVariant('forced-colors', '@media (forced-colors: active)');
     }),
+    /**
+     * TypeScale plugin.
+     * This plugin generates component classes using tailwind's configuration for each object inside of the typeScale const.
+     * If the tailwind config is using a prefix such as 'w-' this will be included in the compiled css class eg. .w-h1
+     */
+    plugin(({ addComponents, theme }) => {
+      const scale = {};
+      Object.entries(typeScale).forEach(([name, styles]) => {
+        scale[`.${name.replace('w-', '')}`] = Object.fromEntries(
+          Object.entries(styles).map(([key, value]) => [key, theme(value)]),
+        );
+      });
+      addComponents(scale);
+    }),
   ],
   corePlugins: {
     ...vanillaRTL.disabledCorePlugins,

tailwind.config.js

@@ -8,7 +8,7 @@ module.exports = {
   content: [
     './wagtail/**/*.{py,html,ts,tsx}',
     './wagtail/**/static_src/**/*.js',
-    './client/**/*.{js,ts,tsx}',
+    './client/**/*.{js,ts,tsx,mdx}',
     './docs/**/*.{md,rst}',
   ],
   corePlugins: {