open-index/open-npm huggingface dataset:
npm package: @guardian/source
Description: <img src="https://github.com/guardian/csnx/blob/main/libs/@guardian/source/assets/logo.png?raw=true" height="320" width="620" >
Latest version: 12.2.1

# `@guardian/source`

<img src="https://github.com/guardian/csnx/blob/main/libs/@guardian/source/assets/logo.png?raw=true" height="320" width="620" >

> An NPM package containing design foundations and robust, accessible React components from the Guardian's
> [Source Design System](https://theguardian.design).

[![npm](https://img.shields.io/npm/v/@guardian/source)](https://www.npmjs.com/package/@guardian/source)
<a href="https://guardian.github.io/storybooks" target="_blank"><img src="https://raw.githubusercontent.com/storybooks/brand/master/badge/badge-storybook.svg"></a>

## Install

```sh
$ pnpm add @guardian/source
```

or

```sh
$ yarn add @guardian/source
```

or

```sh
$ npm install @guardian/source
```

> [!NOTE]
> Use of the React components will require [@emotion/react](https://emotion.sh/docs/introduction#react)

## Usage

_Full documentation is available in the [Source storybook](https://guardian.github.io/storybooks)._

### `foundations`

Source design foundations (e.g. colour, spacing, typography etc) can be imported from the `foundations` subpath:

```js
import { palette } from '@guardian/source/foundations`
```

### `react-components`

A set of robust, accessible, React components can be imported from the `react-components` subpath:

```js
import { Button } from '@guardian/source/react-components`
```

## Contributing

We welcome contributions to Source! See our [contributing](../../../docs/source/contributing.md) and [Storybook](../../../docs/source/storybook.md) docs for more info.
npm package: @guardian/source-foundations
Description: [![npm](https://img.shields.io/npm/v/@guardian/source-foundations)](https://www.npmjs.com/package/@guardian/source-foundations)
Latest version: 16.0.0
Deprecated: Use @guardian/source instead

# `@guardian/source-foundations`

[![npm](https://img.shields.io/npm/v/@guardian/source-foundations)](https://www.npmjs.com/package/@guardian/source-foundations)

The atoms from which all our visual design is built. They may be used with any CSS-in-JS library.

This package is part of the [Source design system](/docs/source/README.md).

## Install

Foundations are installed as a JavaScript package via Yarn:

```sh
$ yarn add @guardian/source-foundations
```

or:

```sh
$ npm install @guardian/source-foundations
```

## Colours

Guardian colours can be found in the [`palette` documentation](https://guardian.github.io/csnx/?path=/docs/source-foundations_palette--palette).

## Space

Our [space](https://guardian.github.io/csnx/?path=/docs/source-foundations_space--page) system is structured as increments of 4px.

```js
import { space } from '@guardian/source-foundations';

const spaceAfter = css`
	margin-bottom: ${space[3]}px;
`;

// margin-bottom: 12px;
```

## Size

[Size](https://guardian.github.io/csnx/?path=/docs/source-foundations_size--page) units may be used to set the height, max-height, width or max-width of a component.

```js
import { width, height } from '@guardian/source-foundations';

const checkbox = css`
	width: ${width.inputXsmall}px;
	height: ${height.inputXsmall}px;
`;

// width: 24px;
// height: 24px;
```

## Typography

[Typography](https://guardian.github.io/csnx/?path=/docs/source-foundations_typography--headline) is expressed as methods that return snippets of CSS depending on the desired font family and size.

```js
import { headline } from '@guardian/source-foundations';

const h1 = css`
	${headline.medium()};
`;

// font-family: GH Guardian Headline, Georgia, serif;
// font-size: 2.13rem;
```

## Media queries

We provide [media queries](https://guardian.github.io/csnx/?path=/docs/source-foundations_media-queries--page) for each breakpoint in our grid layout.

```js
import { from, until, between } from '@guardian/source-foundations';

const styles = css`
	padding: 0 10px;

	${from.mobileLandscape} {
		padding: 0 20px;
	}

	${between.phablet.and.desktop} {
		padding: 0 32px;
	}

	${until.wide} {
		padding: 0 40px;
	}
`;

// padding: 0 10px;
// @media (min-width: 480px) {
//   padding: 0 20px;
// }
// @media (min-width: 660px) and (max-width: 979px) {
//   padding: 0 32px;
// }
// @media (max-width: 1300px) {
//   padding: 0 40px;
// }
```
npm package: @guardian/src-brand
Description: 📣 For more context and visual guides relating to brand usage, visit the [Source Design System website](https://theguardian.design/2a1e5182b/p/8909e0-assets)
Latest version: 3.12.1
Deprecated: This package has been replaced by @guardian/source-react-components.

# Brand

📣 For more context and visual guides relating to brand usage, visit the [Source Design System website](https://theguardian.design/2a1e5182b/p/8909e0-assets)

## Install

```sh
$ yarn add @guardian/src-brand
```

## Example

Our brand SVGs are exported as React components.

```tsx
import { SvgGuardianLogo } from '@guardian/src-brand';

React.render(<SvgGuardianLogo />, rootElement);
```

## Use

### API

See [storybook](https://guardian.github.io/source/?path=/docs/source-src-brand).

### How to use

For context and visual guides relating to usage see the [Source Design System website](https://theguardian.design/2a1e5182b/p/8909e0-assets).
npm package: @guardian/src-button
Description: 📣 For more context and visual guides relating to button usage, visit the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/435225-button/)
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# Buttons

📣 For more context and visual guides relating to button usage, visit the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/435225-button/)

## Install

```sh
$ yarn add @guardian/src-button
```

## Use

### API

See [storybook](https://guardian.github.io/source/?path=/docs/source-src-button-button--playground).

### How to use

For context and visual guides relating to button usage see the [Source Design System website](https://theguardian.design/2a1e5182b/p/435225-button).

## Supported themes

### Standard

-   `default`
-   `brand`
-   `brandAlt`

### Custom

-   `readerRevenue`
-   `readerRevenueBrand`
-   `readerRevenueBrandAlt`
npm package: @guardian/src-checkbox
Description: ## Install
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# Checkbox

## Install

```sh
$ yarn add @guardian/src-checkbox
```

## Use

### API

See [storybook](https://guardian.github.io/source/?path=/docs/source-src-checkbox-checkbox--playground).

### How to use

📣 For more context and visual guides relating to checkbox usage on the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/466fad-checkbox/b/33fc2f)

## Supported themes

### Standard

-   `default`
-   `brand`
npm package: @guardian/src-choice-card
Description: ## Install
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# `@guardian/src-choice-card`

## Install

```sh
$ yarn add @guardian/src-choice-card
```

## Use

### API

See [storybook](https://guardian.github.io/source/?path=/docs/source-src-choice-card-choicecardgroup).

### How to use

For context and visual guides for Choice Cards see the [Source Design System website](https://theguardian.design/2a1e5182b/p/65ffe9-choice-card).
npm package: @guardian/src-ed-button
Description: This is the editorial version of the core `Button` coomponent. This editorial version requires the `format` prop and uses that to override `Button` styles based on `format.theme`
Latest version: 3.9.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Button

This is the editorial version of the core `Button` coomponent. This editorial version
requires the `format` prop and uses that to override `Button` styles based on
`format.theme`

Also exported is `LinkButton` which, like in core, offers a href version of the buttom

## Install

```sh
$ yarn add @guardian/src-ed-button @guardian/src-foundations
```

or

```sh
$ npm i @guardian/src-ed-button @guardian/src-foundations
```

## Use

```jsx
import { Button } from '@guardian/src-ed-button';

const SomeButtons = () => (
    <Button
        priority="primay"
        onClick={() => {}}
        format={{
            display: Display.Standard,
            design: Design.Article,
            theme: Pillar.News,
        }}
    >
        Click me
    </Button>
    <LinkButton
        priority="subdued"
        size="small"
        href="https://www.theguardian.com/uk"
        format={{
            display: Display.Standard,
            design: Design.Article,
            theme: Special.Labs,
        }}
    >
        Click me too
    </LinkButton>
);
```

## `Button` Props

In addition to all the standard `Button` and `LinkButton` props, we also have

### `format`

See **`@guardian/types`**: https://github.com/guardian/types/blob/main/src/format.ts

Which is what we use to decide the editorial styling overrides
npm package: @guardian/src-ed-lines
Description: 📣 For more context and visual guides relating to lines usage, visit the [Source Design System website](https://www.theguardian.design)
Latest version: 3.9.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Lines

📣 For more context and visual guides relating to lines usage, visit the [Source Design System website](https://www.theguardian.design)

## Install

```sh
$ yarn add @guardian/src-ed-lines @guardian/src-foundations
```

or

```sh
$ npm i @guardian/src-ed-lines @guardian/src-foundations
```

## Use

```jsx
import { Lines } from '@guardian/src-ed-lines';

const Section = () => (
    <>
        <Lines count={8} />
        <Lines effect="squiggly" />
        <Lines count={4} effect="dotted" colour="blue" />
    </>
);
```

## `Lines` Props

### `effect`

**`"straight" | "squiggly" | "dotted" | "dashed"`** _= "straight"_

The appearance of the lines.

### `count`

**`1 | 4 | 8`** _= 4_

How many lines appear.

### `color`

**`string`** _= line.primary_

The colour of the lines
npm package: @guardian/src-ed-logo
Description: The Guardian logo appears in the header on most editorial pages
Latest version: 3.9.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# QuoteIcon

The Guardian logo appears in the header on most editorial pages

## Install

```sh
$ yarn add @guardian/src-ed-logo
```

or

```sh
$ npm i @guardian/src-ed-logo
```

## Use

```jsx
import { Logo } from '@guardian/src-ed-logo';

const Header = () => {
    return (
        <header css={headerStyles}>
            <p>Some other header things</p>
            <Logo />
        </header>
    );
};
```

## `Logo` Props

### `logoType`

**`"standard" | "anniversary" | "bestWebsite"`**

The type of logo to return
npm package: @guardian/src-ed-quote-icon
Description: The Guardian quote icon is used in kickers, headlines, drop caps and pull quotes to denote quoted text.
Latest version: 3.9.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# QuoteIcon

The Guardian quote icon is used in kickers, headlines, drop caps and pull quotes to denote quoted text.

## Install

```sh
$ yarn add @guardian/src-ed-quote-icon
```

or

```sh
$ npm i @guardian/src-ed-quote-icon
```

## Use

```jsx
import { QuoteIcon } from '@guardian/src-ed-quote-icon';

const Section = () => (
    <>
        <QuoteIcon
            size="medium"
            format={{
                display: Display.Standard,
                design: Design.Article,
                theme: Pillar.News,
            }}
        />
        <blockquote>I said this</blockquote>
    </>
);
```

## `QuoteIcon` Props

### `size`

**`"xsmall" | "small" | "medium" | "large"`**

The size of the quote.

### `format`

See **`@guardian/types`**: https://github.com/guardian/types/blob/main/src/format.ts

What we use to decide the editorial colour for the quotes
npm package: @guardian/src-ed-star-rating
Description: Displays a rating, 1-5, using star SVGs. See the accompanying stories for visual examples.
Latest version: 3.9.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# StarRating

Displays a rating, 1-5, using star SVGs. See the accompanying stories for visual examples.

📣 For more context and visual guides relating to `StarRating` usage, visit the [Source Design System website](https://www.theguardian.design).

## Use

```tsx
import { StarRating } from '@guardian/editorial';

const ReviewPage = () => (
    <article>
        <h1>Review Of A Film</h1>
        <StarRating
            rating={3}
            size="medium"
        />
        <p>Reasons why this film is 3 stars.</p>
    </article>
);
```

## `StarRating` Props

### `rating`

**`number`**

The rating itself - expected to be `1`, `2`, `3`, `4` or `5`.

### `size`

**`"large" | "medium" | "small"`**

Determines how large the stars are. See the accompanying stories for visual examples.
npm package: @guardian/src-footer
Description: 📣 For more context and visual guides relating to `Footer` usage on the [Source Design System website](https://www.theguardian.design)
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# `Footer`

📣 For more context and visual guides relating to `Footer` usage on the [Source Design System website](https://www.theguardian.design)

## Install

```sh
$ yarn add @guardian/src-footer
```

## Use

### API

See [storybook](https://guardian.github.io/source/?path=/docs/source-src-footer-footer--playground).

### How to use

For context and visual guides relating to footer usage see the [Source Design System website](https://theguardian.design/2a1e5182b/p/12ce79--footer/b/09ee0e).

## Supported themes

### Standard

-   `brand`
npm package: @guardian/src-foundations
Description: The Guardian's foundations are the atoms from which all our visual design is built. They are intended for use with a CSS-in-JS library such as Emotion.
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-foundations.

# Foundations

The Guardian's foundations are the atoms from which all our visual design is built. They are intended for use with a CSS-in-JS library such as Emotion.

## Install

```sh
$ yarn add @guardian/src-foundations
```

## Use

### [Palette](https://www.theguardian.design/2a1e5182b/p/28d868-overview)

```ts
import { background } from '@guardian/src-foundations/palette';

const backgroundColor = css`
    background-color: ${background.primary};
`;
```

### [Typography](https://www.theguardian.design/2a1e5182b/p/930d69-typography/b/78d0d9)

```ts
import { headline, body, textSans } from '@guardian/src-foundations/typography';

const h1 = css`
    ${headline.large({ fontWeight: 'bold' })};
`;

const p = css`
    ${body.main()};
`;

const copyright = css`
    ${textSans.xsmall()};
`;
```

### Media queries

```ts
import { from, until, between } from '@guardian/src-foundations/mq';

const styles = css`
    padding: 0 10px;

    ${from.mobileLandscape} {
        padding: 0 20px;
    }

    ${between.phablet.and.desktop} {
        padding: 0 32px;
    }

    ${until.wide} {
        padding: 0 40px;
    }
`;
```

### [Size](https://www.theguardian.design/2a1e5182b/p/38d9a9-overview)

```ts
import { width, height } from '@guardian/src-foundations/size';

const checkbox = css`
    width: ${width.inputXsmall}px;
    height: ${height.inputXsmall}px;
`;
```

### [Visually Hidden](https://www.theguardian.design/2a1e5182b/p/6691bb-accessibility/t/1285a8)

For elements that should not appear to sighted users, but are useful to assistive technology users.

```ts
import { visuallyHidden } from '@guardian/src-foundations/accessibility';

const label = css`
    ${visuallyHidden};
`;
```

### [Focus Halo](https://www.theguardian.design/2a1e5182b/p/6691bb-accessibility/t/24562a)

This mixin provides a [clear focus state](https://theguardian.design/2a1e5182b/p/08dc26-interaction-states/t/314e46) for elements that may receive keyboard focus.

```ts
import { focusHalo } from '@guardian/src-foundations/accessibility';

const input = css`
    ${focusHalo};
    width: 200px;
    height: 44px;
`;
```

### [Description Id](https://theguardian.design/2a1e5182b/p/6691bb-accessibility/t/062b61)

A function that takes the ID of an element and generates a new ID. This should be set as the
ID of an element that describes the first element. The generated ID should also be passed to
the [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute) attribute on the first element.

```tsx
import { descriptionId } from '@guardian/src-foundations/accessibility';

const Form = () => {
    const id = 'first_name';
    return (
        <form>
            <input id={id} type="text" aria-describedby={descriptionId(id)} />
            <p class="error" id={descriptionId(id)} />
        </form>
    );
};
```
npm package: @guardian/src-grid
Description: 📣 For more context and visual guides relating grid usage on the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/978527--grid-component/b/304251)
Latest version: 2.8.2
Deprecated: This package has been replaced by @guardian/source-react-components.

# Grid

📣 For more context and visual guides relating grid usage on the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/978527--grid-component/b/304251)

## Install

```sh
$ yarn add @guardian/src-grid
```

## Use

```js
import { GridRow, GridItem } from "@guardian/src-grid"

const Article = () => (
    <GridRow breakpoints={["mobile", "tablet", "desktop", "leftCol", "wide"]}>
        <GridItem span={[0, 3, 3, 4, 4]} borderRight={true}>
            <Sidebar />
        </GridItem>
        <GridItem span={[4, 9, 9, 10, 12]}>
            <Main />
        </GridItem>
    </GridRow>
)
```

## `GridRow` Props

### `breakpoints`

**`Array<GridBreakpoint | CustomBreakpoint>`** _= ["mobile", "tablet", "desktop", "leftCol", "wide"]_

A list of breakpoints at which grid column span may change. GridRow currently
supports changes at `"mobile"`, `"tablet"`, `"desktop"`, `"leftCol"` and `"wide"` breakpoints.
Any of these may be omitted.

For best results, breakpoints should be ordered ascending by minimum viewport width.

A custom breakpoint may be specified, which must have the following properties:

-   `width`: the minimum viewport width at which the breakpoint becomes active. This will also
    be the width of the `GridRow` container
-   `columns`: the number of columns the grid should comprise

## `GridItem` Props

### `span`

**`number[]`**

The number of columns a grid item should span. Corresponds to the `breakpoints` list
in `GridRow` props.

When a col span of 0 is specified for a particular breakpoint, the grid item will have
`display: none` applied to it.

### `borderRight`

**`boolean`**_= false_

Whether a border should appear to the right of the grid item.
npm package: @guardian/src-icons
Description: 📣 For more context and visual guides relating to icon usage, visit the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/74a822-overview)
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# Icons

📣 For more context and visual guides relating to icon usage, visit the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/74a822-overview)

## Install

```sh
$ yarn add @guardian/src-icons
```

## Use

Our icon SVGs are exported as React components.

```tsx
import { SvgCheckmark } from '@guardian/src-icons';

React.render(<SvgCheckmark />, rootElement);
```

## SVGs

The `svgs` directory contains the equivalent svg files for each of the icons. Mostly these are pulled in from Figma using the [get-icons script](../../../scripts/get-icons), with a few notable [exceptions](../../../scripts/get-icons#exceptions).
npm package: @guardian/src-inline-error
Description: **:warning: Deprecation warning: This package has been replaced by [`@guardian/src-user-feedback`](https://github.com/guardian/source/tree/main/src/core/components/user-feedback)**
Latest version: 2.8.2
Deprecated: This package has been replaced by @guardian/source-react-components.

# Inline Error

**:warning: Deprecation warning: This package has been replaced by [`@guardian/src-user-feedback`](https://github.com/guardian/source/tree/main/src/core/components/user-feedback)**

📣 For more context and visual guides relating to user feedback, visit the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/108ed3--user-feedback/b/3803b4)
npm package: @guardian/src-label
Description: 📣 For more context and visual guides relating to `Label` usage on the [Source Design System website](https://www.theguardian.design)
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# `Label`

📣 For more context and visual guides relating to `Label` usage on the [Source Design System website](https://www.theguardian.design)

## Install

```sh
$ yarn add @guardian/src-label
```

## Use

### API

See [storybook](https://guardian.github.io/source/?path=/docs/source-src-label-label-).

### How to use

For context and visual guides relating to label usage see the [Source Design System website](https://theguardian.design/2a1e5182b/p/40151e-label/b/86af7d).

## Supported themes

### Standard

-   `light`
-   `brand`
npm package: @guardian/src-link
Description: 📣 For more context and visual guides relating to link usage, visit the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/43c26b-link/)
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# Link

📣 For more context and visual guides relating to link usage, visit the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/43c26b-link/)

## Install

```sh
$ yarn add @guardian/src-link
```

## Usage

### API

See [storybook](https://guardian.github.io/source/?path=/docs/source-src-link-link--demo)

### How to use

For context and visual guides relating to usage see the [Source Design System website](https://theguardian.design/2a1e5182b/p/43c26b-link/b/048fd1).

## Supported themes

### Standard

-   `light`
-   `brand`
-   `brandYellow`
npm package: @guardian/src-select
Description: 📣 For more context and visual guides relating to select box usage on the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/663879-select-box)
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# Select box

📣 For more context and visual guides relating to select box usage on the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/663879-select-box)

## Install

```sh
$ yarn add @guardian/src-select
```

## Use

### API

See [storybook](https://guardian.github.io/source/?path=/docs/source-src-select-select--demo)

### How to use

For context and visual guides relating to usage see the [Source Design System website](https://theguardian.design/2a1e5182b/p/663879-select-box/b/10875c).

## Supported themes

### Standard

-   `light`
npm package: @guardian/src-svgs
Description: **:warning: Deprecation warning: This package has been replaced by [`@guardian/src-icons`](https://github.com/guardian/source/tree/main/src/core/icons)**
Latest version: 2.8.2
Deprecated: This package has been replaced by @guardian/source-react-components.

# SVGs

**:warning: Deprecation warning: This package has been replaced by [`@guardian/src-icons`](https://github.com/guardian/source/tree/main/src/core/icons)**

📣 For more context and visual guides relating to icon usage, visit the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/74a822-overview)
npm package: @guardian/src-text-area
Description: 📣 For more context and visual guides relating text area usage on the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/77ee17-overview)
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# TextArea

📣 For more context and visual guides relating text area usage on the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/77ee17-overview)

## Install

```sh
$ yarn add @guardian/src-text-area
```

## Use

### API

See [storybook](https://guardian.github.io/source/?path=/docs/source-src-text-area-text-area--demo)

### How to use

For context and visual guides relating to usage see the [Source Design System website](https://theguardian.design/2a1e5182b/p/567182-text-area/b/42916b).

## Supported themes

### Standard

-   `light`
npm package: @guardian/src-user-feedback
Description: 📣 For more context and visual guides relating to user feedback usage on the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/108ed3--user-feedback/b/3803b4)
Latest version: 3.13.0
Deprecated: This package has been replaced by @guardian/source-react-components.

# User feedback

📣 For more context and visual guides relating to user feedback usage on the [Source Design System website](https://www.theguardian.design/2a1e5182b/p/108ed3--user-feedback/b/3803b4)

## Install

```sh
$ yarn add @guardian/src-user-feedback
```

## Usage

### API

See [storybook](https://guardian.github.io/source/?path=/docs/source-src-user-feedback-inlineerror--playground)

### How to use

For context and visual guides relating to usage see the [Source Design System website](https://theguardian.design/2a1e5182b/p/108ed3-user-feedback/b/3803b4).

## Supported themes

-   `default`
-   `brand`