+);
diff --git a/libs/@guardian/source-foundations/src/typography/typography.stories.mdx b/libs/@guardian/source-foundations/src/typography/typography.stories.mdx
index a4d1843bd..584f21aec 100644
--- a/libs/@guardian/source-foundations/src/typography/typography.stories.mdx
+++ b/libs/@guardian/source-foundations/src/typography/typography.stories.mdx
@@ -1,16 +1,5 @@
import { Meta, Canvas, Story } from '@storybook/addon-docs';
-import {
- headlineObjectStyles,
- bodyObjectStyles,
- textSansObjectStyles,
- titlepieceObjectStyles,
-} from '@guardian/source-foundations';
-import {
- FontStylesRenderer,
- LineHeightRenderer,
- FontWeightRenderer,
- ItalicsRenderer,
-} from './storybookTypographyRenderers';
+import { TypographyPresets } from './storybookTypographyPresets';
-
-
-
-
+The Guardian has four bespoke typefaces, which were created for different
+purposes. When used effectively, they create contrast and alter the tone in
+which text is read.
-#### Line height
+### Where do we use web typography presets?
-The default for headline is `tight`. This maps to `1.15 (115%)`.
+Any content in a web browser or a webview in the app uses web typography
+presets.
-
+- _Browser_ — All [theguardian.com](https://www.theguardian.com) content
+ (front and article pages) and supporter revenue pages.
+- _App webview_ — Article pages, sign-in and registration pages
-### Body
+#### Guardian Headline
-```css
-font-family: 'GuardianTextEgyptian, Guardian Text Egyptian Web, Georgia, serif';
-```
+Use for headlines, headings and any short form text like pull quotes, bylines
+and titles.
-
+#### Kicker — Guardian Headline
-#### Line height
+Use for a kicker in the fronts card.
-The default for body is `loose`. This maps to `1.40 (140%)`.
+#### Guardian Text Sans
-This meets the [WCAG 2.1 AAA success criterion for visual presentation](https://www.w3.org/TR/WCAG21/#visual-presentation).
+Use for interactive page elements like buttons and text input fields and for
+meta information like datelines, image captions and data visualisations.
-
+_Note:_ Text Sans is used across the board on paid content templates to help
+differentiate from editorial content.
-### Text sans
-
-```css
-font-family: 'GuardianTextSans, Guardian Text Sans Web, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif';
-```
-
-
-
-#### Line height
-
-The default for text-sans is `regular`. This maps to `1.3 (130%)`.
-
-
-
-### Titlepiece
-
-```css
-font-family: 'GT Guardian Titlepiece, Georgia, serif';
-```
-
-
-
-#### Line height
-
-The default for titlepiece is `tight`. This maps to `1.15 (115%)`.
-
-
-
-### Options
-
-Each method may receive an `options` object. Missing options are merged with sensible defaults for each font family.
-
-#### Line height
-
-The available options for line height are documented in the table below.
-
-
-
-
Alias in Source
-
Line height
-
-
-
loose
-
140% (1.4)
-
-
-
regular
-
130% (1.30)
-
-
-
tight
-
115% (1.15)
-
-
-
-We calculate the final line height based on the font size using the following formula:
-
-```ts
-// line-height is defined as a unitless value, so we multiply
-// by the element's font-size in px to get the px value
-const finalLineHeight = `${lineHeight * fontSizeInPx}px`;
-```
+#### Guardian Titlepiece
-And a worked example:
-
-```ts
-const lineHeight =
- 1.15 * // line-height: tight (unitless)
- 30; // font-size: small (px)
-
-// lineHeight === 34.5px
-```
-
-#### Font weight
-
-```tsx
-headline.medium({ fontWeight: 'bold' });
-```
-
-
-
-The default for body and textSans is `regular`. The `light` and `medium` font weights are not available for these fonts.
-
-The default for headline is `medium`. The `regular` font-weight is not available for this font.
-
-The default and only font-weight for titlepiece is `bold`.
-
-#### Font style
-
-```tsx
-headline.medium({ fontStyle: 'italic' });
-```
-
-`normal` (default) is available for all fonts.
-
-`italic` is available for the following fonts:
-
-
-
-#### Unit
-
-```tsx
-headline.medium({ unit: 'px' });
-```
+Use for impact. Ideal for marketing messages, page headers and numerals. Use
+sparingly and at large sizes only.
-Specifies units for the font-size and line-height values.
+_Note:_ this font is not available on [theguardian.com](https://theguardian.com)
-By default, font-size is expressed in `rem`, and line-height is expressed as a [unitless value](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height#values).
+### Specimen
-You can override this behaviour by setting the `unit` option to `px`. As a result, both font-size and line-height will be expressed in `px` values.
+
+
+
diff --git a/libs/@guardian/source-foundations/src/typography/typographyDeprecated.stories.mdx b/libs/@guardian/source-foundations/src/typography/typographyDeprecated.stories.mdx
new file mode 100644
index 000000000..e22303855
--- /dev/null
+++ b/libs/@guardian/source-foundations/src/typography/typographyDeprecated.stories.mdx
@@ -0,0 +1,255 @@
+import { Meta, Canvas, Story } from '@storybook/addon-docs';
+import {
+ headlineObjectStyles,
+ bodyObjectStyles,
+ textSansObjectStyles,
+ titlepieceObjectStyles,
+} from '@guardian/source-foundations';
+import {
+ FontStylesRenderer,
+ LineHeightRenderer,
+ FontWeightRenderer,
+ ItalicsRenderer,
+} from './storybookTypographyRenderers';
+
+
+
+# Typography API (deprecated)
+
+_Note:_ the typography API is deprecated and will be removed in a future
+release. Please use the typography presets in all new code.
+
+Typographic choices affect how textual content is interpreted; influencing tone,
+hierarchy and legibility.
+
+## Example
+
+```tsx
+import { headline, body, textSans } from '@guardian/source-foundations';
+
+const h1 = css`
+ ${headline.large()};
+`;
+
+const p = css`
+ ${body.medium()};
+`;
+
+const copyright = css`
+ ${textSans.xsmall()};
+`;
+```
+
+You can also use the [object style syntax](https://emotion.sh/docs/object-styles):
+
+```tsx
+import { headlineObjectStyles } from '@guardian/source-foundations';
+
+const h1 = {
+ ...headlineObjectStyles.large(),
+};
+```
+
+## Where can I find The Guardian's fonts?
+
+The canonical source of fonts is https://github.com/guardian/fonts
+
+They should be loaded from the locations specified in [font-faces.css](https://github.com/guardian/fonts/blob/main/fonts/web/font-faces.css). This optimises for consistency and performance across The Guardian's digital products.
+
+## API
+
+Each font family has an associated import, exposing methods that return snippets
+of CSS depending on the desired font size.
+
+A range of font sizes are available for each font family. The `medium` font size
+should be considered the default.
+
+Pixel values are given below for ease of understanding. By default the
+typography API assigns font size in rems.
+
+### Headline
+
+```css
+font-family: 'GH Guardian Headline, Guardian Egyptian Web, Georgia, serif';
+```
+
+
+
+#### Line height
+
+The default for headline is `tight`. This maps to `1.15 (115%)`.
+
+
+
+### Body
+
+```css
+font-family: 'GuardianTextEgyptian, Guardian Text Egyptian Web, Georgia, serif';
+```
+
+
+
+#### Line height
+
+The default for body is `loose`. This maps to `1.40 (140%)`.
+
+This meets the [WCAG 2.1 AAA success criterion for visual presentation](https://www.w3.org/TR/WCAG21/#visual-presentation).
+
+
+
+### Text sans
+
+```css
+font-family: 'GuardianTextSans, Guardian Text Sans Web, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif';
+```
+
+
+
+#### Line height
+
+The default for text-sans is `regular`. This maps to `1.3 (130%)`.
+
+
+
+### Titlepiece
+
+```css
+font-family: 'GT Guardian Titlepiece, Georgia, serif';
+```
+
+
+
+#### Line height
+
+The default for titlepiece is `tight`. This maps to `1.15 (115%)`.
+
+
+
+### Options
+
+Each method may receive an `options` object. Missing options are merged with sensible defaults for each font family.
+
+#### Line height
+
+The available options for line height are documented in the table below.
+
+
+
+
Alias in Source
+
Line height
+
+
+
loose
+
140% (1.4)
+
+
+
regular
+
130% (1.30)
+
+
+
tight
+
115% (1.15)
+
+
+
+We calculate the final line height based on the font size using the following formula:
+
+```ts
+// line-height is defined as a unitless value, so we multiply
+// by the element's font-size in px to get the px value
+const finalLineHeight = `${lineHeight * fontSizeInPx}px`;
+```
+
+And a worked example:
+
+```ts
+const lineHeight =
+ 1.15 * // line-height: tight (unitless)
+ 30; // font-size: small (px)
+
+// lineHeight === 34.5px
+```
+
+#### Font weight
+
+```tsx
+headline.medium({ fontWeight: 'bold' });
+```
+
+
+
+The default for body and textSans is `regular`. The `light` and `medium` font weights are not available for these fonts.
+
+The default for headline is `medium`. The `regular` font-weight is not available for this font.
+
+The default and only font-weight for titlepiece is `bold`.
+
+#### Font style
+
+```tsx
+headline.medium({ fontStyle: 'italic' });
+```
+
+`normal` (default) is available for all fonts.
+
+`italic` is available for the following fonts:
+
+
+
+#### Unit
+
+```tsx
+headline.medium({ unit: 'px' });
+```
+
+Specifies units for the font-size and line-height values.
+
+By default, font-size is expressed in `rem`, and line-height is expressed as a [unitless value](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height#values).
+
+You can override this behaviour by setting the `unit` option to `px`. As a result, both font-size and line-height will be expressed in `px` values.
diff --git a/libs/@guardian/source-foundations/src/utils/convert-value.test.ts b/libs/@guardian/source-foundations/src/utils/convert-value.test.ts
index 099699487..b5c59ce0b 100644
--- a/libs/@guardian/source-foundations/src/utils/convert-value.test.ts
+++ b/libs/@guardian/source-foundations/src/utils/convert-value.test.ts
@@ -1,15 +1,15 @@
import {
fontArrayToString,
pxStringToNumber,
+ pxStringToRem,
pxToRem,
- rootPixelFontSize,
} from './convert-value';
describe('pxToRem', () => {
it('should calculate a rem equivalent of a pixel value', () => {
const value = 17;
const result = pxToRem(value);
- expect(result).toBe(value / rootPixelFontSize);
+ expect(result).toBe(1.0625);
});
});
@@ -22,6 +22,15 @@ describe('pxStringToNumber', () => {
});
});
+describe('pxStringToRem', () => {
+ it('should convert a value with a px unit to rem equivalent', () => {
+ const value = '20px';
+ const result = pxStringToRem(value);
+ expect(result).toBe(1.25);
+ expect(typeof result).toBe('number');
+ });
+});
+
describe('fontArrayToString', () => {
it('should convert an array of font names to a valid `font-family` value', () => {
const value = ['GuardianTextEgyptian', 'Georgia', 'serif'];
diff --git a/libs/@guardian/source-foundations/src/utils/convert-value.ts b/libs/@guardian/source-foundations/src/utils/convert-value.ts
index c836fc87a..f581a503f 100644
--- a/libs/@guardian/source-foundations/src/utils/convert-value.ts
+++ b/libs/@guardian/source-foundations/src/utils/convert-value.ts
@@ -1,5 +1,7 @@
export const rootPixelFontSize = 16;
export const pxToRem = (px: number): number => px / rootPixelFontSize;
export const pxStringToNumber = (px: string): number => Number(px.slice(0, -2));
+export const pxStringToRem = (px: string): number =>
+ pxToRem(pxStringToNumber(px));
export const fontArrayToString = (fonts: readonly string[]): string =>
fonts.map((name) => (name.includes(' ') ? `"${name}"` : name)).join(', ');
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a21eb180a..481b7331b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -608,6 +608,9 @@ importers:
tslib:
specifier: 2.6.2
version: 2.6.2
+ tsx:
+ specifier: ^4.7.1
+ version: 4.7.1
typescript:
specifier: 5.3.3
version: 5.3.3
@@ -17342,6 +17345,17 @@ packages:
typescript: 5.3.3
dev: true
+ /tsx@4.7.1:
+ resolution: {integrity: sha512-8d6VuibXHtlN5E3zFkgY8u4DX7Y3Z27zvvPKVmLon/D4AjuKzarkUBTLDBgj9iTQ0hg5xM7c/mYiRVM+HETf0g==}
+ engines: {node: '>=18.0.0'}
+ hasBin: true
+ dependencies:
+ esbuild: 0.19.12
+ get-tsconfig: 4.7.2
+ optionalDependencies:
+ fsevents: 2.3.3
+ dev: true
+
/tty-table@4.1.6:
resolution: {integrity: sha512-kRj5CBzOrakV4VRRY5kUWbNYvo/FpOsz65DzI5op9P+cHov3+IqPbo1JE1ZnQGkHdZgNFDsrEjrfqqy/Ply9fw==}
engines: {node: '>=8.0.0'}