From cd68e3c1406f7b95348c52a5d6861004738bf14e Mon Sep 17 00:00:00 2001
From: Jon McClure <jon.r.mcclure@gmail.com>
Date: Wed, 9 Aug 2023 20:46:50 +0100
Subject: [PATCH] role tokens table

---
 src/docs/docs-components/CopyTable/Table.jsx       |  5 ++++-
 .../docs-components/CopyTable/styles.module.scss   | 11 +++++++++++
 src/docs/styles/tokens/intro.stories.mdx           | 14 +++++++-------
 src/docs/styles/tokens/typography/main.stories.mdx | 11 +++++++++++
 4 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/src/docs/docs-components/CopyTable/Table.jsx b/src/docs/docs-components/CopyTable/Table.jsx
index a23ddb52..a9dbc74d 100644
--- a/src/docs/docs-components/CopyTable/Table.jsx
+++ b/src/docs/docs-components/CopyTable/Table.jsx
@@ -35,7 +35,7 @@ const Copyable = (props) => {
 const TR = (props) => <tr>{props.children.map((c, i) => (<TD {...props} column={i} key={i}>{c}</TD>))}</tr>
 const TH = (props) => <th>{props.children}</th>;
 
-const CopyTable = ({ title = null, header, body, copyable, mdnLink = null }) => {
+const CopyTable = ({ title = null, note = null, header, body, copyable, mdnLink = null }) => {
   return (
     <Unstyled>
       <div className={classes.title}>
@@ -45,6 +45,9 @@ const CopyTable = ({ title = null, header, body, copyable, mdnLink = null }) =>
             <span className="material-symbols-outlined">link</span>
           </a>
         )}
+        {(note) && (
+          <p>{note}</p>
+        )}
       </div>
       <table className={classes.table}>
         <thead>
diff --git a/src/docs/docs-components/CopyTable/styles.module.scss b/src/docs/docs-components/CopyTable/styles.module.scss
index f03ef5af..aa3c89e5 100644
--- a/src/docs/docs-components/CopyTable/styles.module.scss
+++ b/src/docs/docs-components/CopyTable/styles.module.scss
@@ -2,6 +2,7 @@ $copyable: #0071a1;
 $header: #5e81ac;
 
 .title {
+  max-width: 600px;
   font-size: 18px;
   color: #666;
   margin-bottom: 5px;
@@ -18,6 +19,16 @@ $header: #5e81ac;
       opacity: 1;
     }
   }
+  p {
+    font-size: 0.85rem;
+    line-height: 1.25;
+    background-color: #f7fafc;
+    padding: 10px;
+    border-radius: 4px;
+    margin-top: 5px;
+    color: #333;
+    border: 1px solid hsla(203, 50%, 30%, 0.15);
+  }
 }
 
 .table :global {
diff --git a/src/docs/styles/tokens/intro.stories.mdx b/src/docs/styles/tokens/intro.stories.mdx
index e28108a7..5209cbbf 100644
--- a/src/docs/styles/tokens/intro.stories.mdx
+++ b/src/docs/styles/tokens/intro.stories.mdx
@@ -14,9 +14,9 @@ import color from '$lib/scss/tokens/text/\_color.scss?inline';
 
 # Style tokens
 
-All of the components in this library have been styled using a system of tokens. The style tokens give us a lot of flexibility to easily customise components' look, overwrite with more specific styles easily and ultimately make for the most concise CSS definitions possible.
+All of the components in this library have been styled using a system of tokens. The style tokens give us a lot of flexibility and ultimately make for the most concise CSS possible.
 
-You can also use our style tokens to help shortcut the time you spend writing CSS and reinventing solid design conventions.
+You can use the style tokens to help shortcut the time you spend writing CSS and reinventing solid design conventions.
 
 ## What's a "token"?
 
@@ -55,15 +55,15 @@ graph LR;
 
 > Whether you use style tokens or write your own custom CSS in your project is **entirely up to you**.
 >
-> There are hundreds of tokens, so they can be a little daunting at first. But learning the tokens for the styles you have to write most often will absolutely save you time, so we recommend giving them a try.
+> There are hundreds of tokens, so they can be a little daunting at first. But learning the tokens for the styles you have to write most often **will absolutely save you time**, so we recommend giving them a try.
 >
-> **That said**, we _do recommend_ using tokens for styling typography, especially `font-size`. Our typography size tokens responsively size the text on your page using a fluid scale so it will look great whether a reader is on a mobile phone or giant desktop.
+> **That said**, we _do recommend_ using tokens for styling typography, especially `font-size`. (Our typography size tokens use a fluid scale so your text will look great whether a reader is on a mobile phone or giant desktop.)
 
 All of our style tokens can be used through either a class name, an SCSS mixin or both. Use the tables throughout this section of the docs to see what's available for each token.
 
 ### For example...
 
-Here's our table of text colour tokens, which has a few preset tokens for setting `text-color`.
+Here's our table of text colour tokens, which set the `text-color` style.
 
 <CopyTable
   title="Colour"
@@ -73,9 +73,9 @@ Here's our table of text colour tokens, which has a few preset tokens for settin
   copyable={[true, (t) => `@include ${t};`, false]}
 />
 
-This table's tokens can be used through either a class or an SCSS mixin. (The table lets you click to copy for either.)
+This table's tokens can be used through either a class or an SCSS mixin. (The table lets you click-to-copy for either.)
 
-To use the token that sets the text colour to our "primary text colour" (i.e., black), you'd use the `Class` token like this:
+To use the token that sets the `color` style to our "primary" text colour (i.e., black), you'd use the `Class` token like this:
 
 ```svelte
 <p class="text-primary">Lorem ipsum...</p>
diff --git a/src/docs/styles/tokens/typography/main.stories.mdx b/src/docs/styles/tokens/typography/main.stories.mdx
index fa15767d..18a4f10a 100644
--- a/src/docs/styles/tokens/typography/main.stories.mdx
+++ b/src/docs/styles/tokens/typography/main.stories.mdx
@@ -3,6 +3,9 @@ import { parameters } from '$docs/utils/docsPage.js';
 import CopyTable from '../../../docs-components/CopyTable/Table.jsx';
 import { cssStringToTableArray } from '../../../utils/parseCss';
 
+{/* @ts-ignore */}
+import role from '$lib/scss/tokens/text/\_text-role.scss?inline';
+
 {/* @ts-ignore */}
 import color from '$lib/scss/tokens/text/\_color.scss?inline';
 
@@ -53,6 +56,14 @@ import './styles.scss';
 
 # Typography tokens
 
+<CopyTable
+  title="Role"
+  note="Role tokens group several individual style tokens for common text elements like headers, body text, notes and links. You can use them as a shorthand for our default typography styles."
+  header={['Class', 'Include', 'Properties']}
+  body={cssStringToTableArray(role, true)}
+  copyable={[true, (t) => `@include ${t};`, false]}
+/>
+
 <CopyTable
   title="Colour"
   mdnLink="color"