@guardian/stand 0.0.12 → 0.0.14

package/README.md

@@ -1,1804 +1,158 @@
-# Stand - a tools component library
+# `@guardian/stand`
 
 _Find what you need on the (news)stand!_
 
-Stand is component library and design system for internal Guardian tools. Any tool should be able to make use of the components as an npm package - `@guardian/stand` - and developers should feel comfortable contributing.
+A tools component library and design system
 
-## Installation
+Any tool should be able to make use of the components as an npm package, [`@guardian/stand`](https://www.npmjs.com/package/@guardian/stand), and developers should feel comfortable [contributing](https://guardian.github.io/stand/?path=/docs/contributing--docs).
 
-```bash
-$ pnpm add @guardian/stand # or yarn or npm
-```
-
-You'll also need to have TypeScript, React, and Emotion installed in your project.
-
-The compatible versions are listed in the `peerDependencies` section of `package.json`.
-
-Some components have additional dependencies that you will need to install too. See the [Components](#components) section for more details for which components have which peer dependencies.
-
-## Foundations
-
-The Editorial Design System foundations are available via Stand. These are split into two categories: Semantic and Base / Primitives.
-
-In most cases consumers should use the Semantic tokens, which are more meaningful abstractions of the Base / Primitives tokens, i.e applied to specific use cases.
-
-The base / primitives tokens are available for low-level use cases, or very specific cases, but these should be avoided where possible in favour of the semantic tokens.
-
-Stand provides the foundations via CSS variables, as well as JS/TS exports for use in code, which could also be used in CSS-in-JS solutions.
-
-Base / Primitive tokens should not be overridden if they are used directly, as this could have unintended consequences. Instead override the Semantic tokens which are designed to be overridden.
-
-### Fonts
-
-Most applications should only need to load the `Open Sans` and `Guardian Headline` fonts, as these are the primary fonts used across the Guardian's Editorial Tool design system.
-
-You only need to load Guardian Text Egyptian if you're planning to use it in your project, in most cases you only need this when working on Guardian editorial content on an editorial tool, i.e. when using `article-body-*` semantic tokens.
-
-##### Open Sans
-
-##### Guardian Hosted (Recommended)
-
-We are self hosting this font under a Guardian specific domain, so you can load the Open Sans variable font CSS file from our CDN:
-
-Via CSS `@import`:
-
-```css
-@import url('https://assets.guim.co.uk/fonts/open-sans/OpenSans.css');
-```
-
-Via HTML `<link>`:
-
-```html
-<link
-	rel="stylesheet"
-	href="https://assets.guim.co.uk/fonts/open-sans/OpenSans.css"
-/>
-```
-
-We also publish the same `OpenSans.css` file in the `@guardian/stand` package if you prefer to import it from there and you're using a bundler that supports CSS imports:
-
-```ts
-import '@guardian/stand/fonts/OpenSans.css';
-```
-
-All options use the font files hosted on the Guardian CDN at `https://assets.guim.co.uk/fonts/open-sans/woff2/`.
-
-You can also create your own CSS `@font-face` declarations, using the same format as in the `OpenSans.css` file, and/or self host the font files yourself if needed.
-
-##### via Google Fonts
-
-The Open Sans variable font can also be loaded via Google Fonts, but we recommend using the Guardian hosted version to avoid loading from a third party domain:
-
-1. Visit [Google Fonts - Open Sans](https://fonts.google.com/specimen/Open+Sans)
-2. Click "Get Font" -> "Get embed code"
-3. Click "Change styles" dropdown
-4. Use "Full axis" for all options (Italic, Weight, Width)
-5. Copy the relevant `<link>` tag or `@import` code snippet into your project
-   - You don't need to include the CSS class, as the design system will handle applying the correct font-family via CSS variables or JS/TS tokens.
-
-#### Guardian Fonts
-
-Make sure to visit [guardian/fonts](https://github.com/guardian/fonts) repo for the latest information on how to self-host these fonts.
-
-In general, we always want to use the `full-not-hinted` versions of the fonts where possible.
-
-##### Guardian Headline
-
-We only use the bold weight (700) of Guardian Headline in the design system.
-
-```css
-@font-face {
-	font-family: 'GH Guardian Headline';
-	src: url('https://assets.guim.co.uk/static/frontend/fonts/guardian-headline/full-not-hinted/GHGuardianHeadline-Bold.woff2')
-		format('woff2');
-	font-weight: 700;
-	font-style: normal;
-	font-display: swap;
-}
-```
-
-##### Guardian Text Egyptian
-
-We want the regular/normal weight (400), the bold weight (700), and the italic version of each weight for Guardian Text Egyptian in the design system.
-
-```css
-@font-face {
-	font-family: 'GuardianTextEgyptian';
-	src: url('https://assets.guim.co.uk/static/frontend/fonts/guardian-textegyptian/full-not-hinted/GuardianTextEgyptian-Regular.woff2')
-		format('woff2');
-	font-weight: 400;
-	font-style: normal;
-	font-display: swap;
-}
-@font-face {
-	font-family: 'GuardianTextEgyptian';
-	src: url('https://assets.guim.co.uk/static/frontend/fonts/guardian-textegyptian/full-not-hinted/GuardianTextEgyptian-RegularItalic.woff2')
-		format('woff2');
-	font-weight: 400;
-	font-style: italic;
-	font-display: swap;
-}
-@font-face {
-	font-family: 'GuardianTextEgyptian';
-	src: url('https://assets.guim.co.uk/static/frontend/fonts/guardian-textegyptian/full-not-hinted/GuardianTextEgyptian-Bold.woff2')
-		format('woff2');
-	font-weight: 700;
-	font-style: normal;
-	font-display: swap;
-}
-@font-face {
-	font-family: 'GuardianTextEgyptian';
-	src: url('https://assets.guim.co.uk/static/frontend/fonts/guardian-textegyptian/full-not-hinted/GuardianTextEgyptian-BoldItalic.woff2')
-		format('woff2');
-	font-weight: 700;
-	font-style: italic;
-	font-display: swap;
-}
-```
-
-### Semantic
-
-#### Colors
-
-_Status: WIP_
-
-```ts
-import { css } from '@emotion/react';
-import { semanticColors } from '@guardian/stand'; // JS/TS usage
-import '@guardian/stand/semantic/colors.css'; // CSS usage
-
-const stringStyle = css`
-	color: ${semanticColors.text.default}; /* JS/TS usage */
-	background-color: var(--semantic-colors-bg-default-on-light); /* CSS usage */
-`;
-
-const objectStyle = {
-	color: semanticColors.text.default /* JS/TS usage */,
-	backgroundColor: 'var(--semantic-colors-bg-default-on-light)' /* CSS usage */,
-};
-```
-
-For a list of available semantic color styles see the [Storybook Semantic Colors](https://68c12e3ed577cb56abfd31bf-kggeezequd.chromatic.com/?path=/docs/stand-editorial-design-system-semantic-color-palette--docs) section.
-
-For a full list of CSS Semantic Color tokens see [`semantic/colors.css`](./src/styleD/build/css/semantic/colors.css).
+This library is split into two main sections:
 
-#### Typography
+- [Tools Design System](https://guardian.github.io/stand/?path=/docs/stand-tools-design-system-introduction--docs)
+  - The core design system and components used across the Guardian's internal tools.
+  - e.g. Colour, Typography, Buttons, Forms, etc.
+- [Editorial Components](https://guardian.github.io/stand/?path=/docs/stand-editorial-components-introduction--docs)
+  - A collection of highly specific components shared across a smaller number of tools.
+  - e.g. Byline editor, Tag picker, etc.
 
-_Status: WIP_
+Currently maintained by the P&E DevX E2E team, but open to contributions from anyone in the company. Do reach out for help or to get involved!
 
-```ts
-import { css } from '@emotion/react';
-import { semanticColors, semanticTypography } from '@guardian/stand'; // JS/TS usage
-import {
-	convertTypographyToEmotionObjectStyle, // helper function to convert from typography token object to emotion CSS object style
-	convertTypographyToEmotionStringStyle, // helper function to convert from typography token object to emotion CSS string style
-} from '@guardian/stand/utils'; // Utils for working with design tokens
-import '@guardian/stand/semantic/typography.css'; // CSS usage
-
-/* JS/TS usage */
-const stringStyleJS = css`
-	// other styles e.g.
-	color: ${semanticColors.text.default};
-
-	/* (recommended) emotion string style usage helper function*/
-	${convertTypographyToEmotionStringStyle(
-		semanticTypography['body-compact-md'],
-	)}
-
-	/* or direct usage without helper function */
-    font: ${semanticTypography['body-compact-md'].font};
-	letter-spacing: ${semanticTypography['body-compact-md'].letterSpacing};
-	font-variation-settings: 'wdth'
-		${semanticTypography['body-compact-md'].fontWidth};
-`;
-const objectStyleJS = {
-	// other styles e.g.
-	color: semanticColors.text.default,
-
-	// (recommended) emotion object style usage helper function
-	...convertTypographyToEmotionObjectStyle(
-		semanticTypography['body-compact-sm'],
-	),
-
-	// or direct usage without helper function
-	font: semanticTypography['body-compact-sm'].font,
-	letterSpacing: semanticTypography['body-compact-sm'].letterSpacing,
-	fontVariationSettings: `'wdth' ${semanticTypography['body-compact-sm'].fontWidth}`,
-};
-
-/* CSS usage */
-const stringStyleCSS = css`
-	/* CSS usage */
-	font: var(--semantic-typography-body-compact-sm-font);
-	letter-spacing: var(--semantic-typography-body-compact-sm-letter-spacing);
-	font-variation-settings: 'wdth'
-		var(--semantic-typography-body-compact-sm-font-width);
-`;
-const objectStyleCSS = {
-	font: 'var(--semantic-typography-body-compact-sm-font)',
-	letterSpacing: 'var(--semantic-typography-body-compact-sm-letter-spacing)',
-	fontVariationSettings: `'wdth' var(--semantic-typography-body-compact-sm-font-width)`,
-};
-```
-
-For a list of available typography styles see the [Storybook Semantic Typography](https://68c12e3ed577cb56abfd31bf-kggeezequd.chromatic.com/?path=/docs/stand-editorial-design-system-semantic-typography--docs) section.
-
-For a full list of CSS Semantic Typography tokens see [`semantic/typography.css`](./src/styleD/build/css/semantic/typography.css).
-
-#### Sizing
-
-_Status: WIP_
-
-```ts
-import { css } from '@emotion/react';
-import { semanticSizing } from '@guardian/stand'; // JS/TS usage
-import '@guardian/stand/semantic/sizing.css'; // CSS usage
-
-const stringStyle = css`
-	height: ${semanticSizing.height.md}; /* JS/TS usage */
-	border-width: var(--semantic-sizing-border-md); /* CSS usage */
-`;
-
-const objectStyle = {
-	height: semanticSizing.height.md /* JS/TS usage */,
-	borderWidth: 'var(--semantic-sizing-border-md)' /* CSS usage */,
-};
-
-// Icon sizing example
-const iconStyle = css`
-	width: ${semanticSizing.icon.lg};
-	height: ${semanticSizing.icon.lg};
-`;
-```
-
-For a list of available semantic sizing styles see the [Storybook Semantic Sizing](https://68c12e3ed577cb56abfd31bf-kggeezequd.chromatic.com/?path=/docs/stand-editorial-design-system-semantic-sizing--docs) section.
-
-For a full list of CSS Semantic Sizing tokens see [`semantic/sizing.css`](./src/styleD/build/css/semantic/sizing.css).
-
-### Base / Primitives
-
-#### Colors
-
-_Status: WIP_
-
-```ts
-import { css } from '@emotion/react';
-import { baseColors } from '@guardian/stand'; // JS/TS usage
-import '@guardian/stand/base/colors.css'; // CSS usage
-
-const stringStyle = css`
-	color: ${baseColors.neutral['900']}; /* JS/TS usage */
-	background-color: var(--base-colors-blue-500); /* CSS usage */
-`;
-
-const objectStyle = {
-	color: baseColors.neutral['900'] /* JS/TS usage */,
-	backgroundColor: 'var(--base-colors-blue-500)' /* CSS usage */,
-};
-```
-
-For a list of the available base/primitives color styles see the [Storybook Base Colors](https://68c12e3ed577cb56abfd31bf-kggeezequd.chromatic.com/?path=/docs/stand-editorial-design-system-base-color-palette--docs) section.
-
-For a full list of CSS Base/Primitives Color tokens see [`base/colors.css`](./src/styleD/build/css/base/colors.css).
-
-#### Typography
-
-_Status: WIP_
-
-```ts
-import { css } from '@emotion/react';
-import { baseTypography } from '@guardian/stand'; // JS/TS usage
-import '@guardian/stand/base/typography.css'; // CSS usage
-
-/* JS/TS usage */
-const stringStyleJS = css`
-	font-family: ${baseTypography.family['Open Sans']};
-	font-size: ${baseTypography.size['14-rem']};
-	font-weight: ${baseTypography.weight['Open Sans'].normal};
-	font-variation-settings: 'wdth' ${baseTypography.width['Open Sans']};
-	style: ${baseTypography.style.normal};
-	line-height: ${baseTypography.lineHeight.normal};
-	letter-spacing: ${baseTypography.letterSpacing['default-rem']};
-`;
-const objectStyleJS = {
-	fontFamily: baseTypography.family['Open Sans'],
-	fontSize: baseTypography.size['14-rem'],
-	fontWeight: baseTypography.weight['Open Sans'].normal,
-	fontVariationSettings: `'wdth' ${baseTypography.width['Open Sans']}`,
-	fontStyle: baseTypography.style.normal,
-	lineHeight: baseTypography.lineHeight.normal,
-	letterSpacing: baseTypography.letterSpacing['default-rem'],
-};
-
-/* CSS usage */
-const stringStyleCSS = css`
-	font-family: var(--base-typography-family-open-sans);
-	font-size: var(--base-typography-size-14-rem);
-	font-weight: var(--base-typography-weight-open-sans-normal);
-	font-variation-settings: 'wdth' var(--base-typography-width-open-sans);
-	font-style: var(--base-typography-style-normal);
-	line-height: var(--base-typography-line-height-normal);
-	letter-spacing: var(--base-typography-letter-spacing-default-rem);
-`;
-const objectStyleCSS = {
-	fontFamily: 'var(--base-typography-family-open-sans)',
-	fontSize: 'var(--base-typography-size-14-rem)',
-	fontWeight: 'var(--base-typography-weight-open-sans-normal)',
-	fontVariationSettings: `'wdth' var(--base-typography-width-open-sans)`,
-	fontStyle: 'var(--base-typography-style-normal)',
-	lineHeight: 'var(--base-typography-line-height-normal)',
-	letterSpacing: 'var(--base-typography-letter-spacing-default-rem)',
-};
-```
-
-For a list of the available base/primitives typography tokens see the [Storybook Base Typography](https://68c12e3ed577cb56abfd31bf-kggeezequd.chromatic.com/?path=/docs/stand-editorial-design-system-base-typography--docs) section.
-
-For a full list of CSS Base/Primitives Typography tokens see [`base/typography.css`](./src/styleD/build/css/base/typography.css).
-
-#### Spacing
-
-_Status: WIP_
-
-The `rem` tokens should be used in most cases to ensure scalability across different root font sizes.
-`px` tokens are available for cases where a fixed pixel value is required.
-
-```ts
-import { css } from '@emotion/react';
-import { baseSpacing } from '@guardian/stand'; // JS/TS usage
-import '@guardian/stand/base/spacing.css'; // CSS usage
-
-/* JS/TS usage */
-const stringStyleJS = css`
-	padding: ${baseSpacing['16-rem']};
-	margin-bottom: ${baseSpacing['24-rem']};
-	gap: ${baseSpacing['8-rem']};
-`;
-const objectStyleJS = {
-	padding: baseSpacing['16-rem'],
-	marginBottom: baseSpacing['24-rem'],
-	gap: baseSpacing['8-rem'],
-};
-
-/* CSS usage */
-const stringStyleCSS = css`
-	padding: var(--base-spacing-16-rem);
-	margin-bottom: var(--base-spacing-24-rem);
-	gap: var(--base-spacing-8-rem);
-`;
-const objectStyleCSS = {
-	padding: 'var(--base-spacing-16-rem)',
-	marginBottom: 'var(--base-spacing-24-rem)',
-	gap: 'var(--base-spacing-8-rem)',
-};
-```
-
-For a list of the available base/primitives spacing tokens see the [Storybook Base Spacing](https://68c12e3ed577cb56abfd31bf-kggeezequd.chromatic.com/?path=/docs/stand-editorial-design-system-base-spacing--docs) section.
-
-For a full list of CSS Base/Primitives Spacing tokens see [`base/spacing.css`](./src/styleD/build/css/base/spacing.css).
-
-#### Sizing
-
-_Status: WIP_
-
-The `rem` tokens should be used in most cases to ensure scalability across different root font sizes.
-`px` tokens are available for cases where a fixed pixel value is required.
-
-```ts
-import { css } from '@emotion/react';
-import { baseSizing } from '@guardian/stand'; // JS/TS usage
-import '@guardian/stand/base/sizing.css'; // CSS usage
-
-/* JS/TS usage */
-const stringStyleJS = css`
-	width: ${baseSizing['size-48-rem']};
-	height: ${baseSizing['size-24-rem']};
-	min-width: ${baseSizing['size-24-rem']};
-`;
-const objectStyleJS = {
-	width: baseSizing['size-48-rem'],
-	height: baseSizing['size-24-rem'],
-	minWidth: baseSizing['size-24-rem'],
-};
-
-/* CSS usage */
-const stringStyleCSS = css`
-	width: var(--base-sizing-size-48-rem);
-	height: var(--base-sizing-size-24-rem);
-	min-width: var(--base-sizing-size-24-rem);
-`;
-const objectStyleCSS = {
-	width: 'var(--base-sizing-size-48-rem)',
-	height: 'var(--base-sizing-size-24-rem)',
-	minWidth: 'var(--base-sizing-size-24-rem)',
-};
-```
+Stand is built with [React](https://reactjs.org/), [Emotion](https://emotion.sh/docs/introduction), and [TypeScript](https://www.typescriptlang.org/), but the design system is designed to be as framework-agnostic as possible in that styles can be used without these dependencies if needed.
 
-For a list of the available base/primitives sizing tokens see the [Storybook Base Sizing](https://68c12e3ed577cb56abfd31bf-kggeezequd.chromatic.com/?path=/docs/stand-editorial-design-system-base-sizing--docs) section.
+## Contents
 
-For a full list of CSS Base/Primitives Sizing tokens see [`base/sizing.css`](./src/styleD/build/css/base/sizing.css).
+- [Documentation](#documentation)
+- [Install](#install)
+- [Usage](#usage)
+- [Contributing](#contributing)
+- [Tasks](#tasks)
+- [Design Tokens and Style Dictionary](#design-tokens-and-style-dictionary)
+- [Compatibility](#compatibility)
+- [Documentation Site Map](#documentation-site-map)
 
-#### Radius
-
-_Status: WIP_
-
-The `rem` tokens should be used in most cases to ensure scalability across different root font sizes.
-`px` tokens are available for cases where a fixed pixel value is required.
-
-```ts
-import { css } from '@emotion/react';
-import { baseRadius } from '@guardian/stand'; // JS/TS usage
-import '@guardian/stand/base/radius.css'; // CSS usage
-
-/* JS/TS usage */
-const stringStyleJS = css`
-	border-radius: ${baseRadius['corner-4-rem']};
-`;
-const objectStyleJS = {
-	borderRadius: baseRadius['corner-4-rem'],
-};
-
-/* CSS usage */
-const stringStyleCSS = css`
-	border-radius: var(--base-radius-corner-4-rem);
-`;
-const objectStyleCSS = {
-	borderRadius: 'var(--base-radius-corner-4-rem)',
-};
-```
-
-For a list of the available base/primitives radius tokens see the [Storybook Base Radius](https://68c12e3ed577cb56abfd31bf-kggeezequd.chromatic.com/?path=/docs/stand-editorial-design-system-base-radius--docs) section.
-
-For a full list of CSS Base/Primitives Radius tokens see [`base/radius.css`](./src/styleD/build/css/base/radius.css).
-
-## Components - Base
-
-General purpose components for use across a variety of editorial tools based on the design system.
-
-### `Avatar`
-
-The Avatar component displays a user's profile image or initials in a circular container. It supports multiple sizes, colors, and automatic fallback handling.
-
-**When to use**
-
-- Display user profiles in lists, comments, or headers
-- Show user identity in messaging interfaces
-- Represent users in collaborative features
-
-**Peer dependencies:**
-
-- `@emotion/react`
-- `react`
-- `react-dom`
-- `typescript`
-
-See the `peerDependencies` section of `package.json` for compatible versions.
-
-See [avatar custom component build](#avatar-custom-component-build) for usage without React/Emotion.
-
-#### Example usage
-
-See "Emotion/React" heading on [codesandbox.io](https://codesandbox.io/p/sandbox/guardian-stand-avatar-component-mqvzh5)
-
-```tsx
-import { Avatar } from '@guardian/stand/avatar';
-
-/* types, if required */
-import type { AvatarProps, AvatarTheme } from '@guardian/stand/avatar';
-
-/* Initials only */
-<Avatar initials="AB" size="md" />
-
-/* Image with alt text */
-<Avatar
-	src="https://example.com/avatar.jpg"
-	alt="User Name"
-	size="md"
-/>
-
-/* Image with fallback initials and a specific color */
-<Avatar
-	src="https://example.com/avatar.jpg"
-	alt="User Name"
-	initials="AB"
-	color="blue"
-	size="md"
-/>
-```
-
-#### Props
-
-| Name           | Type               | Required    | Default                         | Description                                    |
-| -------------- | ------------------ | ----------- | ------------------------------- | ---------------------------------------------- |
-| `size`         | `'sm'` \| `'md'`   | No          | `'md'`                          | Size of the avatar.                            |
-| `color`        | Various            | No          | Deterministic based on initials | Color of the avatar.                           |
-| `initials`     | `string`           | Conditional | N/A                             | Initials to display when no image is provided. |
-| `src`          | `string`           | Conditional | N/A                             | URL of the avatar image.                       |
-| `alt`          | `string`           | Conditional | N/A                             | Alt text for the image for accessibility.      |
-| `theme`        | `AvatarTheme`      | No          | N/A                             | Custom theme overrides for the avatar.         |
-| `cssOverrides` | `SerializedStyles` | No          | N/A                             | Custom CSS styles for the avatar.              |
-| `className`    | `string`           | No          | N/A                             | Additional class name(s) for the avatar.       |
-
-When using `src`, the `alt` prop is required for accessibility.
-When not using `src`, the `initials` prop is required.
-
-**`size`**
-
-The avatar supports two sizes:
-
-- `sm` (small): 32px
-- `md` (medium): 40px
-
-**`color`**
-
-When no `color` is set, the avatar picks a deterministic color based on the initials (with the exception of `outlined`). You can also specify a color explicitly.
-
-Available colors: `outlined`, `blue`, `green`, `red`, `cyan`, `teal`, `cool-purple`, `warm-purple`, `magenta`, `orange`, `yellow`
-
-#### Customisation
-
-We recommend using the Avatar component as provided, but it can be customised using the `theme` or `cssOverrides` props as required.
-
-**Custom theme**
-
-The `theme` prop allows you to override specific design tokens for the Avatar component:
-
-```tsx
-import type { AvatarTheme } from '@guardian/stand/avatar';
-import { Avatar } from '@guardian/stand/avatar';
-import { baseColors, baseSizing } from '@guardian/stand';
-
-const customTheme: AvatarTheme = {
-	shared: {
-		color: {
-			blue: {
-				background: baseColors.blue[100],
-				text: baseColors.neutral[900],
-			},
-		},
-	},
-	md: {
-		size: baseSizing['size-48-rem'],
-	},
-};
-
-const Component = () => (
-	<Avatar color="blue" initials="CT" size="md" theme={customTheme} />
-);
-```
-
-**CSS overrides**
-
-The `cssOverrides` prop allows you to pass custom CSS to the Avatar component, if the theme prop is not sufficient:
-
-```tsx
-import { Avatar } from '@guardian/stand/avatar';
-import { baseColors, baseSizing, baseSpacing } from '@guardian/stand';
-import { css } from '@emotion/react';
-
-const customStyles = css`
-	border: ${baseSizing['size-2-rem']} solid ${baseColors.red[500]};
-	margin: ${baseSpacing['8-rem']};
-`;
-
-const Component = () => (
-	<Avatar initials="CO" size="md" color="red" cssOverrides={customStyles} />
-);
-```
-
-#### Avatar Custom Component Build
-
-If you're not using React/Emotion, or `@guardian/stand` is not compatible with your project, you can create a custom Avatar component using the styles defined in the `AvatarTheme` type.
-
-You will however be responsible for any additional functionality on top of the styles, for example image loading, image fallback, accessibility etc.
-
-See "Custom Component" heading on [codesandbox.io](https://codesandbox.io/p/sandbox/guardian-stand-avatar-component-mqvzh5)
-
-**`css`**
-
-You can import the Avatar styles as CSS from the package, make sure that your build process supports importing CSS from `node_modules`/`package.json`:
-
-```css
-/* import the font and avatar styles */
-@import '@guardian/stand/fonts/OpenSans.css';
-@import '@guardian/stand/component/avatar.css';
-
-/*
-or for scenarios where you have to use relative paths/node_modules directly:
-
-@import 'node_modules/@guardian/stand/dist/fonts/OpenSans.css';
-@import 'node_modules/@guardian/stand/dist/styleD/build/css/component/avatar.css';
-*/
-
-/* example setup of avatar style using md size and blue color */
-.stand-avatar {
-	display: var(--component-avatar-shared-display);
-	align-items: var(--component-avatar-shared-align-items);
-	justify-content: var(--component-avatar-shared-justify-content);
-	overflow: var(--component-avatar-shared-overflow);
-	flex-shrink: var(--component-avatar-shared-flex-shrink);
-	border-radius: var(--component-avatar-shared-border-radius);
-	background-color: var(--component-avatar-shared-color-blue-background);
-	width: var(--component-avatar-md-size);
-	height: var(--component-avatar-md-size);
-	border: var(--component-avatar-shared-color-blue-border);
-	color: var(--component-avatar-shared-color-blue-text);
-	font: var(--component-avatar-md-typography-font);
-	letter-spacing: var(--component-avatar-md-typography-letter-spacing);
-	font-variation-settings: 'wdth'
-		var(--component-avatar-md-typography-font-width);
-}
-
-/* example setup for avatar image */
-.stand-avatar > img {
-	width: 100%;
-	height: 100%;
-	object-fit: cover;
-}
-```
-
-```html
-<!-- example usage of avatar style in html with avatar -->
-<div class="stand-avatar">AB</div>
-
-<!-- example usage of avatar style in html with avatar image -->
-<div class="stand-avatar">
-	<img src="https://example.com/avatar.jpg" alt="User Name" />
-</div>
-```
-
-**TypeScript/JavaScript**
-
-Use the `componentAvatar` variable and the `ComponentAvatar` type to define your custom styles in TypeScript/JavaScript:
-
-```ts
-import type { ComponentAvatar } from '@guardian/stand'; // if types required
-import { componentAvatar } from '@guardian/stand';
-
-const style = `
-  display: ${componentAvatar.shared.display};
-  align-items: ${componentAvatar.shared['align-items']};
-  justify-content: ${componentAvatar.shared['justify-content']};
-  overflow: ${componentAvatar.shared.overflow};
-  flex-shrink: ${componentAvatar.shared['flex-shrink']};
-  border-radius: ${componentAvatar.shared['border-radius']};
-  background-color: ${componentAvatar.shared.color.blue.background};
-  width: ${componentAvatar.md.size};
-  height: ${componentAvatar.md.size};
-  border: ${componentAvatar.shared.color.blue.border};
-  color: ${componentAvatar.shared.color.blue.text};
-  font: ${componentAvatar.md.typography.font};
-  letter-spacing: ${componentAvatar.md.typography.letterSpacing};
-  font-variation-settings: 'wdth' ${componentAvatar.md.typography.fontWidth};
-`;
-
-const imgStyle = `
-  width: 100%;
-  height: 100%;
-  object-fit: cover;
-`;
-
-// e.g. adding to DOM using vanilla JS styles
-document.getElementById('app')!.innerHTML = `
-    <h2>
-        Using <code>typescript</code>/<code>javascript</code>
-    </h2>
-    <div style="${style}">AB</div>
-    <div style="${style}">
-        <img
-            style="${imgStyle}"
-            src="https://example.com/avatar.jpg"
-            alt="User Name"
-        />
-    </div>
-`;
-```
-
-### `Button`
-
-A React Aria powered button that follows Stand design and accessibility defaults. It supports multiple visual variants, four sizes, disabled state handling, and render props for pending interactions.
-
-**When to use**
-
-- Primary and secondary actions that require clear affordance
-- Form submissions or confirm/cancel flows
-- Re-usable button styles that align with Stand tokens
-
-**Peer dependencies:**
-
-- `@emotion/react`
-- `react`
-- `react-dom`
-- `react-aria-components`
-- `typescript`
-
-See the `peerDependencies` section of `package.json` for compatible versions.
-
-See [button custom component build](#button-custom-component-build) for usage without React/Emotion.
-
-#### Example usage
-
-See "Emotion/React" heading on [codesandbox.io](https://codesandbox.io/p/sandbox/jctg2k)
-
-```tsx
-import { Button } from '@guardian/stand/button';
-import type { ButtonProps, ButtonTheme } from '@guardian/stand/button';
-
-const Example = () => (
-	<>
-		<Button
-			variant="emphasised-primary"
-			size="md"
-			onPress={() => {
-				console.log('Primary action');
-			}}
-		>
-			Publish
-		</Button>
-
-		<Button variant="neutral-secondary" size="sm" isDisabled>
-			Disabled
-		</Button>
-	</>
-);
-```
-
-#### Props
-
-| Name           | Type                                                                                               | Required | Default                | Description                                                                                       |
-| -------------- | -------------------------------------------------------------------------------------------------- | -------- | ---------------------- | ------------------------------------------------------------------------------------------------- |
-| `size`         | `'xs'` \| `'sm'` \| `'md'` \| `'lg'`                                                               | No       | `'md'`                 | Controls the button dimensions and typography.                                                    |
-| `variant`      | `'emphasised-primary'` \| `'emphasised-secondary'` \| `'neutral-primary'` \| `'neutral-secondary'` | No       | `'emphasised-primary'` | Chooses the colour scheme and interaction states.                                                 |
-| `children`     | `ReactNode` \| `RenderProps`                                                                       | Yes      | N/A                    | Content inside the button. Render props receive `{ isPending }` from React Aria.                  |
-| `isDisabled`   | `boolean`                                                                                          | No       | `false`                | Disables interaction and applies disabled styling.                                                |
-| `theme`        | `ButtonTheme` (partial)                                                                            | No       | N/A                    | Override Stand tokens for this instance; merged over the default theme.                           |
-| `cssOverrides` | `SerializedStyles` \| `SerializedStyles[]`                                                         | No       | N/A                    | Low-level escape hatch for Emotion overrides when theming is insufficient.                        |
-| `className`    | `string`                                                                                           | No       | N/A                    | Optional class name forwarded to the root React Aria button.                                      |
-| `...props`     | `ReactAria Button` props                                                                           | No       | N/A                    | All other props from `react-aria-components` `Button` (e.g. `type`, `autoFocus`, event handlers). |
-
-**`size` and `variant`**
-
-- Sizes: `xs`, `sm`, `md`, `lg`
-- Variants: `emphasised-primary`, `emphasised-secondary`, `neutral-primary`, `neutral-secondary`
-
-#### Customisation
-
-We recommend using the default theme. When needed, use the `theme` or `cssOverrides` props.
-
-**Custom theme**
-
-```tsx
-import type { ButtonTheme } from '@guardian/stand/button';
-import { Button } from '@guardian/stand/button';
-import { baseColors } from '@guardian/stand';
-
-const customTheme: Partial<ButtonTheme> = {
-	'emphasised-primary': {
-		shared: {
-			backgroundColor: baseColors['cool-purple'][200],
-			color: baseColors['cool-purple'][900],
-			border: `2px solid ${baseColors['cool-purple'][700]}`,
-			':hover': {
-				backgroundColor: baseColors['cool-purple'][300],
-				border: `2px solid ${baseColors['cool-purple'][700]}`,
-			},
-			':active': {
-				backgroundColor: baseColors['cool-purple'][400],
-				border: `2px solid ${baseColors['cool-purple'][700]}`,
-			},
-		},
-	},
-};
-
-const Component = () => (
-	<Button variant="emphasised-primary" size="md" theme={customTheme}>
-		Custom Themed Button
-	</Button>
-);
-```
-
-**CSS overrides**
-
-```tsx
-import { Button } from '@guardian/stand/button';
-import { baseSpacing } from '@guardian/stand';
-import { css } from '@emotion/react';
-
-const customStyles = css`
-	width: 100%;
-	text-transform: full-width;
-	font-variant: small-caps;
-	padding-inline: ${baseSpacing['24-rem']};
-`;
-
-const Component = () => (
-	<Button variant="neutral-primary" size="sm" cssOverrides={customStyles}>
-		CSSOverrides Button
-	</Button>
-);
-```
+## Documentation
 
-#### Button Custom Component Build
+All documentation is available on [Github Pages Storybook](https://guardian.github.io/stand/), which is updated with the latest changes to the library.
 
-If you're not using React/Emotion, or `@guardian/stand` is not compatible with your project, you can create a custom `Button`/`LinkButton` component using the styles defined in the `ButtonTheme` type.
+## Install
 
-You will however be responsible for any additional functionality on top of the styles, for example accessibility, focus management, interaction states etc.
+The library is published to npm:
 
-See "Custom Component" heading on [codesandbox.io](https://codesandbox.io/p/sandbox/jctg2k)
-
-**`css`**
-
-You can import the Button styles as CSS from the package, make sure that your build process supports importing CSS from `node_modules`/`package.json`:
-
-```css
-/* import the font and button variables */
-@import '@guardian/stand/fonts/OpenSans.css';
-@import '@guardian/stand/component/button.css';
-
-/*
-or for scenarios where you have to use relative paths/node_modules directly:
-
-@import 'node_modules/@guardian/stand/dist/fonts/OpenSans.css';
-@import 'node_modules/@guardian/stand/dist/styleD/build/css/component/button.css';
-*/
-
-/* shared button styles for all variants */
-.stand-button {
-	display: var(--component-button-shared-display);
-	-webkit-appearance: var(--component-button-shared-webkit-appearance);
-	text-align: var(--component-button-shared-text-align);
-	box-shadow: var(--component-button-shared-box-shadow);
-	text-decoration: var(--component-button-shared-text-decoration);
-	cursor: var(--component-button-shared-cursor);
-	justify-content: var(--component-button-shared-justify-content);
-	align-items: var(--component-button-shared-align-items);
-}
-.stand-button:focus-visible {
-	outline: var(--component-button-shared-focus-visible-outline);
-	outline-offset: var(--component-button-shared-focus-visible-outline-offset);
-}
-.stand-button:disabled {
-	cursor: var(--component-button-shared-disabled-cursor);
-}
-
-/* example setup of button/link button style using md size and emphasised primary variant */
-.stand-button-emphasised-primary {
-	color: var(--component-button-emphasised-primary-shared-color);
-	background: var(
-		--component-button-emphasised-primary-shared-background-color
-	);
-	height: var(--component-button-emphasised-primary-md-height);
-	padding: var(--component-button-emphasised-primary-md-padding-top)
-		var(--component-button-emphasised-primary-md-padding-right)
-		var(--component-button-emphasised-primary-md-padding-bottom)
-		var(--component-button-emphasised-primary-md-padding-left);
-	font: var(--component-button-emphasised-primary-md-typography-font);
-	letter-spacing: var(
-		--component-button-emphasised-primary-md-typography-letter-spacing
-	);
-	font-variation-settings: 'wdth'
-		var(--component-button-emphasised-primary-md-typography-font-width);
-	border: var(--component-button-emphasised-primary-shared-border);
-	border-radius: var(
-		--component-button-emphasised-primary-shared-border-radius
-	);
-}
-.stand-button-emphasised-primary:hover {
-	background: var(
-		--component-button-emphasised-primary-shared-hover-background-color
-	);
-	border: var(--component-button-emphasised-primary-shared-hover-border);
-}
-.stand-button-emphasised-primary:active {
-	background: var(
-		--component-button-emphasised-primary-shared-active-background-color
-	);
-	border: var(--component-button-emphasised-primary-shared-active-border);
-}
-.stand-button-emphasised-primary:disabled {
-	color: var(--component-button-emphasised-primary-shared-disabled-color);
-	background: var(
-		--component-button-emphasised-primary-shared-disabled-background-color
-	);
-	border: var(--component-button-emphasised-primary-shared-disabled-border);
-}
-
-/* example setup of button/link button style using md size and neutral secondary variant */
-.stand-button-neutral-secondary {
-	color: var(--component-button-neutral-secondary-shared-color);
-	background: var(--component-button-neutral-secondary-shared-background-color);
-	height: var(--component-button-neutral-secondary-md-height);
-	padding: var(--component-button-neutral-secondary-md-padding-top)
-		var(--component-button-neutral-secondary-md-padding-right)
-		var(--component-button-neutral-secondary-md-padding-bottom)
-		var(--component-button-neutral-secondary-md-padding-left);
-	font: var(--component-button-neutral-secondary-md-typography-font);
-	letter-spacing: var(
-		--component-button-neutral-secondary-md-typography-letter-spacing
-	);
-	font-variation-settings: 'wdth'
-		var(--component-button-neutral-secondary-md-typography-font-width);
-	border: var(--component-button-neutral-secondary-shared-border);
-	border-radius: var(--component-button-neutral-secondary-shared-border-radius);
-}
-.stand-button-neutral-secondary:hover {
-	background: var(
-		--component-button-neutral-secondary-shared-hover-background-color
-	);
-	border: var(--component-button-neutral-secondary-shared-hover-border);
-}
-.stand-button-neutral-secondary:active {
-	background: var(
-		--component-button-neutral-secondary-shared-active-background-color
-	);
-	border: var(--component-button-neutral-secondary-shared-active-border);
-}
-.stand-button-neutral-secondary:disabled {
-	color: var(--component-button-neutral-secondary-shared-disabled-color);
-	background: var(
-		--component-button-neutral-secondary-shared-disabled-background-color
-	);
-	border: var(--component-button-neutral-secondary-shared-disabled-border);
-}
-```
-
-```html
-<button class="stand-button stand-button-emphasised-primary">
-	Button Label
-</button>
-<button class="stand-button stand-button-emphasised-primary" disabled>
-	Disabled Button Label
-</button>
-<a class="stand-button stand-button-neutral-secondary" href="#"
-	>LinkButton Label</a
->
-```
-
-**TypeScript/JavaScript**
-
-Use the `componentButton` variable and the `ComponentButton` type to define your custom styles in TypeScript/JavaScript:
-
-```ts
-import type { ComponentButton } from '@guardian/stand'; // if types required
-import { componentButton } from '@guardian/stand/button';
-
-/* NB: The HTML style attribute cannot target psuedo selectors, so they haven't been implemented e.g. hover/focus */
-const sharedButtonStyles = `
-  display: ${componentButton.shared.display};
-  -webkit-appearance: ${componentButton.shared['-webkit-appearance']};
-  text-align: ${componentButton.shared['text-align']};
-  box-shadow: ${componentButton.shared['box-shadow']};
-  text-decoration: ${componentButton.shared['text-decoration']};
-  cursor: ${componentButton.shared.cursor};
-  justify-content: ${componentButton.shared['justify-content']};
-  align-items: ${componentButton.shared['align-items']};
-`;
-
-const emphasisedPrimaryButtonStyles = `
-  ${sharedButtonStyles}
-  color: ${componentButton['emphasised-primary'].shared.color};
-  background: ${componentButton['emphasised-primary'].shared.backgroundColor};
-  height: ${componentButton['emphasised-primary'].md.height};
-  padding: ${componentButton['emphasised-primary'].md.padding.top}
-    ${componentButton['emphasised-primary'].md.padding.right}
-    ${componentButton['emphasised-primary'].md.padding.bottom}
-    ${componentButton['emphasised-primary'].md.padding.left};
-  font: ${componentButton['emphasised-primary'].md.typography.font};
-  letter-spacing: ${componentButton['emphasised-primary'].md.typography.letterSpacing};
-  font-variation-settings: 'wdth'
-  ${componentButton['emphasised-primary'].md.typography.fontWidth};
-  border: ${componentButton['emphasised-primary'].shared.border};
-  border-radius: ${componentButton['emphasised-primary'].shared.borderRadius};
-`;
-
-const emphasisedPrimaryButtonDisabledStyles = `
-  ${emphasisedPrimaryButtonStyles}
-  cursor: ${componentButton.shared[':disabled'].cursor};
-  color: ${componentButton['emphasised-primary'].shared[':disabled'].color};
-  background: ${componentButton['emphasised-primary'].shared[':disabled'].backgroundColor};
-  border: ${componentButton['emphasised-primary'].shared[':disabled'].border};
-`;
-
-const neutralSecondaryButtonStyles = `
-  ${sharedButtonStyles}
-  color: ${componentButton['neutral-secondary'].shared.color};
-  background: ${componentButton['neutral-secondary'].shared.backgroundColor};
-  height: ${componentButton['neutral-secondary'].md.height};
-  padding: ${componentButton['neutral-secondary'].md.padding.top}
-    ${componentButton['neutral-secondary'].md.padding.right}
-    ${componentButton['neutral-secondary'].md.padding.bottom}
-    ${componentButton['neutral-secondary'].md.padding.left};
-  font: ${componentButton['neutral-secondary'].md.typography.font};
-  letter-spacing: ${componentButton['neutral-secondary'].md.typography.letterSpacing};
-  font-variation-settings: 'wdth'
-  ${componentButton['neutral-secondary'].md.typography.fontWidth};
-  border: ${componentButton['neutral-secondary'].shared.border};
-  border-radius: ${componentButton['neutral-secondary'].shared.borderRadius};
-`;
-
-// e.g. adding to DOM using vanilla JS styles
-document.getElementById('app')!.innerHTML = `
-    <button style="${emphasisedPrimaryButtonStyles}">Button Label</button>
-    <button disabled style="${emphasisedPrimaryButtonDisabledStyles}">Disabled Button Label</button>
-    <a href="#" style="${neutralSecondaryButtonStyles}">LinkButton Label</a>
-`;
-```
-
-### `Icon`
-
-The Icon component provides a flexible way to display icons in your application. It supports both Material Symbols (font-based icons) and SVG icons (Material Icons or custom SVG components), with consistent sizing and color control.
-
-**When to use**
-
-- Display icons alongside text or buttons
-- Represent actions, states, or categories visually
-- Provide visual cues in UI elements
-
-**Peer dependencies:**
-
-- `@emotion/react`
-- `react`
-- `react-dom`
-- `typescript`
-
-See the `peerDependencies` section of `package.json` for compatible versions.
-
-See [icon custom component build](#icon-custom-component-build) for usage without React/Emotion.
-
-#### Example usage
-
-See "Emotion/React" heading under the `Icon` component on [codesandbox.io](https://codesandbox.io/p/sandbox/mrzkrw).
-
-```tsx
-import { Icon } from '@guardian/stand/icon';
-import { baseColors } from '@guardian/stand';
-
-/* types, if required */
-import type { IconProps, IconTheme } from '@guardian/stand/icon';
-
-/* Material Symbols (font icon) */
-<Icon size="md" symbol="home"></Icon>
-
-/* Material Symbols with custom color */
-<Icon size="md" fill={baseColors.red[500]} symbol="home"></Icon>
-
-/* Standalone meaningful icon (use alt prop) */
-<Icon alt="Warning: High priority" symbol="warning"></Icon>
-
-/* Material Icons (SVG) */
-import HomeIcon from '@material-design-icons/svg/outlined/home.svg?react';
-<Icon size="md" alt="Home">
-	<HomeIcon />
-</Icon>
-
-/* Custom SVG component */
-const CustomIcon = () => (
-	<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
-		<path d="M12 2L2 7v10c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V7l-10-5z" />
-	</svg>
-);
-
-<Icon size="lg" fill={baseColors.blue[500]} alt="Shield protection">
-	<CustomIcon />
-</Icon>
-```
-
-#### Props
-
-| Name           | Type                            | Required    | Default | Description                                                                                                                                                 |
-| -------------- | ------------------------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `symbol`       | `MaterialSymbol`                | Conditional | N/A     | Name of the Material Symbol to display (e.g., "home", "add"). Uses the `MaterialSymbol` type for type safety. Alternative to providing the icon as a child. |
-| `children`     | `ReactNode` \| `MaterialSymbol` | Conditional | N/A     | Icon content - either a Material Symbol name (typed as `MaterialSymbol`), an SVG component (ReactNode), or left empty if using `symbol`.                    |
-| `size`         | `'sm'` \| `'md'` \| `'lg'`      | No          | `'md'`  | Controls the icon dimensions.                                                                                                                               |
-| `fill`         | `string`                        | No          | N/A     | Fill/color of the icon. Default is to inherit from text color or icon defaults.                                                                             |
-| `alt`          | `string`                        | Conditional | N/A     | Alternative text for screen readers. Required if the icon conveys meaning on its own. Omit for decorative icons alongside text.                             |
-| `theme`        | `IconTheme` (partial)           | No          | N/A     | Override Stand tokens for this instance; merged over the default theme.                                                                                     |
-| `cssOverrides` | `SerializedStyles`              | No          | N/A     | Low-level escape hatch for Emotion overrides when theming is insufficient.                                                                                  |
-| `className`    | `string`                        | No          | N/A     | Additional class name(s) for the icon. For Material Symbols, combines with `material-symbols`.                                                              |
-
-**`size`**
-
-The icon supports three sizes:
-
-- `sm` (small): 20px
-- `md` (medium): 24px
-- `lg` (large): 32px
-
-**`symbol`**
-
-The `symbol` prop provides a convenient way to specify a Material Symbol icon by name (typed as `MaterialSymbol`, e.g., `"home"`, `"add"`, `"close"`). This is the recommended approach for font-based icons. If both `symbol` and `children` are provided, `symbol` takes precedence for Material Symbols.
-
-**`children`**
-
-The Icon component accepts two types of children:
-
-- **MaterialSymbol**: Pass the icon name as a string typed as `MaterialSymbol` (e.g., `"home"`, `"add"`, `"close"`). Requires the Material Symbols font to be loaded. (Prefer using the `symbol` prop for clarity.)
-- **ReactNode** (SVG): Pass an SVG component (e.g., from `@material-design-icons/svg` or a custom SVG component).
-
-**`alt`**
-
-Provide alternative text to describe the icon's meaning for screen readers:
-
-- **When to use**: Icons that convey meaning on their own (status indicators, standalone alerts, informational graphics)
-- **When to omit**: Icons that are purely decorative or appear alongside descriptive text
-
-#### Customisation
-
-We recommend using the default theme. When needed, use the `theme` or `cssOverrides` props.
-
-**Custom theme**
-
-```tsx
-import type { IconTheme } from '@guardian/stand/icon';
-import { Icon } from '@guardian/stand/icon';
-import { baseSizing } from '@guardian/stand';
-
-const customTheme: Partial<IconTheme> = {
-	shared: {
-		display: 'block',
-		'user-select': 'all',
-	},
-	md: {
-		size: baseSizing['size-48-rem'],
-	},
-};
-
-const Component = () => (
-	<Icon size="md" theme={customTheme}>
-		home
-	</Icon>
-);
-```
-
-**CSS overrides**
-
-```tsx
-import { Icon } from '@guardian/stand/icon';
-import { baseColors, baseSpacing, semanticSizing } from '@guardian/stand';
-import { css } from '@emotion/react';
-
-const customStyles = css`
-	padding: ${baseSpacing['4-rem']};
-	background-color: ${baseColors.yellow[400]};
-	border-radius: ${semanticSizing.border['extra-wide']};
-`;
-
-const Component = () => (
-	<Icon size="lg" fill={baseColors.neutral[900]} cssOverrides={customStyles}>
-		home
-	</Icon>
-);
-```
-
-#### Icon Custom Component Build
-
-If you're not using React/Emotion, or `@guardian/stand` is not compatible with your project, you can create a custom Icon component using the styles defined in the `IconTheme` type.
-
-You will however be responsible for any additional functionality on top of the styles, for example icon loading, accessibility, etc.
-
-See "Custom Component" heading under the `Icon` component on [codesandbox.io](https://codesandbox.io/p/sandbox/mrzkrw) for an example of a custom component build without React/Emotion.
-
-**`css`**
-
-You can import the Icon styles as CSS from the package, make sure that your build process supports importing CSS from `node_modules`/`package.json`:
-
-```css
-/* import the icon font and icon styles */
-@import '@guardian/stand/fonts/MaterialSymbolsOutlined.css';
-@import '@guardian/stand/component/icon.css';
-
-/*
-or for scenarios where you have to use relative paths/node_modules directly:
-
-@import 'node_modules/@guardian/stand/dist/fonts/MaterialSymbolsOutlined.css';
-@import 'node_modules/@guardian/stand/dist/style/build/css/component/icon.css';
-*/
-
-@import '@guardian/stand/base/spacing.css';
-@import '@guardian/stand/base/colors.css';
-
-.stand-icon {
-	display: var(--component-icon-shared-display);
-	user-select: var(--component-icon-shared-user-select);
-	font-size: var(--component-icon-lg-size);
-}
-
-.stand-icon-font-color {
-	color: var(--base-colors-magenta-400);
-}
-
-.stand-icon-svg > svg {
-	width: var(--component-icon-lg-size);
-	height: var(--component-icon-lg-size);
-}
-
-.stand-icon-svg-color > svg {
-	fill: var(--base-colors-magenta-400);
-}
-```
-
-```html
-<!-- Material Symbols (font icons) -->
-<span class="material-symbols stand-icon">home</span>
-<span class="material-symbols stand-icon stand-icon-font-color">upload</span>
-
-<!-- SVG icons -->
-<span class="material-symbols stand-icon stand-icon-svg">
-	<svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>
-</span>
-<span class="material-symbols stand-icon stand-icon-svg stand-icon-svg-color">
-	<svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>
-</span>
-```
-
-**TypeScript/JavaScript**
-
-Use the `componentIcon` variable and the `ComponentIcon` type to define your custom styles in TypeScript/JavaScript:
-
-```ts
-import type { ComponentIcon } from '@guardian/stand'; // if types required
-import { componentIcon, baseColors } from '@guardian/stand';
-
-const iconStyles = `
-  display: ${componentIcon.shared.display};
-  user-select: ${componentIcon.shared['user-select']};
-  font-size: ${componentIcon.lg.size};
-`;
-
-const iconFontColorStyles = `
-  ${iconStyles}
-  color: ${baseColors.magenta[400]};
-`;
-
-const iconSvgStyles = `
-  width: ${componentIcon.lg.size};
-  height: ${componentIcon.lg.size};
-`;
-
-const iconSvgColorStyles = `
-  ${iconSvgStyles}
-  fill: ${baseColors.magenta[400]};
-`;
-
-// e.g. adding to DOM using vanilla JS styles
-document.getElementById('app')!.innerHTML = `
-  <h3>
-        Using <code>typescript</code>/<code>javascript</code>
-  </h3>
-  <div>see <code>src/icon/custom.ts</code><div>
-  <div style="margin-top: 4px;">Material Symbols</div>
-  <div class="container">
-    <span class="material-symbols" style="${iconStyles}">home</span>
-    <span class="material-symbols" style="${iconFontColorStyles}">upload</span>
-  </div>
-  <div style="margin-top: 4px;">SVGs</div>
-  <div class="container">
-    <span class="material-symbols" style="${iconStyles}"><svg style="${iconSvgStyles}"...>...</svg></span>
-    <span class="material-symbols" style="${iconFontColorStyles}"><svg style="${iconSvgColorStyles}"...>...</svg></span>
-  </div>
-`;
-```
-
-### `LinkButton`
-
-An anchor element styled like the Stand `Button` component, based on the React Aria `Link`. It keeps link semantics (`href`, `target`, `rel`) while sharing the same variants and sizes as `Button`.
-
-**When to use**
-
-- Navigational links that should visually align with buttons
-- Cross-page CTAs where a button look-and-feel is preferred
-- Situations requiring disabled styling while preserving link semantics
-
-**Peer dependencies:**
-
-- `@emotion/react`
-- `react`
-- `react-dom`
-- `react-aria-components`
-- `typescript`
-
-See the `peerDependencies` section of `package.json` for compatible versions.
-
-See [link button custom component build](#button-custom-component-build) for usage without React/Emotion.
-
-#### Example usage
-
-See "Emotion/React" heading on [codesandbox.io](https://codesandbox.io/p/sandbox/jctg2k)
-
-```tsx
-import { LinkButton } from '@guardian/stand/button';
-import type { LinkButtonTheme, LinkButtonProps } from '@guardian/stand/button';
-
-const Example = () => (
-	<>
-		<LinkButton
-			href="/article"
-			variant="emphasised-primary"
-			size="md"
-			target="_blank"
-			rel="noreferrer"
-		>
-			Read article
-		</LinkButton>
-
-		<LinkButton
-			href="/settings"
-			variant="neutral-secondary"
-			size="sm"
-			isDisabled
-		>
-			Disabled link
-		</LinkButton>
-	</>
-);
-```
-
-#### Props
-
-| Name           | Type                                                                                               | Required | Default                | Description                                                                                               |
-| -------------- | -------------------------------------------------------------------------------------------------- | -------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
-| `href`         | `string`                                                                                           | Yes      | N/A                    | Destination URL for the link.                                                                             |
-| `size`         | `'xs'` \| `'sm'` \| `'md'` \| `'lg'`                                                               | No       | `'md'`                 | Controls the link-button dimensions and typography.                                                       |
-| `variant`      | `'emphasised-primary'` \| `'emphasised-secondary'` \| `'neutral-primary'` \| `'neutral-secondary'` | No       | `'emphasised-primary'` | Chooses the colour scheme and interaction states.                                                         |
-| `children`     | `ReactNode`                                                                                        | Yes      | N/A                    | Content of the link.                                                                                      |
-| `isDisabled`   | `boolean`                                                                                          | No       | `false`                | Disables interaction and applies disabled styling.                                                        |
-| `theme`        | `LinkButtonTheme` (partial)                                                                        | No       | N/A                    | Override Stand tokens for this instance; merged over the default theme.                                   |
-| `cssOverrides` | `SerializedStyles` \| `SerializedStyles[]`                                                         | No       | N/A                    | Low-level escape hatch for Emotion overrides when theming is insufficient.                                |
-| `className`    | `string`                                                                                           | No       | N/A                    | Optional class name forwarded to the root React Aria link.                                                |
-| `...props`     | `ReactAria Link` props                                                                             | No       | N/A                    | All other props from `react-aria-components` `Link` (e.g. `target`, `rel`, `aria-label`, event handlers). |
-
-**`size` and `variant`**
-
-- Sizes: `xs`, `sm`, `md`, `lg`
-- Variants: `emphasised-primary`, `emphasised-secondary`, `neutral-primary`, `neutral-secondary`
-
-#### Customisation
-
-We recommend using the default theme. When needed, use the `theme` or `cssOverrides` props.
-
-**Custom theme**
-
-```tsx
-import type { LinkButtonTheme } from '@guardian/stand/button';
-import { LinkButton } from '@guardian/stand/button';
-import { baseColors } from '@guardian/stand';
-
-const customTheme: Partial<LinkButtonTheme> = {
-	'emphasised-primary': {
-		shared: {
-			backgroundColor: baseColors['cool-purple'][200],
-			color: baseColors['cool-purple'][900],
-			border: `2px solid ${baseColors['cool-purple'][700]}`,
-			':hover': {
-				backgroundColor: baseColors['cool-purple'][300],
-				border: `2px solid ${baseColors['cool-purple'][700]}`,
-			},
-			':active': {
-				backgroundColor: baseColors['cool-purple'][400],
-				border: `2px solid ${baseColors['cool-purple'][700]}`,
-			},
-		},
-	},
-};
-
-const Component = () => (
-	<LinkButton
-		href="/"
-		variant="emphasised-primary"
-		size="md"
-		theme={customTheme}
-	>
-		Custom Themed LinkButton
-	</LinkButton>
-);
-```
-
-**CSS overrides**
-
-```tsx
-import { LinkButton } from '@guardian/stand/button';
-import { baseSpacing } from '@guardian/stand';
-import { css } from '@emotion/react';
-
-const customStyles = css`
-	width: 100%;
-	text-transform: full-width;
-	font-variant: small-caps;
-	padding-inline: ${baseSpacing['24-rem']};
-`;
-
-const Component = () => (
-	<LinkButton
-		href="/"
-		variant="neutral-primary"
-		size="sm"
-		cssOverrides={customStyles}
-	>
-		CSSOverrides LinkButton
-	</LinkButton>
-);
-```
-
-#### LinkButton Custom Component Build
-
-LinkButton shares the same tokens and CSS output as `Button`. Use the [Button custom component build](#button-custom-component-build) guidance to consume the CSS or TypeScript tokens when you need a non-React implementation.
-
-### Typography
-
-The Typography component provides a convenient way to wrap React elements in a font variant.
-
-**Peer dependencies**
-
-- `@emotion/react`
-- `react`
-- `react-dom`
-- `typescript`
-
-See the `peerDependencies` section of `package.json` for compatible versions.
-
-#### Example usage
-
-```tsx
-import { Typography } from '@guardian/stand/typography';
-
-/* types, if required */
-import type { Typography, TypographyTheme } from '@guardian/stand/typography';
-
-/* Paragraph element with body-md preset and text children */
-<Typography element="p" variant="body-md">Body text here</Typography>
-
-/* Div with an italic text wrapped inside */
-<Typography element="div" variant="body-md">Some text, with <Typography element="i" variant="body-italic-md">even more text</Typography></Typography>
-```
-
-#### Props
-
-| Name           | Type               | Required | Default   | Description                                          |
-| -------------- | ------------------ | -------- | --------- | ---------------------------------------------------- |
-| `element`      | Various            | No       | 'span'    | HTML element to render with font applied to.         |
-| `variant`      | Various            | No       | 'body-md' | Font variant to apply as a CSS style to the element. |
-| `children`     | `ReactNode`        | No       | N/A       | Content to render inside the supplied HTML element.  |
-| `theme`        | `TypographyTheme`  | No       | N/A       | Custom theme overrides for the typography.           |
-| `cssOverrides` | `SerializedStyles` | No       | N/A       | Custom CSS styles for the typography.                |
-| `className`    | `string`           | No       | N/A       | Additional class name(s) for the typography.         |
-
-#### Customisation
-
-**Custom theme**
-
-The `theme` prop allows you to override the color of the text:
-
-```tsx
-import type { TypographyTheme } from '@guardian/stand/typography';
-import { Typography } from '@guardian/stand/typography';
-
-const customTheme: TypographyTheme = {
-	color: 'red',
-};
-const Component = () => (
-	<Typography element="p" variant="body-md" theme={customTheme}>
-		Text
-	</Typography>
-);
-```
-
-**CSS overrides**
-
-The `cssOverrides` prop allows you to pass custom CSS to the rendered element.
-
-## Components - Editorial
-
-Specialised components for use in specific editorial use cases.
-
-### `Byline`
-
-A flexible byline editor component built in ProseMirror and React with usability and accessibility in mind.
-
-**Peer dependencies:**
-
-You'll need to install the following peer dependencies in your project to use the `Byline` component:
-
-- `@emotion/react`
-- `@guardian/prosemirror-invisibles`
-- `prosemirror-dropcursor`
-- `prosemirror-history`
-- `prosemirror-keymap`
-- `prosemirror-model`
-- `prosemirror-state`
-- `prosemirror-view`
-- `react`
-- `react-dom`
-- `typescript`
-
-See the `peerDependencies` section of `package.json` for compatible versions.
-
-**Note:** If you only need the built CSS (`@guardian/stand/component/byline.css`), you don't need to install these dependencies.
-
-#### Usage
+```bash
+# With pnpm
+pnpm add @guardian/stand
 
-```tsx
-import type { BylineModel } from '@guardian/stand/byline';
-import { Byline } from '@guardian/stand/byline';
+# or with npm
+npm install @guardian/stand
 
-const Component = () => {
-    const bylineModel: BylineModel = {
-        // ...set up your byline model here
-    };
-    ...
-	return (
-        <>
-        ...
-            <Byline initialValue={bylineModel} />
-        ...
-        </>
-    );
-};
+# or with yarn
+yarn add @guardian/stand
 ```
 
-By itself the `Byline` component is just the editor UI. You will need to set up the ProseMirror editor state, schema, and plugins to get a fully functioning byline editor. See the props and example below for a more complete implementation.
-
-The `BylineModel` type defines the structure of the byline data which is agnostic from any other data structure. You must convert to/from this model when integrating with your application's data structures.
-
-#### Props
-
-See [`BylineProps`](src/byline/Byline.tsx#L41) for the full list of props, usage example can be seen in Storybook.
-
-#### Example
-
-The `ContentByline` component in `flexible-frontend` has a detailed example of how to use the `Byline` component from Stand. See [ContentByline.tsx](https://github.com/guardian/flexible-content/blob/1d537615a18ae24a4a5410a3f945b2b9db1dbb47/flexible-frontend/src/app/components/furniture/content-byline/ContentByline.tsx#L72-L205).
-
-### TagPicker
-
-#### TagAutocomplete
-
-_Status: Testing_
-
-Part of the overall TagPicker component, the TagAutocomplete provides an accessible
-autocomplete input for selecting tags from a list of options, based on the [React Aria ComboBox](https://react-spectrum.adobe.com/react-aria/ComboBox) component.
-
-**Peer dependencies:**
-
-- `@emotion/react`
-- `react`
-- `react-aria-components`
-- `react-dom`
-- `typescript`
-
-See the `peerDependencies` section of `package.json` for compatible versions.
-
-**Note:** If you only need the built CSS (`@guardian/stand/component/tagAutocomplete.css`), you don't need to install these dependencies.
-
-##### Props
-
-See [`TagAutocompleteProps`](src/components/tag-picker/TagAutocomplete.tsx#L23) for the full list of props, usage example can be seen in Storybook.
-
-#### TagTable
-
-_Status: Testing_
-
-Part of the overall TagPicker component, the TagTable provides an accessible
-table for displaying tags, with options to add, remove, and reorder tags via drag and drop,
-based on the [React Aria Table](https://react-spectrum.adobe.com/react-aria/Table) component.
-
-**Peer dependencies:**
-
-- `@emotion/react`
-- `react`
-- `react-aria-components`
-- `react-dom`
-- `typescript`
-
-See the `peerDependencies` section of `package.json` for compatible versions.
-
-**Note:** If you only need the built CSS (`@guardian/stand/component/tagTable.css`), you don't need to install these dependencies.
+Depending on your project setup, you may also need to install [peer dependencies](https://nodejs.org/en/blog/npm/peer-dependencies).
 
-##### Props
+**My project uses React, Emotion, and TypeScript:**
 
-See [`TagTableProps`](src/components/tag-picker/TagTable.tsx#L31) for the full list of props, usage example can be seen in Storybook.
+See the `peerDependencies` in `package.json` for compatible versions and install them.
 
-#### Usage
+If you're using the Tools Design System, you may also want to install the compatible version of [`react-aria-components`](https://react-aria.adobe.com/).
 
-_Example with TagAutocomplete and TagTable combined:_
+For specific Editorial Components, check the documentation for each component for additional dependencies.
 
-```tsx
-import { TagAutocomplete, TagTable } from '@guardian/stand/tag-picker';
+**My project doesn't (or can't) use React, Emotion, or TypeScript:**
 
-const Component = () => {
-  const [selectedTags, setSelectedTags] = useState<
-    TagManagerObjectData[] // TagManagerObjectData is an internal type representing a Tag
-  >([]);
-  const [options, setOptions] = useState<TagManagerObjectData[]>([]);
-  const [value, setValue] = useState('');
-  const onChange = (inputText: string) => {
-    setValue(inputText);
-    if (inputText === '') {
-      setOptions([]);
-      return;
-    }
+You can still use design tokens and styles from the Tools Design System. Import [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties) and/or JS design tokens directly from the package. Every component has a "Custom Component Build" section in its documentation showing how to do this.
 
-    if (inputText === '*') {
-      setOptions(exampleTags); // exampleTags is an array of Tags
-      return;
-    }
+**My project doesn't use JavaScript at all:**
 
-    // Simple filtering against exampleTags
-    const filteredItems = exampleTags.filter((t) =>
-      t.internalName.toLowerCase().includes(inputText.toLowerCase()),
-    );
-    return setOptions(filteredItems);
-  };
-  return (
-    <>
-      <div
-        css={css`
-            display: flex;
-        `}
-      >
-        <TagAutocomplete
-          onChange={onChange}
-          options={options}
-          label="Tags"
-          addTag={(tag) =>
-              setSelectedTags((tags) => {
-                  return [...tags, tag];
-              })
-          }
-          loading={false}
-          placeholder={''}
-          disabled={false}
-          value={value}
-        />
-        <select>
-           option>All tags</option>
-        </select>
-      </div>
-      <TagTable rows={selectedTags} filterRows={() => true} />
-    </>
-  );
-};
-```
-
-#### Example
-
-This is currently still in testing phase, so a production implementation is not yet available.
-
-### `UserMenu`
+You can import CSS variables from the package, provided your build process supports importing CSS from `node_modules`. See the "Custom Component Build" section in each component's documentation.
 
-The UserMenu component presents a collection of accessibility settings for users to customise their experience of using the application. The current supported settings are:
+## Usage
 
-- "Text Size"
-- "Font Family"
-- "Color scheme"
+See the [Tools Design System](https://guardian.github.io/stand/?path=/docs/stand-tools-design-system-introduction--docs) and [Editorial Components](https://guardian.github.io/stand/?path=/docs/stand-editorial-components-introduction--docs) documentation for details.
 
-**Peer dependencies:**
+## Contributing
 
-- `@emotion/react`
-- `react`
-- `react-dom`
-- `typescript`
-- `react-aria-components`
+See the [Contributing guidelines](https://guardian.github.io/stand/?path=/docs/contributing--docs) for guidelines on contributing to this project. Project setup and common tasks are listed below.
 
-See the `peerDependencies` section of `package.json` for compatible versions.
+## Getting Started
 
-**When to use**
+> If you are looking to **use Stand in your project**, see the [Tools Design System](https://guardian.github.io/stand/?path=/docs/stand-tools-design-system-introduction--docs) or [Editorial Components](https://guardian.github.io/stand/?path=/docs/stand-editorial-components-introduction--docs) documentation for installation and usage instructions.
 
-- as an application-level "accessibility options" panel
-- as part of a more general options page
+The following steps are for **developing the Stand library itself**.
 
-#### Usage
+1. **Install dependencies:**
 
-```tsx
-import { UserMenu, type UserMenuProps } from '@guardian/stand/user-menu';
-
-const customFontFamilyOptions = [
-	{
-		id: 'white',
-		buttonStyle: {
-			backgroundColor: 'white',
-		},
-		isDefault: true,
-	},
-	{
-		id: 'pink',
-		buttonStyle: {
-			backgroundColor: 'pink',
-		},
-	},
-];
-
-const Component = ({
-	currentPreferences,
-	updatePreferences,
-}: {
-	currentPreferences: UserMenuProps['preferences'];
-	updatePreferences: UserMenuProps['updatePreferences'];
-}) => {
-	...
-	return (
-		<>
-			...
-			<UserMenu
-				feedBacklink="https://example.com/feedback-form"
-				fontFamilyOptions={customFontFamilyOptions}
-				colorSchemeOptions={[]}
-				preferences={currentPreferences}
-				updatePreferences={updatePreferences}
-			/>
-			...
-		</>
-	);
-};
-```
-
-`UserMenu` does not manage the persistence of the settings, nor how they are applied in the application when set - it merely presents a set of [controlled](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components) inputs for displaying and setting the values held by the application.
-
-There are options defaults for each of the setting, but these can be overridden with the props. IF the application does not support customising one of the options, setting an empty array for one of the sets of options will exclude that option from the UI (like in `colorSchemeOptions` in the example above).
+   ```bash
+   # With pnpm
+   pnpm install
+   ```
 
-#### Props
+2. **Run Storybook**: Most development is done within Storybook, which provides a live environment for building and testing components in isolation:
 
-See [`UserMenuProps`](src/user-menu/UserMenu.tsx#L14) for the full list of props, usage example can be seen in Storybook.
+   ```bash
+   pnpm storybook
+   ```
 
-#### Example
+   This will start Storybook at `http://localhost:6007`. See the [contributing guidelines](https://guardian.github.io/stand/?path=/docs/contributing--docs) for how to add new components and stories.
 
-This is currently still in testing phase, so a production implementation is not yet available.
+3. **Build** the package for publishing:
 
-### Contributing
+   ```bash
+   pnpm build
+   ```
 
-See the [Contributing to Stand](./CONTRIBUTING.md) documentation for guidelines on contributing to this project. Project setup and common tasks are listed below.
+   To regenerate Style Dictionary design token outputs after changing any token files (see [Design Tokens and Style Dictionary](#design-tokens-and-style-dictionary)):
 
-### Setup
+   ```bash
+   pnpm build-styled
+   ```
 
-- Run `./setup.sh` in the project root (flexible-content) directory to set up pnpm, install dependencies, and build the project.
+4. **Test:**
 
-### Tasks
+   ```bash
+   pnpm test                 # unit tests (Jest)
+   pnpm test:e2e             # end-to-end tests (Playwright)
+   pnpm test:react-matrix    # compatibility matrix tests (see Compatibility)
+   pnpm tsc                  # TypeScript type checking
+   pnpm lint                 # lint (pnpm lint:fix to auto-fix)
+   pnpm format:check         # formatting check (pnpm format:fix to auto-fix)
+   ```
 
-- Run `pnpm install` to install dependencies.
-- Run `pnpm build` to build, this makes any changes available to flexible-frontend
-- Run `pnpm storybook` to run Storybook
-- Run `pnpm build:storybook` to build the Storybook static site
-- Run `pnpm build-styled` to build the Style Dictionary styles
-- Run `pnpm test` to run tests
-- Run `pnpm test:e2e` to run end-to-end tests using Playwright
-- Run `pnpm test:react-matrix` to run matrix tests (see Compatibility section below)
-- Run `pnpm tsc` to run check TypeScript types
-- Run `pnpm lint` to run the linter
-  - Run `pnpm lint:fix` to fix any auto-fixable issues
-- Run `pnpm format:check` to check code formatting
-  - Run `pnpm format:fix` to fix code formatting issues
+## Design Tokens and Style Dictionary
 
-### Style Dictionary
+The [Design Tokens](https://www.w3.org/community/design-tokens/) specification provides standards upon which products and design tools can rely for sharing stylistic pieces of a design system at scale.
 
 The project uses [Style Dictionary](https://styledictionary.com/) to manage design tokens.
 
-Tokens are defined in the `src/styleD/tokens` folder.
+Tokens are defined in `src/styleD/tokens/`, the generated outputs live in `src/styleD/build/`, and both are committed to the repository. During the package build, Rollup copies the build outputs into `dist/styleD/build/` for publishing.
 
-The output styles are generated into the `src/styleD/build` folder.
+Most foundation tokens are generated from Figma variables, see `scripts/figma/README.md` for details.
 
-We use rollup to copy the built styles into the `dist/styleD/build` folder during the build process, and these are published with the package.
+After making changes to any token files, regenerate the outputs and commit them:
 
-Most tokens are generated from Figma variables using a script to make these available in the `src/styleD/tokens` folder. See the [Generate Design Tokens from Figma Variables](./scripts/figma/README.md) documentation for more details.
-
-Use `pnpm build-styled` to generate the styles after making changes to the tokens and make sure to test and commit the changes to the built styles.
-
-See the [Style Dictionary documentation](./docs/style-dictionary.md) for more details on how we structure and generate the styles.
+```bash
+pnpm build-styled
+```
 
-### Compatibility
+See the [Style Dictionary documentation](https://guardian.github.io/stand/?path=/docs/style-dictionary--docs) for more details on how we structure and generate the styles.
 
-See the package.json `peerDependencies` section for compatible versions of React and other dependencies that Stand works with.
+## Compatibility
 
-Version sets for matrix testing live in `./scripts/deps-matrix-versions.json`:
+See the `peerDependencies` in `package.json` for compatible versions of React and other dependencies.
 
-The test script `./scripts/test-deps-matrix.sh` reads this JSON file first, then applies any environment overrides you supply. Precedence is:
+Version sets for matrix testing live in `./scripts/deps-matrix-versions.json`. The test script `./scripts/test-deps-matrix.sh` reads this file first, then applies any environment overrides. Precedence is:
 
 1. Explicit env var (e.g. `REACT_VERSIONS="18.0.0 19.0.0"`)
 2. Value from `deps-matrix-versions.json`
 
 All three variables (`REACT_VERSIONS`, `EMOTION_VERSIONS`, `TS_VERSIONS`) must be defined after loading; otherwise the script exits with an error.
 
-Matrix generation in CI uses the same JSON file in the workflow: `../.github/workflows/stand-component-library-deps-matrix.yml` to ensure consistency.
+Matrix generation in CI uses the same JSON file in the workflow `../.github/workflows/stand-component-library-deps-matrix.yml` to ensure consistency.
 
-#### Updating Supported Versions
+### Updating Supported Versions
 
-1. Edit `./scripts/deps-matrix-versions.json` with new versions
+1. Edit `./scripts/deps-matrix-versions.json` with new versions.
 2. Run the matrix test locally:
    ```bash
    ./scripts/test-deps-matrix.sh
@@ -1807,13 +161,23 @@ Matrix generation in CI uses the same JSON file in the workflow: `../.github/wor
    ```bash
    REACT_VERSIONS="18.0.0" EMOTION_VERSIONS="11.14.0" TS_VERSIONS="5.1" ./scripts/test-deps-matrix.sh
    ```
-4. Review results (table output and any failures). Fix issues or adjust code
-5. Update `peerDependencies` in `package.json` to reflect the new minimum / tested range
-6. Open a PR, the CI pipeline will comment with the compatibility matrix
-
-#### Tips
-
-- Keep versions in ascending order for readability
-- Remove deprecated versions only after confirming no downstream tool depends on them
-- Add a new version first, then run the matrix, then adjust `peerDependencies` once green
-- Changes to `peerDependencies` are always a breaking change to the library, as per our [recommendations](https://github.com/guardian/recommendations/blob/main/npm-packages.md#changes-to-peerdependencies-ranges-are-breaking)
+4. Review results (table output and any failures). Fix issues or adjust code.
+5. Update `peerDependencies` in `package.json` to reflect the new minimum/tested range.
+6. Open a PR, the CI pipeline will comment with the compatibility matrix.
+
+### Tips
+
+- Keep versions in ascending order for readability.
+- Remove deprecated versions only after confirming no downstream tool depends on them.
+- Add a new version first, then run the matrix, then adjust `peerDependencies` once green.
+- Changes to `peerDependencies` are always a breaking change, as per our [recommendations](https://github.com/guardian/recommendations/blob/main/npm-packages.md#changes-to-peerdependencies-ranges-are-breaking).
+
+## Documentation Site Map
+
+- [Getting Started](https://guardian.github.io/stand/?path=/docs/getting-started--docs)
+- [Contributing](https://guardian.github.io/stand/?path=/docs/contributing--docs)
+- [Tools Design System Introduction](https://guardian.github.io/stand/?path=/docs/stand-tools-design-system-introduction--docs)
+- [Editorial Components Introduction](https://guardian.github.io/stand/?path=/docs/stand-editorial-components-introduction--docs)
+- [Style Dictionary](https://guardian.github.io/stand/?path=/docs/style-dictionary--docs)
+- [Architecture Decision Records](https://guardian.github.io/stand/?path=/docs/architecture-decision-records--docs)
+- [Changelog](https://guardian.github.io/stand/?path=/docs/changelog--docs)