npm package: @highlight-ui/typography
Description: This is the Typography package used by UI-components in Personio
Author: Personio GmbH & Co. KG
Latest version: 6.3.8

[![npm](https://img.shields.io/npm/v/@highlight-ui/typography)](https://www.npmjs.com/package/@highlight-ui/typography)
[![personio.design](https://img.shields.io/static/v1?label=Personio&message=zeroheight&color=yellow)](https://www.personio.design/40d648a47/p/23fb8c-typography/b/94d94d)
[![storybook.personio.design](https://img.shields.io/static/v1?label=Personio&message=storybook&color=red)](https://storybook.personio.design/?path=/story/elements-typography)

# @highlight-ui/typography

The Typography components which manage the usage of typographic design tokens through props.

## Features

- Polymorphic component
- Support text color tokens
- Supports truncation
- Supports components that Pre-combines `fontFamily`, `fontSize`, `fontWeight`, `letterSpacing`, `lineHeight`, `textTransform`, and `textDecoration`
  - Heading: offers variants in choice of `2xlarge`, `xlarge`, `large`, `medium`, `small` and `xsmall` which are identical with the Figma assets.
  - Body: Body component offers variants in choice of `large`, `base`, `small`, `strong-large`, `strong-base` and `strong-small` which are identical with the Figma assets.

## Installation

Using npm:

```bash
npm install @highlight-ui/typography
```

Using yarn:

```bash
yarn add @highlight-ui/typography
```

Using pnpm:

```bash
pnpm add @highlight-ui/typography
```

In your (S)CSS file:

```scss
@import url('@highlight-ui/typography');
```

Once the package is installed, you can import the library:

```typescript
import { Body, Heading } from '@highlight-ui/typography';
```

## Usage

### Typography (_Deprecated_)🗑️

```tsx
import React from 'react';
import { Typography } from '@highlight-ui/typography';

export default function Example() {
  return <Typography>Text</Typography>;
}
```

### Heading component

```tsx
import React from 'react';
import { Heading } from '@highlight-ui/typography';

export default function Example() {
  return (
    <Heading as="h2" variant="xlarge" color="text-default">
      some large heading
    </Heading>
  );
}
```

### Body component

```tsx
import React from 'react';
import { Body } from '@highlight-ui/typography';

export default function Example() {
  return (
    <Body variant="large" color="text-default">
      some large text
    </Body>
  );
}
```

## Advanced usage

### Changing the rendered HTML tag

By default, the `<Body />` component renders a `span` element, whereas the `<Heading />` component has no default (refer to the [props table](#props-) below). To change the HTML tag that will be used for rendering, the `as` prop can be used to specify any other HTML tag.

```tsx
import React from 'react';
import { Body } from '@highlight-ui/typography';

export default function Example() {
  return (
    <Body as="p" color="text-default">
      Text
    </Body>
  );
}
```

### Change typographic style through design tokens (_Deprecated_)🗑️

By default, the Typography component applies the `body-base` typography token. To override this default style, the `token` prop can be used to change the applied typographic style.

```tsx
import React from 'react';
import { Typography } from '@highlight-ui/typography';

export default function Example() {
  return <Typography token="heading-medium">Text</Typography>;
}
```

### Overriding font properties (_Deprecated_)🗑️

Individual font properties can be overriden through props such as `fontFamily`. Other properties that can be overriden are: `fontSize`, `fontWeight`, `letterSpacing`, `lineHeight`, `textTransform`, and `textDecoration`. For more details on these props, check out the component's [props table](#props-).

```tsx
import React from 'react';
import { Typography } from '@highlight-ui/typography';

export default function Example() {
  return <Typography fontFamily="mono">Text</Typography>;
}
```

### Customizing through a CSS class name (_Deprecated_)🗑️

Use the `className` prop to customize the component through CSS classes.

```tsx
import React from 'react';
import { Typography } from '@highlight-ui/typography';
import styles from './customStyles.scss';

export default function Example() {
  return <Typography className={styles.wrappedText}>Text</Typography>;
}
```

## Props 📜

### Heading

| Prop       | Type                                                      | Required | Default | Description                                                                                                                     |
| :--------- | :-------------------------------------------------------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------------------------ |
| `color`    | `TypographyColorToken`                                    | no       |         | Specifies a text color                                                                                                          |
| `as`       | `h1`,`h2`, `h3`, `h4`, `h5`, `h6`, `span`                 | yes      |         | Specifies an HTML tag for rendering the element                                                                                 |
| `variant`  | `2xlarge`, `xlarge`, `large`, `medium`, `small`, `xsmall` | yes      |         | Specifies a variant for rendering the element                                                                                   |
| `truncate` | `boolean`                                                 | no       | `false` | Whether to truncate the text                                                                                                    |
| `metadata` | `ComponentMetadata`                                       | no       |         | An object consisting of `testId` and `actionName` properties which will be mapped as HTML data attributes onto the root element |
| `id`       | `string`                                                  | no       |         | Specifies a unique id for the element                                                                                           |
| `title`    | `string`                                                  | no       |         | Specifies extra information about the element                                                                                   |

### Body

| Prop       | Type                                                                    | Required | Default | Description                                                                                                                     |
| :--------- | :---------------------------------------------------------------------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------------------------ |
| `color`    | `TypographyColorToken`                                                  | no       |         | Specifies a text color                                                                                                          |
| `as`       | `p`,`span`                                                              | no       | `span`  | Specifies an HTML tag for rendering the element                                                                                 |
| `variant`  | `large`, `base`, `small`, `strong-large`, `strong-base`, `strong-small` | no       | `base`  | Specifies a variant for rendering the element                                                                                   |
| `truncate` | `boolean`                                                               | no       | `false` | Whether to truncate the text                                                                                                    |
| metadata   | `ComponentMetadata`                                                     | no       |         | An object consisting of `testId` and `actionName` properties which will be mapped as HTML data attributes onto the root element |
| `id`       | `string`                                                                | no       |         | Specifies a unique id for the element                                                                                           |
| `title`    | `string`                                                                | no       |         | Specifies extra information about the element                                                                                   |

### Typography (_Deprecated_)🗑️

> Note: This component has been deprecated. Please migrate to the Heading and Body components.

| Prop             | Type                            | Required | Default       | Description                                     |
| :--------------- | :------------------------------ | :------- | :------------ | :---------------------------------------------- |
| `className`      | `string`                        | no       | `undefined`   | Allows providing a custom class name            |
| `component`      | `string`                        | no       | `'p'`         | Specifies an HTML tag for rendering the element |
| `token`          | `TypographyToken`               | no       | `'body-base'` | Specifies typography token                      |
| `color`          | `TypographyColorToken`          | no       | `undefined`   | Specifies a text color                          |
| `fontFamily`     | `TypographyFontFamilyToken`     | no       | `undefined`   | Specifies font family                           |
| `fontSize`       | `TypographyFontSizeToken`       | no       | `undefined`   | Specifies font size                             |
| `fontWeight`     | `TypographyFontWeightToken`     | no       | `undefined`   | Specifies font weight                           |
| `letterSpacing`  | `TypographyLetterSpacingToken`  | no       | `undefined`   | Specifies letter spacing                        |
| `lineHeight`     | `TypographyLineHeightToken`     | no       | `undefined`   | Specifies line height                           |
| `textTransform`  | `TypographyTextCaseToken`       | no       | `undefined`   | Specifies text case                             |
| `textDecoration` | `TypographyTextDecorationToken` | no       | `undefined`   | Specifies text decoration                       |

Also accepts props from the [React.HTMLAttributes\<HTMLElement\>](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/2d512539e20a785e8b5d6f6413ccd3b5e242cbd4/types/react/index.d.ts#L1860) type.

### Custom types 🔠

| Type                            | Values                                                                                                                                                                       | Description                        |
| :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------- |
| `TypographyToken`               | [Typography](https://www.personio.design/40d648a47/p/23fb8c-typography/b/94d94d) token names                                                                                 | Used for the `token` prop          |
| `TypographyColorToken`          | ["Text"](https://www.personio.design/40d648a47/p/489790-colours/t/26f115) and ["Text On"](https://www.personio.design/40d648a47/p/489790-colours/t/5797c9) color token names | Used for the `color` prop          |
| `TypographyFontFamilyToken`     | `'default' \| 'mono'`                                                                                                                                                        | Used for the `fontFamily` prop     |
| `TypographyFontSizeToken`       | `'small' \| 'base' \| 'large' \| 'xsmall' \| 'xlarge' \| '2xl' \| '3xl'`                                                                                                     | Used for the `fontSize` prop       |
| `TypographyFontWeightToken`     | `'bold' \| 'regular' \| 'semi-bold'`                                                                                                                                         | Used for the `fontWeight` prop     |
| `TypographyLetterSpacingToken`  | `'base'`                                                                                                                                                                     | Used for the `letterSpacing` prop  |
| `TypographyLineHeightToken`     | `'base' \| 'large' \| 'xlarge'`                                                                                                                                              | Used for the `lineHeight` prop     |
| `TypographyTextCaseToken`       | `'none' \| 'uppercase'`                                                                                                                                                      | Used for the `textTransform` prop  |
| `TypographyTextDecorationToken` | `'none' \| 'underline'`                                                                                                                                                      | Used for the `textDecoration` prop |

## Testing

```tsx
import React from 'react';
import { render } from '@testing-library/react';
import { Body } from '@highlight-ui/typography';

describe('TestExample', () => {
  it('test description', () => {
    render(<Body>Text</Body>);
    // write your expect here
  });
});
```

## Accessibility Considerations

These components should only be used to handle the styling of the text elements themselves. The spacing, alignment and semantics of the text elements should be managed by the parent. While doing this, it is important to consider the correct semantic page regions are being used such as `<aside>`, `<section>`, and `<nav>`.

Accessible usage of the Typography components relies on the following:

- Heading elements (e.g. `<h1>`, `<h2>`) are nested and used in a logical sequence.
- Only one `<h1>` (`as="h1"`) element per page.
- Don't skip heading levels.

## Place in design system 💻

The Typography component is being used in all of Highlight UI to display any kind of text element.

## Contributing 🖌️

If you're interested in contributing, please visit our [contribution page](https://www.personio.design/40d648a47/v/0/p/138faf-about-the-process).