From 715844d8a6db56a0f1bb9be9cfd14a6a43c258cd Mon Sep 17 00:00:00 2001
From: James Koster <james@jameskoster.co.uk>
Date: Thu, 10 Oct 2024 13:16:54 +0100
Subject: [PATCH] Add type tokens to storybook (#65993)

* Add type tokens to storybook

* Use tabs for spacing

* Apply suggestions from code review

Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com>

---------

Co-authored-by: jameskoster <jameskoster@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
---
 storybook/stories/tokens/typography.mdx | 178 ++++++++++++++++++++++++
 1 file changed, 178 insertions(+)
 create mode 100644 storybook/stories/tokens/typography.mdx

diff --git a/storybook/stories/tokens/typography.mdx b/storybook/stories/tokens/typography.mdx
new file mode 100644
index 0000000000000..c3b49b2865f18
--- /dev/null
+++ b/storybook/stories/tokens/typography.mdx
@@ -0,0 +1,178 @@
+import { Meta, Typeset } from '@storybook/addon-docs/blocks';
+
+<Meta title="Tokens/Typography" name="page" />
+ 
+export const typography = {
+	type: {
+		primary: '-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen-Sans,Ubuntu,Cantarell,"Helvetica Neue",sans-serif',
+	},
+	weight: {
+		regular: '400',
+		medium: '500',
+	},
+	size: {
+		s1: 11,
+		s2: 12,
+		s3: 13,
+		s4: 15,
+		s5: 20,
+		s6: 32,
+	},
+};
+ 
+export const SampleTextHeading = 'Code is Poetry.';
+export const SampleTextParagraph = 'WordPress grows when people like you tell their friends about it, and the thousands of businesses and services that are built on and around WordPress share that fact with their users.'
+ 
+# Typography tokens
+
+This document outlines the various tokens relating to typography in the WordPress components system.
+
+## Semantic tokens
+
+Semantic tokens compose primitive tokens to create reusable type styles enhancing consistency across the software.
+
+They are defined as SASS mixins and can be used like so:
+
+```css
+.my-component {
+	@include heading-large();
+}
+```
+
+### Headings
+
+<Typeset
+	fontSizes={[
+		Number(typography.size.s6),
+		Number(typography.size.s5),
+		Number(typography.size.s4),
+		Number(typography.size.s3),
+		Number(typography.size.s2),
+		Number(typography.size.s1),
+	]}
+	fontWeight={typography.weight.medium}
+	sampleText={SampleTextHeading}
+	fontFamily={typography.type.primary}
+/>
+
+<table>
+	<thead>
+		<tr>
+			<th>Style</th>
+			<th>Primitives</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr>
+			<td>heading-2x-large</td>
+			<td>`$font-family-headings`, `font-weight-medium`, `font-size-2x-large`, `line-height-2x-large`</td>
+		</tr>
+		<tr>
+			<td>heading-x-large</td>
+			<td>`$font-family-headings`, `font-weight-medium`, `font-size-x-large`, `line-height-medium`</td>
+		</tr>
+		<tr>
+			<td>heading-large</td>
+			<td>`$font-family-headings`, `font-weight-medium`, `font-size-large`, `line-height-small`</td>
+		</tr>
+		<tr>
+			<td>heading-medium</td>
+			<td>`$font-family-headings`, `font-weight-medium`, `font-size-medium`, `line-height-small`</td>
+		</tr>
+		<tr>
+			<td>heading-small</td>
+			<td>`$font-family-headings`, `font-weight-medium`, `font-size-x-small`, `line-height-x-small`</td>
+		</tr>
+	</tbody>
+</table>
+
+### Body
+
+<Typeset
+	fontSizes={[
+		Number(typography.size.s5),
+		Number(typography.size.s4),
+		Number(typography.size.s3),
+		Number(typography.size.s2),
+	]}
+	fontWeight={typography.weight.regular}
+	sampleText={SampleTextParagraph}
+	fontFamily={typography.type.primary}
+/>
+
+<table>
+	<thead>
+		<tr>
+			<th>Style</th>
+			<th>Primitives</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr>
+			<td>body-x-large</td>
+			<td>`$font-family-body`, `font-weight-regular`, `font-size-x-large`, `line-height-x-large`</td>
+		</tr>
+		<tr>
+			<td>body-large</td>
+			<td>`$font-family-body`, `font-weight-regular`, `font-size-large`, `line-height-medium`</td>
+		</tr>
+		<tr>
+			<td>body-medium</td>
+			<td>`$font-family-body`, `font-weight-regular`, `font-size-medium`, `line-height-small`</td>
+		</tr>
+		<tr>
+			<td>body-small</td>
+			<td>`$font-family-body`, `font-weight-regular`, `font-size-small`, `line-height-x-small`</td>
+		</tr>
+	</tbody>
+</table>
+
+## Primitive tokens
+ 
+Primitive tokens are organized into 4 sets relating to `size`, `line-height`, `weight`, and `family`, defined as SASS variables.
+
+### Size
+```css
+$font-size-x-small: 11px;
+$font-size-small: 12px;
+$font-size-medium: 13px;
+$font-size-large: 15px;
+$font-size-x-large: 20px;
+$font-size-2x-large: 32px;
+```
+
+### Line-height
+
+```css
+$font-line-height-x-small: 16px;
+$font-line-height-small: 20px;
+$font-line-height-medium: 24px;
+$font-line-height-large: 28px;
+$font-line-height-x-large: 32px;
+$font-line-height-2x-large: 40px;
+```
+
+### Weight
+
+```css
+$font-weight-regular: 400;
+$font-weight-medium: 500;
+```
+
+### Families
+
+```css
+$font-family-headings: -apple-system, "system-ui", "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
+$font-family-body: -apple-system, "system-ui", "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
+$font-family-mono: Menlo, Consolas, monaco, monospace;
+```
+
+Generally use of semantic tokens is encouraged, but it is possible to create ad hoc styles by referencing primitives, for example:
+
+```css
+.my-type-style {
+	font-family: $font-family-headings;
+	line-height: $font-line-height-x-small;
+	font-weight: $font-weight-regular;
+}
+```