@guardian/stand 0.0.9 → 0.0.10

package/README.md

@@ -453,7 +453,1048 @@ For a list of the available base/primitives radius tokens see the [Storybook Bas
 
 For a full list of CSS Base/Primitives Radius tokens see [`base/radius.css`](./src/styleD/build/css/base/radius.css).
 
-## Components
+## 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>
+);
+```
+
+#### Button Custom Component Build
+
+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.
+
+You will however be responsible for any additional functionality on top of the styles, for example accessibility, focus management, interaction states etc.
+
+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`
 
@@ -627,6 +1668,86 @@ const Component = () => {
 
 This is currently still in testing phase, so a production implementation is not yet available.
 
+### `UserMenu`
+
+The UserMenu component presents a collection of accessibility settings for users to customise their experience of using the application. The current supported settings are:
+
+- "Text Size"
+- "Font Family"
+- "Color scheme"
+
+**Peer dependencies:**
+
+- `@emotion/react`
+- `react`
+- `react-dom`
+- `typescript`
+- `react-aria-components`
+
+See the `peerDependencies` section of `package.json` for compatible versions.
+
+**When to use**
+
+- as an application-level "accessibility options" panel
+- as part of a more general options page
+
+#### Usage
+
+```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).
+
+#### Props
+
+See [`UserMenuProps`](src/user-menu/UserMenu.tsx#L14) for the full list of props, usage example can be seen in Storybook.
+
+#### Example
+
+This is currently still in testing phase, so a production implementation is not yet available.
+
 ### Contributing
 
 See the [Contributing to Stand](./CONTRIBUTING.md) documentation for guidelines on contributing to this project. Project setup and common tasks are listed below.