From 392fb9ad6dab4d7359e03b1057f6713547fe951f Mon Sep 17 00:00:00 2001
From: Jon McClure <jon.r.mcclure@gmail.com>
Date: Fri, 7 Jul 2023 21:27:55 +0100
Subject: [PATCH] cleanup typography docs and Theme types

---
 src/components/Theme/@types/component.ts      |  52 ++++---
 src/components/Theme/Theme.stories.svelte     |   4 +-
 .../Theme/stories/docs/customise.md           |   2 +-
 src/components/Theme/themes/common.js         |  38 +++++
 src/components/Theme/themes/dark.js           |  34 +----
 src/components/Theme/themes/light.js          |  35 +----
 src/docs/docStyles.scss                       |  17 ---
 src/docs/typography/MdxTheme.jsx              |  29 ++++
 src/docs/typography/custom-fonts.stories.mdx  |   2 +-
 src/docs/typography/docs/FaceDemo.svelte      |  20 ---
 src/docs/typography/docs/SizeDemo.svelte      |  20 ---
 src/docs/typography/docs/StyleDemo.svelte     |  17 ---
 src/docs/typography/docs/face.md              |  38 -----
 src/docs/typography/docs/size.md              |  49 -------
 src/docs/typography/docs/style.md             | 132 ------------------
 src/docs/typography/{ => imgs}/demo.png       | Bin
 src/docs/typography/{ => imgs}/gfonts.png     | Bin
 .../typography/{ => imgs}/type-guides.png     | Bin
 src/docs/typography/{ => imgs}/typeset.png    | Bin
 src/docs/typography/intro.stories.mdx         |   6 +-
 src/docs/typography/styles.scss               |  12 ++
 src/docs/typography/using                     |   0
 .../typography/using-faces.stories.svelte     |  36 -----
 .../typography/using-sizes.stories.svelte     |  38 -----
 .../typography/using-styles.stories.svelte    |  40 ------
 .../typography/using-the-system.stories.mdx   |  68 +++++----
 26 files changed, 166 insertions(+), 523 deletions(-)
 create mode 100644 src/components/Theme/themes/common.js
 create mode 100644 src/docs/typography/MdxTheme.jsx
 delete mode 100644 src/docs/typography/docs/FaceDemo.svelte
 delete mode 100644 src/docs/typography/docs/SizeDemo.svelte
 delete mode 100644 src/docs/typography/docs/StyleDemo.svelte
 delete mode 100644 src/docs/typography/docs/face.md
 delete mode 100644 src/docs/typography/docs/size.md
 delete mode 100644 src/docs/typography/docs/style.md
 rename src/docs/typography/{ => imgs}/demo.png (100%)
 rename src/docs/typography/{ => imgs}/gfonts.png (100%)
 rename src/docs/typography/{ => imgs}/type-guides.png (100%)
 rename src/docs/typography/{ => imgs}/typeset.png (100%)
 create mode 100644 src/docs/typography/styles.scss
 delete mode 100644 src/docs/typography/using
 delete mode 100644 src/docs/typography/using-faces.stories.svelte
 delete mode 100644 src/docs/typography/using-sizes.stories.svelte
 delete mode 100644 src/docs/typography/using-styles.stories.svelte

diff --git a/src/components/Theme/@types/component.ts b/src/components/Theme/@types/component.ts
index 7a1bbed8..6bf72f0a 100644
--- a/src/components/Theme/@types/component.ts
+++ b/src/components/Theme/@types/component.ts
@@ -1,5 +1,6 @@
 interface Scale {
   'size-base': number,
+  'size-base-mobile': number;
   'size-1': string,
   'size-2': string,
   'size-3': string,
@@ -25,31 +26,44 @@ interface Colour {
   'brand-shadow': string;
 };
 
+interface FontFamily {
+  'hed': string;
+  'subhed': string;
+  'body': string;
+  'note': string;
+}
+
+interface FontSize {
+  'hed': string;
+  'subhed-1': string;
+  'subhed-2': string;
+  'subhed-3': string;
+  'body': string;
+  'note-1': string;
+  'note-2': string;
+  'note-3': string;
+}
+
 interface Font {
-  'family-hed': string;
-  'family-subhed': string;
-  'family-body': string;
-  'family-note': string;
-  'size-hed': string;
-  'size-subhed-1': string;
-  'size-subhed-2': string;
-  'size-subhed-3': string;
-  'size-body': string;
-  'size-note-1': string;
-  'size-note-2': string;
-  'size-note-3': string;
+  family: FontFamily;
+  size: FontSize;
+}
+
+interface CustomFont {
+  family?: Partial<FontFamily>;
+  size?: Partial<FontSize>;
 }
 
 export interface Theme {
-  scale: Scale,
-  typeface: Typeface
-  colour: Colour,
+  scale: Scale;
+  typeface: Typeface;
+  colour: Colour;
   font: Font;
 };
 
 export interface CustomTheme {
-  scale?: Partial<Scale>,
-  typeface?: Partial<Typeface>,
-  colour?: Partial<Colour>,
-  font?: Partial<Font>
+  scale?: Partial<Scale>;
+  typeface?: Partial<Typeface>;
+  colour?: Partial<Colour>;
+  font?: Partial<CustomFont>;
 }
diff --git a/src/components/Theme/Theme.stories.svelte b/src/components/Theme/Theme.stories.svelte
index 75ee6d8d..ec357e33 100644
--- a/src/components/Theme/Theme.stories.svelte
+++ b/src/components/Theme/Theme.stories.svelte
@@ -55,7 +55,7 @@
     base="dark"
     theme="{{
       colour: { accent: 'yellow' },
-      font: { 'family-hed': 'freight-book' },
+      font: { family: { hed: 'freight-book' } },
     }}"
   >
     <ThemedPage />
@@ -91,7 +91,7 @@
           <Theme
             theme="{{
               colour: { background: 'steelblue', 'text-primary': '#fff' },
-              font: { 'family-note': 'freight-book' },
+              font: { family: { note: 'freight-book' } },
             }}"
             base="dark"
           >
diff --git a/src/components/Theme/stories/docs/customise.md b/src/components/Theme/stories/docs/customise.md
index d9f50b30..114c98d5 100644
--- a/src/components/Theme/stories/docs/customise.md
+++ b/src/components/Theme/stories/docs/customise.md
@@ -20,7 +20,7 @@ Check out the "Control" column for `theme` in the properties table above to see
   base="dark"
   theme="{{
     colour: { accent: 'yellow' },
-    font: { 'family-hed': 'freight-book' },
+    font: { family: { hed: 'freight-book' } },
   }}"
 >
   <!-- Page content -->
diff --git a/src/components/Theme/themes/common.js b/src/components/Theme/themes/common.js
new file mode 100644
index 00000000..3c2cf027
--- /dev/null
+++ b/src/components/Theme/themes/common.js
@@ -0,0 +1,38 @@
+/** @type {Omit<import('../@types/component').Theme, "colour">} */
+export default {
+  scale: {
+    'size-base': 1.375,
+    'size-base-mobile': 1.125,
+    'size-1': 'calc(var(--theme-scale-size-base) * 2.25rem)',
+    'size-2': 'calc(var(--theme-scale-size-base) * 1.5rem)',
+    'size-3': 'calc(var(--theme-scale-size-base) * 1rem)',
+    'size-4': 'calc(var(--theme-scale-size-base) * 0.9rem)',
+    'size-5': 'calc(var(--theme-scale-size-base) * 0.72rem)',
+    'size-6': 'calc(var(--theme-scale-size-base) * 0.66rem)',
+  },
+  typeface: {
+    display: 'Knowledge, sans-serif',
+    serif: 'freight-book, serif',
+    'sans-serif': 'Knowledge, sans-serif',
+    monospace:
+      'Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+  },
+  font: {
+    family: {
+      hed: 'var(--theme-typeface-display)',
+      subhed: 'var(--theme-typeface-sans-serif)',
+      body: 'var(--theme-typeface-serif)',
+      note: 'var(--theme-typeface-sans-serif)',
+    },
+    size: {
+      hed: 'var(--theme-scale-size-1)',
+      'subhed-1': 'var(--theme-scale-size-2)',
+      'subhed-2': 'var(--theme-scale-size-3)',
+      'subhed-3': 'var(--theme-scale-size-6)',
+      body: 'var(--theme-scale-size-3)',
+      'note-1': 'var(--theme-scale-size-4)',
+      'note-2': 'var(--theme-scale-size-5)',
+      'note-3': 'var(--theme-scale-size-6)',
+    },
+  },
+};
diff --git a/src/components/Theme/themes/dark.js b/src/components/Theme/themes/dark.js
index 7d591a05..96ce7be8 100644
--- a/src/components/Theme/themes/dark.js
+++ b/src/components/Theme/themes/dark.js
@@ -1,36 +1,8 @@
+import common from './common.js';
+
 /** @type {import('../@types/component').Theme} */
 export default {
-  scale: {
-    'size-base': 1.375,
-    'size-base-mobile': 1.125,
-    'size-1': 'calc(var(--theme-scale-size-base) * 2.25rem)',
-    'size-2': 'calc(var(--theme-scale-size-base) * 1.5rem)',
-    'size-3': 'calc(var(--theme-scale-size-base) * 1rem)',
-    'size-4': 'calc(var(--theme-scale-size-base) * 0.9rem)',
-    'size-5': 'calc(var(--theme-scale-size-base) * 0.72rem)',
-    'size-6': 'calc(var(--theme-scale-size-base) * 0.66rem)',
-  },
-  typeface: {
-    display: 'Knowledge, sans-serif',
-    serif: 'freight-book, serif',
-    'sans-serif': 'Knowledge, sans-serif',
-    monospace:
-      'Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
-  },
-  font: {
-    'family-hed': 'var(--theme-typeface-display)',
-    'family-subhed': 'var(--theme-typeface-sans-serif)',
-    'family-body': 'var(--theme-typeface-serif)',
-    'family-note': 'var(--theme-typeface-sans-serif)',
-    'size-hed': 'var(--theme-scale-size-1)',
-    'size-subhed-1': 'var(--theme-scale-size-2)',
-    'size-subhed-2': 'var(--theme-scale-size-3)',
-    'size-subhed-3': 'var(--theme-scale-size-6)',
-    'size-body': 'var(--theme-scale-size-3)',
-    'size-note-1': 'var(--theme-scale-size-4)',
-    'size-note-2': 'var(--theme-scale-size-5)',
-    'size-note-3': 'var(--theme-scale-size-6)',
-  },
+  ...common,
   colour: {
     background: '#2e3440',
     'text-primary': '#ffffff',
diff --git a/src/components/Theme/themes/light.js b/src/components/Theme/themes/light.js
index 8817d8e7..1f62909d 100644
--- a/src/components/Theme/themes/light.js
+++ b/src/components/Theme/themes/light.js
@@ -1,35 +1,8 @@
+import common from './common.js';
+
+/** @type {import('../@types/component').Theme} */
 export default {
-  scale: {
-    'size-base': 1.375,
-    'size-base-mobile': 1.125,
-    'size-1': 'calc(var(--theme-scale-size-base) * 2.25rem)',
-    'size-2': 'calc(var(--theme-scale-size-base) * 1.5rem)',
-    'size-3': 'calc(var(--theme-scale-size-base) * 1rem)',
-    'size-4': 'calc(var(--theme-scale-size-base) * 0.9rem)',
-    'size-5': 'calc(var(--theme-scale-size-base) * 0.72rem)',
-    'size-6': 'calc(var(--theme-scale-size-base) * 0.66rem)',
-  },
-  typeface: {
-    display: 'Knowledge, sans-serif',
-    serif: 'freight-book, serif',
-    'sans-serif': 'Knowledge, sans-serif',
-    monospace:
-      'Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
-  },
-  font: {
-    'family-hed': 'var(--theme-typeface-display)',
-    'family-subhed': 'var(--theme-typeface-sans-serif)',
-    'family-body': 'var(--theme-typeface-serif)',
-    'family-note': 'var(--theme-typeface-sans-serif)',
-    'size-hed': 'var(--theme-scale-size-1)',
-    'size-subhed-1': 'var(--theme-scale-size-2)',
-    'size-subhed-2': 'var(--theme-scale-size-3)',
-    'size-subhed-3': 'var(--theme-scale-size-6)',
-    'size-body': 'var(--theme-scale-size-3)',
-    'size-note-1': 'var(--theme-scale-size-4)',
-    'size-note-2': 'var(--theme-scale-size-5)',
-    'size-note-3': 'var(--theme-scale-size-6)',
-  },
+  ...common,
   colour: {
     background: '#ffffff',
     'text-primary': '#404040',
diff --git a/src/docs/docStyles.scss b/src/docs/docStyles.scss
index 30b8b6db..451f89a2 100644
--- a/src/docs/docStyles.scss
+++ b/src/docs/docStyles.scss
@@ -4,23 +4,6 @@ img.feature {
   display: block;
 }
 
-div.type-system-demo {
-  // @TODO import type mixins here to apply styles to demos...
-  margin: 2rem auto;
-  background-color: #ededed;
-  padding: 15px 20px;
-  border: 1px solid #ccc;
-  border-radius: 4px;
-
-  *:first-child {
-    margin-top: 0;
-  }
-
-  *:last-child {
-    margin-bottom: 0;
-  }
-}
-
 #custom-table {
   [data-field='Net worth (in billions)'] {
     text-align: right;
diff --git a/src/docs/typography/MdxTheme.jsx b/src/docs/typography/MdxTheme.jsx
new file mode 100644
index 00000000..c579fe8f
--- /dev/null
+++ b/src/docs/typography/MdxTheme.jsx
@@ -0,0 +1,29 @@
+import { Canvas, Unstyled } from '@storybook/blocks';
+
+import React from 'react';
+import flatten from '../../components/Theme/utils/flatten';
+import lightTheme from '../../components/Theme/themes/light';
+
+// This is a React equivalent for the Svelte Theme component
+// which is useful for setting CSS variables in MDX docs around
+// typography demos. It also wraps demos in a unstyled storybook 
+// canvas.
+
+const ThemeWrapper = (props) => {
+  const theme = flatten(lightTheme);
+  const styleObj = {};
+  Object.keys(theme).map(key => {
+    styleObj[`--theme-${key}`] = theme[key];
+  });
+  return (
+    <Unstyled>
+      <Canvas>
+        <div className="my-theme-wrapper" style={styleObj}>
+          {props.children}
+        </div>
+      </Canvas>
+    </Unstyled>
+  );
+}
+
+export default ThemeWrapper;
\ No newline at end of file
diff --git a/src/docs/typography/custom-fonts.stories.mdx b/src/docs/typography/custom-fonts.stories.mdx
index ea3cba1d..7c1d44ac 100644
--- a/src/docs/typography/custom-fonts.stories.mdx
+++ b/src/docs/typography/custom-fonts.stories.mdx
@@ -1,7 +1,7 @@
 import { Meta } from '@storybook/addon-docs';
 import { parameters } from '$docs/utils/docsPage.js';
 
-import Gfont from './gfonts.png';
+import Gfont from './imgs/gfonts.png';
 
 <Meta title="Typography/Adding custom fonts" parameters={{ ...parameters }} />
 
diff --git a/src/docs/typography/docs/FaceDemo.svelte b/src/docs/typography/docs/FaceDemo.svelte
deleted file mode 100644
index f9666653..00000000
--- a/src/docs/typography/docs/FaceDemo.svelte
+++ /dev/null
@@ -1,20 +0,0 @@
-<script>
-  /**
-   * font family
-   * @type {string}
-   */
-  export let face = 'typeface-serif';
-</script>
-
-<div class="{face}">
-  As mass-printing technologies like the printing press spread, newspapers were
-  established to provide increasingly literate audiences with the news. The
-  first references to privately owned newspaper publishers in China date to the
-  late Ming dynasty in 1582. Johann Carolus's Relation aller Fürnemmen und
-  gedenckwürdigen Historien, published in 1605 in Strasbourg, is often
-  recognized as the first newspaper in Europe.
-</div>
-
-<style lang="scss">
-  @import '../../../scss/typography/main';
-</style>
diff --git a/src/docs/typography/docs/SizeDemo.svelte b/src/docs/typography/docs/SizeDemo.svelte
deleted file mode 100644
index af2476f6..00000000
--- a/src/docs/typography/docs/SizeDemo.svelte
+++ /dev/null
@@ -1,20 +0,0 @@
-<script>
-  /**
-   * font size level
-   * @type {string}
-   */
-  export let size = 'font-size-3';
-</script>
-
-<div class="{size}">
-  As mass-printing technologies like the printing press spread, newspapers were
-  established to provide increasingly literate audiences with the news. The
-  first references to privately owned newspaper publishers in China date to the
-  late Ming dynasty in 1582. Johann Carolus's Relation aller Fürnemmen und
-  gedenckwürdigen Historien, published in 1605 in Strasbourg, is often
-  recognized as the first newspaper in Europe.
-</div>
-
-<style lang="scss">
-  @import '../../../scss/typography/main';
-</style>
diff --git a/src/docs/typography/docs/StyleDemo.svelte b/src/docs/typography/docs/StyleDemo.svelte
deleted file mode 100644
index d08742e3..00000000
--- a/src/docs/typography/docs/StyleDemo.svelte
+++ /dev/null
@@ -1,17 +0,0 @@
-<script>
-  /**
-   * font class
-   * @type {string}
-   */
-  export let textClass = 'font-body';
-</script>
-
-<div class="{textClass}">
-  The agency was established in London in 1851 by the German-born Paul Julius
-  Reuter. It was acquired by the Thomson Corporation of Canada in 2008 and now
-  makes up the media division of Thomson Reuters.
-</div>
-
-<style lang="scss">
-  @import '../../../scss/typography/main';
-</style>
diff --git a/src/docs/typography/docs/face.md b/src/docs/typography/docs/face.md
deleted file mode 100644
index b57d0ef4..00000000
--- a/src/docs/typography/docs/face.md
+++ /dev/null
@@ -1,38 +0,0 @@
-There are four font families provided via the `Theme`, which feeds into all the text styles. If you need to specifically apply font family styles to your HTML elements, you can use the following methods.
-
-<br />
-
-These are the available **font family types** and their **corresponding tokens**. Check out the CSS variables in the Styling section to see the default values assigned by the Theme.
-
-| typeface        | class                  | mixin                 | CSS vars used from Theme      |
-| --------------- | ---------------------- | --------------------- | ----------------------------- |
-| Display font    | `.typeface-display`    | `typeface-display`    | `--theme-typeface-display`    |
-| Serif font      | `.typeface-serif`      | `typeface-serif`      | `--theme-typeface-serif`      |
-| Sans-serif font | `.typeface-sans-serif` | `typeface-sans-serif` | `--theme-typeface-sans-serif` |
-| Monospace font  | `.typeface-monospace`  | `typeface-monospace`  | `--theme-typeface-monospace`  |
-
-## With CSS classes
-
-Add the `typeface-` class to any element for the classes to take effect. Check out the available classes and their associated sizes in the example below.
-
-```svelte
-<div class="typeface-serif">...your text here</div>
-```
-
-## With SCSS mixins
-
-Include the mixins in your stylesheets as shown below.
-
-```svelte
-<div class="my-class">...your text here</div>
-
-<style lang="scss">
-  @import '@reuters-graphics/graphics-components/dist/scss/typography/_main.scss';
-
-  .my-class {
-    @include typeface-serif;
-  }
-</style>
-```
-
-## See the typefaces in action
diff --git a/src/docs/typography/docs/size.md b/src/docs/typography/docs/size.md
deleted file mode 100644
index b8a0aba0..00000000
--- a/src/docs/typography/docs/size.md
+++ /dev/null
@@ -1,49 +0,0 @@
-The font sizes are used to style the various elements on the page, including margins and padding utilities. This is to ensure the harmonic rhythm of the page set by the system.
-
-You may need to use the sizes from this scale in situations like -
-
-- Adding sizes in your custom svelte component
-- Sizing chart elemnents in D3
-- Defining bespoke style beyond what is provided by the [Text styles](/docs/typography-how-to-use--text-styles)
-
-<br />
-
-These are the available **text size levels** and their **corresponding tokens**. Check out the CSS variables in the Styling section to see the default values assigned by the Theme.
-
-| level | class          | mixin         | CSS vars used from Theme |
-| ----- | -------------- | ------------- | ------------------------ |
-| 1     | `.font-size-1` | `font-size-1` | `--theme-scale-size-1`   |
-| 2     | `.font-size-2` | `font-size-2` | `--theme-scale-size-2`   |
-| 3     | `.font-size-3` | `font-size-3` | `--theme-scale-size-3`   |
-| 4     | `.font-size-4` | `font-size-4` | `--theme-scale-size-4`   |
-| 5     | `.font-size-5` | `font-size-5` | `--theme-scale-size-5`   |
-| 6     | `.font-size-6` | `font-size-6` | `--theme-scale-size-6`   |
-
-> The text sizes are always a multiple of `size-base = 1.375`. On mobile
-> {max-width:510px}, levels 1, 2, 3, 4 scale down to `size-base-mobile = 1.125`
-
-## With CSS classes
-
-Add the `font-size-*` class to any element for the classes to take effect, where `*` = 1 to 6. Check out the available classes and their associated sizes in the example below.
-
-```svelte
-<div class="font-body">...your text here</div>
-```
-
-## With SCSS mixins
-
-Include the mixins in your stylesheets as shown below.
-
-```svelte
-<div class="my-class">...your text here</div>
-
-<style lang="scss">
-  @import '@reuters-graphics/graphics-components/dist/scss/typography/_main.scss';
-
-  .my-class {
-    @include font-size-3;
-  }
-</style>
-```
-
-## See the text size levels in action
diff --git a/src/docs/typography/docs/style.md b/src/docs/typography/docs/style.md
deleted file mode 100644
index a9f8d7ef..00000000
--- a/src/docs/typography/docs/style.md
+++ /dev/null
@@ -1,132 +0,0 @@
-The styles are automatically applied to native HTML elements like the `H` and `p` tag.
-
-```svelte
-<div>
-  <h2>Here's a section title</h2>
-  <p>and some text to go with it...</p>
-</div>
-```
-
-These are the available **text styles** and their **corresponding tokens**. The `font-size-` inherits the sizes based on the scale as described by the [Type System](/docs/typography-intro--page). Check out the CSS variables in the Styling section to see the default values and roles assigned by the Theme.
-
-| Style         | class            | mixin           | CSS vars used from Theme                                                                     |
-| ------------- | ---------------- | --------------- | -------------------------------------------------------------------------------------------- |
-| Page title    | `.font-hed`      | `font-hed`      | `--theme-font-size-hed`, `--theme-font-family-hed` , `--theme-colour-text-primary`           |
-| Section title | `.font-subhed-1` | `font-subhed-1` | `--theme-font-size-subhed-1`, `--theme-font-family-subhed` , `--theme-colour-text-primary`   |
-| Subhed        | `.font-subhed-2` | `font-subhed-2` | `--theme-font-size-subhed-2`, `--theme-font-family-subhed` , `--theme-colour-text-primary`   |
-| Smallhed      | `.font-subhed-3` | `font-subhed-3` | `--theme-font-size-subhed-3`, `--theme-font-family-subhed` , `--theme-colour-text-secondary` |
-| Body text     | `.font-body`     | `font-body`     | `--theme-font-size-body`, `--theme-font-family-body` , `--theme-colour-text-primary`         |
-| Body note     | `.font-note-1`   | `font-note-1`   | `--theme-font-size-note-1`, `--theme-font-family-note` , `--theme-colour-text-primary`       |
-| Endnotes      | `.font-note-2`   | `font-note-2`   | `--theme-font-size-note-2`, `--theme-font-family-note` , `--theme-colour-text-secondary`     |
-| Footnotes     | `.font-note-3`   | `font-note-3`   | `--theme-font-size-note-3`, `--theme-font-family-note` , `--theme-colour-text-secondary`     |
-
-## Styling with with CSS classes
-
-> This is the most common way you probably will add styles inside your svelte components in the HTML code.
-
-Add the `font-` class to any element for the classes to take effect.
-
-```svelte
-<!-- div using body font style -->
-<div class="font-body">
-  Two hardy boxing kangaroos jet from Sydney to Zanzibar on quicksilver pinions.
-</div>
-
-<!-- Text using body font style -->
-<p class="font-body">
-  Back in my quaint garden jaunty zinnias vie with flaunting phlox.
-</p>
-```
-
-It is a good practice to not use `<h>` tags unless it is a heading level due to _a11y_ concerns. You should use the CSS styles instead for your elements to style it like a heading.
-
-```svelte
-<!-- Text which is not a heading, but using a heading style -->
-<p class="font-subhed-3">
-  The vegetarian menu included gazpacho, piquant julienne beets, rusk rounds
-  with yogurt, and excellent flan.
-</p>
-```
-
-You can also use the clases for styling text elemnets in SVG charts.
-
-```svelte
-<!-- Text which is not a heading, but using a heading style -->
-<text class="font-note-3">Gazpacho</text>
-<text class="font-note-3">Baguette</text>
-<text class="font-note-3">Lamb Biryani</text>
-```
-
-## Styling with with SCSS mixins
-
-[Mixins](https://sass-lang.com/documentation/at-rules/mixin) allow you to define styles that can be re-used throughout your stylesheet. This is useful when you need to compose styles for elements using your own classes, while using some predefined styles.
-
-Include the mixins in your SCSS code block as shown below.
-
-```svelte
-<div class="my-class">
-  The July sun caused a fragment of black pine wax to ooze on the velvet quilt.
-</div>
-
-<style lang="scss">
-  @import '@reuters-graphics/graphics-components/dist/scss/typography/_main.scss';
-
-  .my-class {
-    @include font-note-3;
-  }
-</style>
-```
-
-The mixins also allow you to add the styles as `!important` to overrule any other styles. You can specify it using `($i: true)` arg while including the mixin.
-
-```scss
-.my-class {
-  @include font-note-3($i: true);
-  // more style declarations...
-}
-```
-
-The above code will effectively compile to the following CSS:
-
-```scss
-.my-class {
-  font-size: var(--theme-font-size-note-3) !important;
-  font-family: var(--theme-font-family-note) !important;
-  font-weight: 400 !important;
-  line-height: 1.4 !important;
-  color: var(--theme-colour-text-secondary) !important;
-  // more style declarations...
-}
-```
-
-## Customising text styles
-
-Since the styles are inherited from the `--theme-font-*` and `--theme-colour-*`CSS variables, any modifcation must happen in the `<Theme>` component in `page.svelte`. Read how to [customise CSS variables](../?path=/docs/theming-theme--custom-theme).
-
-### Example: Changing the font family for the page title
-
-Page title uses `--theme-font-family-hed` to define the font family, which inherits `--theme-typeface-display` (refer the [CSS variables](../?path=/docs/theming-css-variables--page)). Hence, in this case, you should redefine the `--theme-typeface-display` and the changes should reflect on your page.
-
-If you want to redefine `--theme-font-family-hed` independently, you should add a new CSS typeface variable (e.g. `--theme-typeface-hed`) and assign it to the text style variable.
-
-```svelte
-<Theme
-  base="light"
-  theme="{{
-    typeface: {
-      // New CSS variable
-      hed: 'Playfair Display',
-    },
-    font: {
-      // Assign the new typeface variable
-      'family-hed': 'var(--theme-typeface-hed)',
-    },
-  }}"
->
-  <!-- page stuff -->
-</Theme>
-```
-
-## See the styles in action
-
-Select a style from the menu in the `control` column and see it added to the text.
diff --git a/src/docs/typography/demo.png b/src/docs/typography/imgs/demo.png
similarity index 100%
rename from src/docs/typography/demo.png
rename to src/docs/typography/imgs/demo.png
diff --git a/src/docs/typography/gfonts.png b/src/docs/typography/imgs/gfonts.png
similarity index 100%
rename from src/docs/typography/gfonts.png
rename to src/docs/typography/imgs/gfonts.png
diff --git a/src/docs/typography/type-guides.png b/src/docs/typography/imgs/type-guides.png
similarity index 100%
rename from src/docs/typography/type-guides.png
rename to src/docs/typography/imgs/type-guides.png
diff --git a/src/docs/typography/typeset.png b/src/docs/typography/imgs/typeset.png
similarity index 100%
rename from src/docs/typography/typeset.png
rename to src/docs/typography/imgs/typeset.png
diff --git a/src/docs/typography/intro.stories.mdx b/src/docs/typography/intro.stories.mdx
index 1883d19d..ca163263 100644
--- a/src/docs/typography/intro.stories.mdx
+++ b/src/docs/typography/intro.stories.mdx
@@ -1,9 +1,9 @@
 import { Meta } from '@storybook/addon-docs';
 import { parameters } from '$docs/utils/docsPage.js';
 
-import Typeset from './typeset.png';
-import TypeGuides from './type-guides.png';
-import DemoImg from './demo.png';
+import Typeset from './imgs/typeset.png';
+import TypeGuides from './imgs/type-guides.png';
+import DemoImg from './imgs/demo.png';
 
 <Meta title="Typography/Intro" parameters={{ ...parameters }} />
 
diff --git a/src/docs/typography/styles.scss b/src/docs/typography/styles.scss
new file mode 100644
index 00000000..7042ce3f
--- /dev/null
+++ b/src/docs/typography/styles.scss
@@ -0,0 +1,12 @@
+div.type-system-demo {
+  @import '../../scss/typography/mixins';
+  @import '../../scss/typography/classes';
+
+  *:first-child {
+    margin-top: 0;
+  }
+
+  *:last-child {
+    margin-bottom: 0;
+  }
+}
diff --git a/src/docs/typography/using b/src/docs/typography/using
deleted file mode 100644
index e69de29b..00000000
diff --git a/src/docs/typography/using-faces.stories.svelte b/src/docs/typography/using-faces.stories.svelte
deleted file mode 100644
index bf82cd75..00000000
--- a/src/docs/typography/using-faces.stories.svelte
+++ /dev/null
@@ -1,36 +0,0 @@
-<script>
-  import { Meta, Story } from '@storybook/addon-svelte-csf';
-
-  import {
-    withComponentDocs,
-    withStoryDocs,
-  } from '$lib/docs/utils/withParams.js';
-
-  import FaceDemo from './docs/FaceDemo.svelte';
-
-  // @ts-ignore
-  import face from './docs/face.md?raw';
-
-  const meta = {
-    title: 'Typography/Using the system',
-    component: FaceDemo,
-    ...withComponentDocs(face),
-    argTypes: {
-      face: {
-        control: 'select',
-        options: [
-          'typeface-display',
-          'typeface-serif',
-          'typeface-sans-serif',
-          'typeface-monospace',
-        ],
-      },
-    },
-  };
-</script>
-
-<Meta {...meta} />
-
-<Story let:args name="Typefaces" {...withStoryDocs(face)}>
-  <FaceDemo {...args} />
-</Story>
diff --git a/src/docs/typography/using-sizes.stories.svelte b/src/docs/typography/using-sizes.stories.svelte
deleted file mode 100644
index 6a79beb8..00000000
--- a/src/docs/typography/using-sizes.stories.svelte
+++ /dev/null
@@ -1,38 +0,0 @@
-<script>
-  import { Meta, Story } from '@storybook/addon-svelte-csf';
-
-  import {
-    withComponentDocs,
-    withStoryDocs,
-  } from '$lib/docs/utils/withParams.js';
-
-  import SizeDemo from './docs/SizeDemo.svelte';
-
-  // @ts-ignore
-  import size from './docs/size.md?raw';
-
-  const meta = {
-    title: 'Typography/Using the system',
-    component: SizeDemo,
-    ...withComponentDocs(size),
-    argTypes: {
-      size: {
-        control: 'select',
-        options: [
-          'font-size-1',
-          'font-size-2',
-          'font-size-3',
-          'font-size-4',
-          'font-size-5',
-          'font-size-6',
-        ],
-      },
-    },
-  };
-</script>
-
-<Meta {...meta} />
-
-<Story let:args name="Text sizes" {...withStoryDocs(size)}>
-  <SizeDemo {...args} />
-</Story>
diff --git a/src/docs/typography/using-styles.stories.svelte b/src/docs/typography/using-styles.stories.svelte
deleted file mode 100644
index 3b8b492a..00000000
--- a/src/docs/typography/using-styles.stories.svelte
+++ /dev/null
@@ -1,40 +0,0 @@
-<script>
-  import { Meta, Story } from '@storybook/addon-svelte-csf';
-
-  import {
-    withComponentDocs,
-    withStoryDocs,
-  } from '$lib/docs/utils/withParams.js';
-
-  import StyleDemo from './docs/StyleDemo.svelte';
-
-  // @ts-ignore
-  import style from './docs/style.md?raw';
-
-  const meta = {
-    title: 'Typography/Using the system',
-    component: StyleDemo,
-    ...withComponentDocs(style),
-    argTypes: {
-      textClass: {
-        control: 'select',
-        options: [
-          'font-hed',
-          'font-subhed-1',
-          'font-subhed-2',
-          'font-subhed-3',
-          'font-body',
-          'font-note-1',
-          'font-note-2',
-          'font-note-3',
-        ],
-      },
-    },
-  };
-</script>
-
-<Meta {...meta} />
-
-<Story let:args name="Text styles" {...withStoryDocs(style)}>
-  <StyleDemo {...args} />
-</Story>
diff --git a/src/docs/typography/using-the-system.stories.mdx b/src/docs/typography/using-the-system.stories.mdx
index 7361b2b0..b8d6edb7 100644
--- a/src/docs/typography/using-the-system.stories.mdx
+++ b/src/docs/typography/using-the-system.stories.mdx
@@ -1,5 +1,9 @@
 import { Meta } from '@storybook/addon-docs';
 import { parameters } from '$docs/utils/docsPage.js';
+import { Canvas, Unstyled } from '@storybook/blocks';
+import Theme from './MdxTheme.jsx';
+
+import './styles.scss';
 
 <Meta title="Typography/Using the type system" parameters={{ ...parameters }} />
 
@@ -33,10 +37,12 @@ Apply text styles to any element using CSS classes that correspond to each text
 <p class="font-note-1">Sans-serif text...</p>
 ```
 
-<div class="type-system-demo">
-  <div class="font-subhed-1">Subhed</div>
-  <p class="font-note-1">Sans-serif text...</p>
-</div>
+<Theme>
+  <div className="type-system-demo">
+    <div className="font-subhed-1">Subhed</div>
+    <p className="font-note-1">Sans-serif text...</p>
+  </div>
+</Theme>
 
 The following text style elements and corresponding classes are available:
 
@@ -51,16 +57,18 @@ The following text style elements and corresponding classes are available:
 | Endnotes      | `.font-note-2`   | `font-note-2`   | `--theme-font-size-note-2`, `--theme-font-family-note` , `--theme-colour-text-secondary`     |
 | Footnotes     | `.font-note-3`   | `font-note-3`   | `--theme-font-size-note-3`, `--theme-font-family-note` , `--theme-colour-text-secondary`     |
 
-<div class="type-system-demo">
-  <p class="font-hed">Lorem ipsum dolor sit amet...</p>
-  <p class="font-subhed-1">Lorem ipsum dolor sit amet...</p>
-  <p class="font-subhed-2">Lorem ipsum dolor sit amet...</p>
-  <p class="font-subhed-3">Lorem ipsum dolor sit amet...</p>
-  <p class="font-body">Lorem ipsum dolor sit amet...</p>
-  <p class="font-note-1">Lorem ipsum dolor sit amet...</p>
-  <p class="font-note-2">Lorem ipsum dolor sit amet...</p>
-  <p class="font-note-3">Lorem ipsum dolor sit amet...</p>
-</div>
+<Theme>
+  <div className="type-system-demo">
+    <p className="font-hed">Lorem ipsum dolor sit amet...</p>
+    <p className="font-subhed-1">Lorem ipsum dolor sit amet...</p>
+    <p className="font-subhed-2">Lorem ipsum dolor sit amet...</p>
+    <p className="font-subhed-3">Lorem ipsum dolor sit amet...</p>
+    <p className="font-body">Lorem ipsum dolor sit amet...</p>
+    <p className="font-note-1">Lorem ipsum dolor sit amet...</p>
+    <p className="font-note-2">Lorem ipsum dolor sit amet...</p>
+    <p className="font-note-3">Lorem ipsum dolor sit amet...</p>
+  </div>
+</Theme>
 
 ### Type sizes
 
@@ -75,14 +83,16 @@ The following classes apply specific text sizes to any element:
 | 5     | `.font-size-5` | `font-size-5` | `--theme-scale-size-5`   |
 | 6     | `.font-size-6` | `font-size-6` | `--theme-scale-size-6`   |
 
-<div class="type-system-demo">
-  <p class="font-size-1">Lorem ipsum dolor sit amet...</p>
-  <p class="font-size-2">Lorem ipsum dolor sit amet...</p>
-  <p class="font-size-3">Lorem ipsum dolor sit amet...</p>
-  <p class="font-size-4">Lorem ipsum dolor sit amet...</p>
-  <p class="font-size-5">Lorem ipsum dolor sit amet...</p>
-  <p class="font-size-6">Lorem ipsum dolor sit amet...</p>
-</div>
+<Theme>
+  <div className="type-system-demo">
+    <p className="font-size-1">Lorem ipsum dolor sit amet...</p>
+    <p className="font-size-2">Lorem ipsum dolor sit amet...</p>
+    <p className="font-size-3">Lorem ipsum dolor sit amet...</p>
+    <p className="font-size-4">Lorem ipsum dolor sit amet...</p>
+    <p className="font-size-5">Lorem ipsum dolor sit amet...</p>
+    <p className="font-size-6">Lorem ipsum dolor sit amet...</p>
+  </div>
+</Theme>
 
 > The text sizes are always a multiple of `size-base = 1.375`. On mobile
 > max-width:510px, levels 1, 2, 3, 4 scale down to `size-base-mobile = 1.125`
@@ -98,9 +108,11 @@ The following classes apply typefaces to any element:
 | Sans-serif font | `.typeface-sans-serif` | `typeface-sans-serif` | `--theme-typeface-sans-serif` |
 | Monospace font  | `.typeface-monospace`  | `typeface-monospace`  | `--theme-typeface-monospace`  |
 
-<div class="type-system-demo">
-  <p class="typeface-display">Lorem ipsum dolor sit amet...</p>
-  <p class="typeface-serif">Lorem ipsum dolor sit amet...</p>
-  <p class="typeface-sans-serif">Lorem ipsum dolor sit amet...</p>
-  <p class="typeface-monospace">Lorem ipsum dolor sit amet...</p>
-</div>
+<Theme>
+  <div className="type-system-demo">
+    <p className="typeface-display">Lorem ipsum dolor sit amet...</p>
+    <p className="typeface-serif">Lorem ipsum dolor sit amet...</p>
+    <p className="typeface-sans-serif">Lorem ipsum dolor sit amet...</p>
+    <p className="typeface-monospace">Lorem ipsum dolor sit amet...</p>
+  </div>
+</Theme>