@guardian/stand

Find what you need on the (news)stand!

A tools component library and design system

Any tool should be able to make use of the components and design system as an npm package, @guardian/stand, and developers should feel comfortable contributing.

Stand contains two collections: the Tools Design System, our core design system foundations and UI components, and Shareable non-Design System Components, reusable components that sit outside the design system. Both are available through @guardian/stand; inclusion in Stand does not imply that the component is part of the design system.

• Tools Design System
  • The core design system foundations and collection of components used across the Guardian's internal tools.
  • e.g. Colour, Typography, Buttons, Forms, etc.
• Shareable non-Design System Components
  • Reusable components outside the core design system. They may use design system styles, but are not required to follow all its guidelines or be verified by the design system team.
  • e.g. Byline editor, Tag picker, etc.

Start with the Tools Design System collection for general-purpose UI building blocks. Look in the shareable components collection for more specialised reusable components. Using design tokens or composing design system components does not automatically make a component part of the design system.

Contributors should use the component placement guide to choose a collection on where to place a new component.

Currently maintained by the P&E Design Systems team, but open to contributions from anyone in the company. Do reach out for help or to get involved!

Find us in the P&E Design Systems chat.

Stand is built with React, Emotion, and TypeScript, but the design system is designed to be as framework-agnostic as possible in that styles can be used without these dependencies if needed.

Contents

• Documentation
• Install
• Usage
• Contributing
• Tasks
• Design Tokens and Style Dictionary
• Compatibility
• Documentation Site Map

Documentation

All documentation is available on Github Pages Storybook, which is updated with the latest changes to the library.

Install

The library is published to npm:

# With pnpm
pnpm add @guardian/stand

# or with npm
npm install @guardian/stand

# or with yarn
yarn add @guardian/stand

Depending on your project setup, you may also need to install peer dependencies.

My project uses React, Emotion, and TypeScript:

Alongside React, Emotion and TypeScript, most projects will also need react-aria-components, which many Stand components are built on:

pnpm add react-aria-components

A few components need extra dependencies:

• DatePicker: @internationalized/date
• Byline: prosemirror-model, prosemirror-state, prosemirror-view, prosemirror-keymap, prosemirror-history, prosemirror-dropcursor and @guardian/prosemirror-invisibles

Compatible version ranges are listed under peerDependencies in package.json.

My project doesn't (or can't) use React, Emotion, or TypeScript:

You can still use design tokens and styles from the Tools Design System. Import CSS variables 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.

My project doesn't use JavaScript at all:

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. Not every component supports an interactive custom build, but the CSS variables are available if you only need the styles.

Fonts

Most applications only need Open Sans and Guardian Headline. Load Guardian Text Egyptian too if you use the article-body-* typography tokens.

Open Sans is hosted on the Guardian CDN. You can load it with CSS @import, an HTML <link>, or from the package if your bundler supports CSS imports:

@import url('https://assets.guim.co.uk/fonts/open-sans/OpenSans.css');

<link
	rel="stylesheet"
	href="https://assets.guim.co.uk/fonts/open-sans/OpenSans.css"
/>

import '@guardian/stand/fonts/OpenSans.css';

The design system only uses the bold (700) weight of Guardian Headline:

@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;
}

For the Guardian Text Egyptian @font-face declarations and other options, see the Semantic Typography documentation and the guardian/fonts repo.

Icons

Components that take a symbol or string icon prop use the Material Symbols font, which is hosted on the Guardian CDN. We recommend the Outlined style:

@import url('https://assets.guim.co.uk/fonts/material-symbols/MaterialSymbolsOutlined.css');

<link
	rel="stylesheet"
	href="https://assets.guim.co.uk/fonts/material-symbols/MaterialSymbolsOutlined.css"
/>

import '@guardian/stand/fonts/MaterialSymbolsOutlined.css';

Rounded and Sharp styles are also available. For those, and for using SVG icons instead, see the Icon documentation.

Usage

See the Tools Design System and Shareable non-Design System Components documentation for details.

Contributing

See the Contributing guidelines for guidelines on contributing to this project. Project setup and common tasks are listed below.

Getting Started

If you are looking to use Stand in your project, see the Tools Design System or Shareable non-Design System Components documentation for installation and usage instructions.

The following steps are for developing the Stand library itself.

1. Install dependencies:

   # With pnpm
   pnpm install

2. Run Storybook: Most development is done within Storybook, which provides a live environment for building and testing components in isolation:

   pnpm storybook

   This will start Storybook at http://localhost:6007. See the contributing guidelines for how to add new components and stories.

3. Build the package for publishing:

   pnpm build

   To regenerate Style Dictionary design token outputs after changing any token files (see Design Tokens and Style Dictionary):

   pnpm build-styled

4. Test:

   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 tsc6                 # TypeScript 6 type checking
   pnpm lint                 # lint (pnpm lint:fix to auto-fix)
   pnpm format:check         # formatting check (pnpm format:fix to auto-fix)

Design Tokens and Style Dictionary

The 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 to generate CSS and TypeScript token outputs from src/styleD/tokens/.

The shared Tools Design System tokens in src/styleD/tokens/base/base.json, src/styleD/tokens/semantic/semantic.json, and src/styleD/tokens/component/component.json are managed in Tokens Studio. All other token JSON files are maintained locally in this project. Shareable components and unverified Tools Design System components keep their component tokens local; after a component is verified, the design systems team moves its tokens to Tokens Studio and removes the local token file.

To change Tokens Studio managed tokens (verified Design System Components), liaise with the design systems team. The current manual process uses the Tokens Studio CLI from the project root to pull the latest tokens and regenerate the Style Dictionary outputs:

studio tokens pull
pnpm build-styled

Review the pulled source and generated output changes before committing. An automated pull workflow is planned; until it is available, do not edit the managed files directly or pull tokens from Figma variables. For locally maintained token JSON, make changes in the project and regenerate the outputs:

pnpm build-styled

See the Design Tokens documentation for more details on token usage, ownership, and generated outputs.

Compatibility

See the peerDependencies in package.json for compatible versions of React and other dependencies.

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 four variables (REACT_VERSIONS, EMOTION_VERSIONS, TS_VERSIONS, RAC_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.

Updating Supported Versions

1. Edit ./scripts/deps-matrix-versions.json with new versions.
2. Run the matrix test locally:

   ./scripts/test-deps-matrix.sh

3. (Optional) Narrow the matrix with overrides:

   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, as per our recommendations.

Documentation Site Map

• Getting Started
• Contributing
• Tools Design System Introduction
• Shareable non-Design System Components Introduction
• Design Tokens
• Architecture Decision Records
• Changelog
• Vision