diff --git a/.storybook/preview.ts b/.storybook/preview.ts
index 4658f565..aa5a0770 100644
--- a/.storybook/preview.ts
+++ b/.storybook/preview.ts
@@ -53,25 +53,23 @@ export const parameters = {
'Styles',
[
'Intro',
- 'Typography', [
- 'Main',
- 'Intro',
- 'Using the type system',
- '*',
- ],
- 'Layout', [
- 'Main',
- 'Spacers',
- 'Flexbox',
- '*',
- ],
- 'Borders',
'Colours', [
'Intro',
'Primary',
'Thematic',
'*',
- ]
+ ],
+ 'Tokens', [
+ 'Intro',
+ 'Typography',
+ '*',
+ 'Layout', [
+ 'Main',
+ 'Spacers',
+ 'Flexbox',
+ '*',
+ ],
+ ],
],
'Actions',
['Intro', '*'],
diff --git a/src/components/Headline/Headline.svelte b/src/components/Headline/Headline.svelte
index c73e8e82..ac89abf2 100644
--- a/src/components/Headline/Headline.svelte
+++ b/src/components/Headline/Headline.svelte
@@ -69,8 +69,8 @@
diff --git a/src/docs/scss/css-variables.stories.mdx b/src/docs/scss/css-variables.stories.mdx
deleted file mode 100644
index 7f40fe47..00000000
--- a/src/docs/scss/css-variables.stories.mdx
+++ /dev/null
@@ -1,52 +0,0 @@
-import { Meta } from '@storybook/addon-docs';
-import { parameters } from '$docs/utils/docsPage.js';
-
-
-
-
-
-# CSS variables
-
-Several [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) are provided by the [`Theme`](?path=/docs/components-theme--default) component. All other components in this library use these variables for styling basic colours and typography. You can (and probably _should_) use them in you own code, too.
-
-> In the future, client's may be allowed to override our CSS variables to match their own house styles. So when using CSS variables, it's a good idea to set a [fallback value](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties#custom_property_fallback_values), in case a client misconfigures a variable override.
->
-> **Note:** CSS variables do not currently affect [ai2svelte](https://github.com/reuters-graphics/ai2svelte/) graphics, so you should continue to make sure your colours match the theme of your page directly in Adobe Illustrator for those graphics.
-
-```svelte
-
My custom text
-
-
-```
-
-## Variables
-
-### Colours
-
-| CSS variable | Role |
-| ------------------------------- | ------------------------------- |
-| `--theme-colour-background` | Background colour |
-| `--theme-colour-text-primary` | Primary text colour body text |
-| `--theme-colour-text-secondary` | Secondary text colour for notes |
-| `--theme-colour-accent` | A single accent colour |
-| `--theme-colour-brand-logo` | Reuters logo kinesis colour |
-| `--theme-colour-brand-rules` | Rules in header and footer |
-| `--theme-colour-brand-shadow` | Box shadow on header |
-
-### Fonts
-
-| CSS variable | Role |
-| -------------------------------- | ------------------------------- |
-| `--theme-font-size-base` | Base font size |
-| `--theme-font-family-serif` | Base serif font family |
-| `--theme-font-family-sans-serif` | Base sans-serif font family |
-| `--theme-font-family-monospace` | Base monospace font family |
-| `--theme-font-family-hed` | Headline (`h1`) font family |
-| `--theme-font-family-subhed` | Subhead (`h2`-`h6`) font family |
-| `--theme-font-family-body` | Body text font family |
-| `--theme-font-family-note` | Note font family |
diff --git a/src/docs/styles/tokens/accessibility/main.stories.mdx b/src/docs/styles/tokens/accessibility/main.stories.mdx
new file mode 100644
index 00000000..2011d281
--- /dev/null
+++ b/src/docs/styles/tokens/accessibility/main.stories.mdx
@@ -0,0 +1,20 @@
+import { Meta } from '@storybook/addon-docs';
+import { parameters } from '$docs/utils/docsPage.js';
+import CopyTable from '../../../docs-components/CopyTable/Table.jsx';
+import { cssStringToTableArray } from '../../../utils/parseCss';
+
+{/* @ts-ignore */}
+import visibilityStyles from '$lib/scss/tokens/accessibility/\_visibility.scss?inline';
+
+
+
+
+
+# Accessibility tokens
+
+ `@include ${t};`, false]}
+/>
diff --git a/src/docs/styles/tokens/backgrounds/main.stories.mdx b/src/docs/styles/tokens/backgrounds/main.stories.mdx
new file mode 100644
index 00000000..ab1c27dc
--- /dev/null
+++ b/src/docs/styles/tokens/backgrounds/main.stories.mdx
@@ -0,0 +1,21 @@
+import { Meta } from '@storybook/addon-docs';
+import { parameters } from '$docs/utils/docsPage.js';
+import CopyTable from '../../../docs-components/CopyTable/Table.jsx';
+import { cssStringToTableArray } from '../../../utils/parseCss';
+
+{/* @ts-ignore */}
+import backgroundColor from '$lib/scss/tokens/backgrounds/\_background-color.scss?inline';
+
+
+
+
+
+# Background tokens
+
+ `@include ${t};`, false]}
+/>
diff --git a/src/docs/styles/borders/main.stories.mdx b/src/docs/styles/tokens/borders/main.stories.mdx
similarity index 65%
rename from src/docs/styles/borders/main.stories.mdx
rename to src/docs/styles/tokens/borders/main.stories.mdx
index b3f91907..85195093 100644
--- a/src/docs/styles/borders/main.stories.mdx
+++ b/src/docs/styles/tokens/borders/main.stories.mdx
@@ -1,25 +1,25 @@
import { Meta } from '@storybook/addon-docs';
import { parameters } from '$docs/utils/docsPage.js';
-import CopyTable from '../../docs-components/CopyTable/Table.jsx';
-import { cssStringToTableArray } from '../../utils/parseCss';
+import CopyTable from '../../../docs-components/CopyTable/Table.jsx';
+import { cssStringToTableArray } from '../../../utils/parseCss';
{/* @ts-ignore */}
-import borderColor from '$lib/scss/borders/\_border-color.scss?raw';
+import borderColor from '$lib/scss/tokens/borders/\_border-color.scss?raw';
{/* @ts-ignore */}
-import borderRadius from '$lib/scss/borders/\_border-radius.scss?raw';
+import borderRadius from '$lib/scss/tokens/borders/\_border-radius.scss?raw';
{/* @ts-ignore */}
-import borderStyle from '$lib/scss/borders/\_border-style.scss?raw';
+import borderStyle from '$lib/scss/tokens/borders/\_border-style.scss?raw';
{/* @ts-ignore */}
-import borderWidth from '$lib/scss/borders/\_border-width.scss?raw';
+import borderWidth from '$lib/scss/tokens/borders/\_border-width.scss?raw';
-
+

-# Border classes
+# Border tokens
+
+
+
+# Style tokens
+
+TK...
diff --git a/src/docs/styles/layout/flexbox.stories.mdx b/src/docs/styles/tokens/layout/flexbox.stories.mdx
similarity index 70%
rename from src/docs/styles/layout/flexbox.stories.mdx
rename to src/docs/styles/tokens/layout/flexbox.stories.mdx
index 17890dd9..a88522ee 100644
--- a/src/docs/styles/layout/flexbox.stories.mdx
+++ b/src/docs/styles/tokens/layout/flexbox.stories.mdx
@@ -1,46 +1,46 @@
import { Meta } from '@storybook/addon-docs';
import { parameters } from '$docs/utils/docsPage.js';
-import CopyTable from '../../docs-components/CopyTable/Table.jsx';
-import { cssStringToTableArray } from '../../utils/parseCss';
+import CopyTable from '../../../docs-components/CopyTable/Table.jsx';
+import { cssStringToTableArray } from '../../../utils/parseCss';
{/* @ts-ignore */}
-import alignContent from '$lib/scss/layout/flex/\_align-content.scss?raw';
+import alignContent from '$lib/scss/tokens/layout/flex/\_align-content.scss?raw';
{/* @ts-ignore */}
-import alignItems from '$lib/scss/layout/flex/\_align-items.scss?raw';
+import alignItems from '$lib/scss/tokens/layout/flex/\_align-items.scss?raw';
{/* @ts-ignore */}
-import alignSelf from '$lib/scss/layout/flex/\_align-self.scss?raw';
+import alignSelf from '$lib/scss/tokens/layout/flex/\_align-self.scss?raw';
{/* @ts-ignore */}
-import flexDirection from '$lib/scss/layout/flex/\_flex-direction.scss?raw';
+import flexDirection from '$lib/scss/tokens/layout/flex/\_flex-direction.scss?raw';
{/* @ts-ignore */}
-import flexGrow from '$lib/scss/layout/flex/\_flex-grow.scss?raw';
+import flexGrow from '$lib/scss/tokens/layout/flex/\_flex-grow.scss?raw';
{/* @ts-ignore */}
-import flexShrink from '$lib/scss/layout/flex/\_flex-shrink.scss?raw';
+import flexShrink from '$lib/scss/tokens/layout/flex/\_flex-shrink.scss?raw';
{/* @ts-ignore */}
-import flexWrap from '$lib/scss/layout/flex/\_flex-wrap.scss?raw';
+import flexWrap from '$lib/scss/tokens/layout/flex/\_flex-wrap.scss?raw';
{/* @ts-ignore */}
-import flex from '$lib/scss/layout/flex/\_flex.scss?raw';
+import flex from '$lib/scss/tokens/layout/flex/\_flex.scss?raw';
{/* @ts-ignore */}
-import justifyContent from '$lib/scss/layout/flex/\_justify-content.scss?raw';
+import justifyContent from '$lib/scss/tokens/layout/flex/\_justify-content.scss?raw';
{/* @ts-ignore */}
-import justifyItems from '$lib/scss/layout/flex/\_justify-items.scss?raw';
+import justifyItems from '$lib/scss/tokens/layout/flex/\_justify-items.scss?raw';
{/* @ts-ignore */}
-import justifySelf from '$lib/scss/layout/flex/\_justify-self.scss?raw';
+import justifySelf from '$lib/scss/tokens/layout/flex/\_justify-self.scss?raw';
-
+

-# Flexbox
+# Flexbox tokens
Flexbox is a modern way to lay out elements on your page while controling their alignment, distribution, space between and more. If flexbox is new, checkout the excellent [CSS tricks guide](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).
diff --git a/src/docs/styles/layout/main.stories.mdx b/src/docs/styles/tokens/layout/main.stories.mdx
similarity index 63%
rename from src/docs/styles/layout/main.stories.mdx
rename to src/docs/styles/tokens/layout/main.stories.mdx
index 0fe6b4a4..c1fee5e9 100644
--- a/src/docs/styles/layout/main.stories.mdx
+++ b/src/docs/styles/tokens/layout/main.stories.mdx
@@ -1,22 +1,22 @@
import { Meta } from '@storybook/addon-docs';
import { parameters } from '$docs/utils/docsPage.js';
-import CopyTable from '../../docs-components/CopyTable/Table.jsx';
-import { cssStringToTableArray } from '../../utils/parseCss';
+import CopyTable from '../../../docs-components/CopyTable/Table.jsx';
+import { cssStringToTableArray } from '../../../utils/parseCss';
{/* @ts-ignore */}
-import boxSizine from '$lib/scss/layout/\_box-sizing.scss?raw';
+import boxSizine from '$lib/scss/tokens/layout/\_box-sizing.scss?raw';
{/* @ts-ignore */}
-import display from '$lib/scss/layout/\_display.scss?raw';
+import display from '$lib/scss/tokens/layout/\_display.scss?raw';
{/* @ts-ignore */}
-import floats from '$lib/scss/layout/\_floats.scss?raw';
+import floats from '$lib/scss/tokens/layout/\_floats.scss?raw';
-
+

-# Layout classes
+# Layout tokens
+

-# Spacer classes
+# Spacer tokens
+

-# Typography classes
+# Typography tokens
+
+ `@include ${t};`, false]}
+/>
`@include ${t};`, false]}
+/>
+
+ `@include ${t};`, false]}
/>
`@include ${t};`, false]}
/>
`@include ${t};`, false]}
+/>
+
+ `@include ${t};`, false]}
/>
-
-
-
-# Adding custom fonts
-
-For some projects, you may need to use typefaces other than the defaults provided by the GraphicsKit.
-
-You will need to:
-
-- Import the fonts in your code.
-- Declare the `font-family` in the corresponding CSS variables in the Theme.
-
-## Importing custom fonts
-
-There are many ways to load fonts, but care should be taken that the font files load first before page render, to avoid layout shifts during font swapping after the font is downloaded. For this reason, we will use `` method in the page `head` instead of CSS imports.
-
-In this sample from [Google Fonts](https://fonts.google.com/), once we have selected the font families, copy the `` code.
-
-
-
-In your project, navigate to `Pages` > `layout.svelte` and add the code in `svelte:head` fragment as follows:
-
-If you don't have the layout file, add it.
-
-```svelte
-
-
-
-
-
-
-
-```
-
-Similarly, you can add fonts from Adobe Typekit or custom local fonts with the correct paths to the URL.
-
-## Adding fonts to the theme
-
-You can customise one or more of the the pre-defined font families in the Theme.
-
-> Do not directly apply the font family in your CSS. Always use the CSS variables defined in the Theme so that it configures and reflects across the page design.
-
-```svelte
-
-
-
-```
-
-Read more about customising typefaces in the [How to use](/docs/typography-how-to-use--typefaces) section.
diff --git a/src/docs/styles/typography/imgs/demo.png b/src/docs/styles/typography/imgs/demo.png
deleted file mode 100644
index 4c33e4a8..00000000
Binary files a/src/docs/styles/typography/imgs/demo.png and /dev/null differ
diff --git a/src/docs/styles/typography/imgs/gfonts.png b/src/docs/styles/typography/imgs/gfonts.png
deleted file mode 100644
index 65849c82..00000000
Binary files a/src/docs/styles/typography/imgs/gfonts.png and /dev/null differ
diff --git a/src/docs/styles/typography/imgs/type-guides.png b/src/docs/styles/typography/imgs/type-guides.png
deleted file mode 100644
index 236cc7d7..00000000
Binary files a/src/docs/styles/typography/imgs/type-guides.png and /dev/null differ
diff --git a/src/docs/styles/typography/imgs/typeset.png b/src/docs/styles/typography/imgs/typeset.png
deleted file mode 100644
index e7cd98bc..00000000
Binary files a/src/docs/styles/typography/imgs/typeset.png and /dev/null differ
diff --git a/src/docs/styles/typography/intro.stories.mdx b/src/docs/styles/typography/intro.stories.mdx
deleted file mode 100644
index eef451fe..00000000
--- a/src/docs/styles/typography/intro.stories.mdx
+++ /dev/null
@@ -1,41 +0,0 @@
-import { Meta } from '@storybook/addon-docs';
-import { parameters } from '$docs/utils/docsPage.js';
-
-{/* @ts-ignore */}
-import Typeset from './imgs/typeset.png';
-
-{/* @ts-ignore */}
-import TypeGuides from './imgs/type-guides.png';
-
-{/* @ts-ignore */}
-import DemoImg from './imgs/demo.png';
-
-
-
-
-
-# Typography
-
-Our Reuters Graphics components include a basic typography system designed to make it easy to incorporate clean, balanced type styles in your project.
-
-The typography system includes all the levels of text heirarchy you'll need for graphics pages, including page title, subheads, section titles, body copy, graphic descriptions, captions and other notes.
-
-
-
-## The type style system
-
-The typographic scale is based on the scale of fifths to create six harmonic levels of font sizes. These create the sizing for headlines, body text and spacing.
-
-The typographic scale is set using the CSS variable in the `Theme` component. You can customise it there.
-
-
diff --git a/src/docs/styles/typography/using-the-system.stories.mdx b/src/docs/styles/typography/using-the-system.stories.mdx
deleted file mode 100644
index 874cbc74..00000000
--- a/src/docs/styles/typography/using-the-system.stories.mdx
+++ /dev/null
@@ -1,120 +0,0 @@
-import { Meta } from '@storybook/addon-docs';
-import { parameters } from '$docs/utils/docsPage.js';
-import Theme from '../../docs-components/MdxTheme/Theme.jsx';
-
-import './styles.scss';
-
-
-
-
-
-# Using the type system
-
-## Type style heirarchy
-
-The type styles consist of 3 elements: size, typeface and colour. TKTKTK
-
-## Using type styles
-
-Type styles are automatically applied to native HTML elements like `h` and `p` tags and to certain combinations of elements that represent specific text components.
-
-```html
-
-
Here's a section title
-
and some text to go with it...
-
-
-
-
Editors: Simon Scarr
-
-```
-
-Apply text styles to any element using CSS classes that correspond to each text element type.
-
-```html
-
Subhed
-
Sans-serif text...
-```
-
-
-
-
Subhed
-
Sans-serif text...
-
-
-
-The following text style elements and corresponding classes are available:
-
-| 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` |
-
-
-
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
-
-
-### Type sizes
-
-The following classes apply specific text sizes to any element:
-
-| 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` |
-
-
-
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
Lorem ipsum dolor sit amet...
-
-
-
-> 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`
-
-### Typefaces
-
-The following classes apply typefaces to any element:
-
-| 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` |
-
-
-