docs: Add consumer documentation (#60)

Adds consumer documentation [category:Documentation]
Workday · Oct 25, 2023 · 58d367c · 58d367c
1 parent b7d779f
commit 58d367c
Show file tree

Hide file tree

Showing 35 changed files with 1,032 additions and 187 deletions.
diff --git a/packages/canvas-tokens-docs/.storybook/global.css b/packages/canvas-tokens-docs/.storybook/global.css
@@ -0,0 +1,92 @@
+* {
+  box-sizing: border-box;
+}
+
+h1,h2,h3,h4,h5,h6 {
+  color: var(--cnvs-base-palette-black-pepper-400);
+  margin: 0;
+}
+
+ol, ul {
+  color: var(--cnvs-base-palette-black-pepper-300);
+  font-family: var(--cnvs-base-font-family-50);
+  font-weight: var(--cnvs-base-font-weight-400);
+  line-height: var(--cnvs-base-line-height-150);
+  font-size: var(--cnvs-base-font-size-100);
+  letter-spacing: var(--cnvs-base-letter-spacing-200);
+  margin: 0;
+  padding: 0;
+  list-style: inside;
+  margin: 1rem 0;
+}
+
+/* for nested list styles */
+ul ul {
+  margin: 0;
+  padding-inline-start: 1rem;
+}
+
+h1 {
+  font-family: var(--cnvs-base-font-family-50);
+  font-weight: var(--cnvs-base-font-weight-700);
+  line-height: var(--cnvs-base-line-height-500);
+  font-size: var(--cnvs-base-font-size-500);
+}
+
+h2 {
+  font-family: var(--cnvs-base-font-family-50);
+  font-weight: var(--cnvs-base-font-weight-700);
+  line-height: var(--cnvs-base-line-height-350);
+  font-size: var(--cnvs-base-font-size-300);
+}
+
+h3 {
+  font-family: var(--cnvs-base-font-family-50);
+  font-weight: var(--cnvs-base-font-weight-700);
+  line-height: var(--cnvs-base-line-height-300);
+  font-size: var(--cnvs-base-font-size-250);
+}
+
+h4 {
+  font-family: var(--cnvs-base-font-family-50);
+  font-weight: var(--cnvs-base-font-weight-700);
+  line-height: var(--cnvs-base-line-height-250);
+  font-size: var(--cnvs-base-font-size-200);
+}
+
+p {
+  color: var(--cnvs-base-palette-black-pepper-300);
+  font-family: var(--cnvs-base-font-family-50);
+  font-weight: var(--cnvs-base-font-weight-400);
+  line-height: var(--cnvs-base-line-height-150);
+  font-size: var(--cnvs-base-font-size-100);
+  letter-spacing: var(--cnvs-base-letter-spacing-200);
+  margin: 1rem 0;
+}
+
+pre {
+  margin: 0;
+}
+
+pre > * {
+  font-family: var(--cnvs-base-font-family-100);
+  font-size: var(--cnvs-base-font-size-75);
+}
+
+blockquote {
+  margin: 0;
+  padding: var(--cnvs-sys-space-x2) var(--cnvs-sys-space-x6);
+  border-left: 0.25rem solid var(--cnvs-base-palette-soap-400);
+  color: var(--cnvs-base-palette-licorice-300);
+}
+
+blockquote > p {
+  margin: 0;
+}
+
+hr {
+  background-color: var(--cnvs-base-palette-soap-500);
+  border: none;
+  height: 0.0625rem;
+  margin: 2rem 0;
+}
diff --git a/packages/canvas-tokens-docs/.storybook/preview-head.html b/packages/canvas-tokens-docs/.storybook/preview-head.html
@@ -2,12 +2,6 @@
   document.title = 'Canvas Tokens Storybook';
 </script>
 
-<style type="text/css">
-  * {
-    box-sizing: border-box;
-  }
-</style>
-
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=Noto+Sans&family=Roboto+Mono&family=Roboto:wght@300;400;500;700&display=swap" rel="stylesheet">
diff --git a/packages/canvas-tokens-docs/.storybook/preview.ts b/packages/canvas-tokens-docs/.storybook/preview.ts
@@ -3,12 +3,18 @@ import '@workday/canvas-tokens-web/css/base/_variables.css';
 import '@workday/canvas-tokens-web/css/brand/_variables.css';
 import '@workday/canvas-tokens-web/css/system/_variables.css';
 
+import './global.css';
+
 const preview: Preview = {
   parameters: {
     chromatic: {disableSnapshot: false},
     options: {
       storySort: {
-        order: ['Docs', ['Getting Started'], 'Visual Tests'],
+        order: [
+          'Docs',
+          ['Getting Started', 'Base Tokens', 'Brand Tokens', 'System Tokens', ['Overview']],
+          'Visual Tests',
+        ],
       },
     },
   },

diff --git a/packages/canvas-tokens-docs/components/ColorGrid.tsx b/packages/canvas-tokens-docs/components/ColorGrid.tsx
@@ -1,18 +1,23 @@
 import * as React from 'react';
-import {TokenGrid} from './TokenGrid';
+import {TokenGrid, formatJSVar} from './TokenGrid';
 
 export interface ColorSwatch {
+  /** The name of the CSS variable */
+  cssVar: string;
+  /** The formatted name of the JS variable */
+  jsVar: React.ReactNode;
+  /** The actual string value of the token */
   value: string;
-  varName: string;
 }
 
 /** builds color swatch objects for ColorGrid */
-export function buildColorSwatch(varName: string): ColorSwatch {
+export function buildColorSwatch(varName: string, jsVarName: string): ColorSwatch {
   // Get the CSS var's value from the :root element
   const value = getComputedStyle(document.documentElement).getPropertyValue(varName);
   return {
     value,
-    varName,
+    cssVar: varName,
+    jsVar: formatJSVar(jsVarName),
   };
 }
 
@@ -30,21 +35,20 @@ function formatName(name: string) {
 }
 
 function getSwatchStyles(token: ColorSwatch) {
-  // linear gradients need to be background images
-  if (token.value.startsWith('linear-gradient(')) {
-    return {backgroundImage: `var(${token.varName})`};
-    // everything else can be a background color
-  } else {
-    return {backgroundColor: `var(${token.varName})`};
-  }
+  // update the property to support linear gradients
+  // which need to be a background image instead of background color
+  const property = token.value.startsWith('linear-gradient(')
+    ? 'backgroundImage'
+    : 'backgroundColor';
+  return {[property]: `var(${token.cssVar})`};
 }
 
 /** A configuration of TokenGrid to quickly build tables for colors */
 export function ColorGrid(props: ColorGridProps) {
   return (
     <TokenGrid
       caption={formatName(props.name)}
-      headings={['Swatch', 'CSS Variable', 'Value']}
+      headings={['Swatch', 'CSS Variable', 'JS Variable', 'Value']}
       rows={props.palette}
     >
       {token => (
@@ -53,10 +57,13 @@ export function ColorGrid(props: ColorGridProps) {
             <TokenGrid.Swatch style={getSwatchStyles(token)} />
           </TokenGrid.RowItem>
           <TokenGrid.RowItem>
-            <TokenGrid.MonospaceLabel>{token.varName}</TokenGrid.MonospaceLabel>
+            <TokenGrid.MonospaceLabel>{token.cssVar}</TokenGrid.MonospaceLabel>
           </TokenGrid.RowItem>
           <TokenGrid.RowItem>
-            <TokenGrid.MonospaceLabel>{token.value}</TokenGrid.MonospaceLabel>
+            <TokenGrid.MonospaceLabel>{token.jsVar}</TokenGrid.MonospaceLabel>
+          </TokenGrid.RowItem>
+          <TokenGrid.RowItem>
+            <span>{token.value}</span>
           </TokenGrid.RowItem>
         </>
       )}

diff --git a/packages/canvas-tokens-docs/components/TokenGrid/index.css b/packages/canvas-tokens-docs/components/TokenGrid/index.css
@@ -2,8 +2,8 @@
   border: solid 1px var(--cnvs-base-palette-soap-500);
   border-radius: 0.5rem;
   display: grid;
-  min-width: 48rem;
-  max-width: 64rem;
+  min-width: 62.5rem;
+  max-width: 80rem;
   overflow-x: auto;
 }
 
@@ -46,6 +46,7 @@
 .token-grid__row-item {
   align-items: start;
   display: grid;
+  font-family: var(--cnvs-base-font-family-100);
   gap: 0.25rem;
   justify-self: start;
 }
@@ -59,16 +60,17 @@
 }
 
 .token-grid__sample {
-  background-color: var(--cnvs-base-palette-french-vanilla-100);;
+  background-color: var(--cnvs-base-palette-french-vanilla-100);
   display: grid;
   grid-template-columns: minmax(2rem, 8rem);
   height: 2rem;
   width: 2rem;
 }
 
 .token-grid__monospace-label {
-  background-color: var(--cnvs-base-palette-soap-200);
-  font-family: 'Roboto Mono';
+  background-color: var(--cnvs-base-palette-blueberry-100);
+  color: var(--cnvs-base-palette-blueberry-500);
+  font-family: var(--cnvs-base-font-family-100);
   padding: 0.25rem;
   border-radius: 0.25rem;
   min-height: 1rem;

diff --git a/packages/canvas-tokens-docs/components/TokenGrid/index.tsx b/packages/canvas-tokens-docs/components/TokenGrid/index.tsx
@@ -12,6 +12,23 @@ function classNames(baseClassName: string, classNames = '') {
   return classNames.length ? `${baseClassName} ${classNames}` : baseClassName;
 }
 
+/** CSS won't break words on dots, so we need to add <wbr> tags manually.
+ * This function formats the JS var name so it will break on the dot notation */
+export function formatJSVar(varName: string) {
+  return varName.split('.').map((identifier, index) => {
+    // Don't add a word-break before the first identifier
+    if (!index) {
+      return identifier;
+    }
+    return (
+      <span key={index}>
+        .<wbr />
+        {identifier}
+      </span>
+    );
+  });
+}
+
 export function TokenGrid<T>({caption, children, headings, rows}: TokenGridProps<T>) {
   return (
     <table className="token-grid">
@@ -43,13 +60,16 @@ const TokenGridRowItem: React.FC<React.HTMLProps<HTMLTableCellElement>> = ({
   ...props
 }) => (
   <td
-    className={classNames('token-grid__row-item cnvs-sys-type-subtext-large', className)}
+    className={classNames('token-grid__row-item cnvs-sys-type-subtext-medium', className)}
     {...props}
   />
 );
 
 const TokenGridSample: React.FC<React.HTMLProps<HTMLSpanElement>> = ({className, ...props}) => (
-  <span className={classNames('token-grid__sample', className)} {...props} />
+  <span
+    className={classNames('token-grid__sample cnvs-sys-type-body-small', className)}
+    {...props}
+  />
 );
 
 const TokenGridSwatch: React.FC<React.HTMLProps<HTMLSpanElement>> = ({className, ...props}) => (
@@ -58,13 +78,18 @@ const TokenGridSwatch: React.FC<React.HTMLProps<HTMLSpanElement>> = ({className,
 
 const TokenGridMonospaceLabel: React.FC<React.HTMLProps<HTMLSpanElement>> = ({
   className,
+  children,
   ...props
-}) => (
-  <span
-    className={classNames('token-grid__monospace-label cnvs-sys-type-subtext-medium', className)}
-    {...props}
-  />
-);
+}) => {
+  return (
+    <span
+      className={classNames('token-grid__monospace-label cnvs-sys-type-subtext-medium', className)}
+      {...props}
+    >
+      {children}
+    </span>
+  );
+};
 
 TokenGrid.RowItem = TokenGridRowItem;
 TokenGrid.Sample = TokenGridSample;

diff --git a/packages/canvas-tokens-docs/stories/GettingStarted.mdx b/packages/canvas-tokens-docs/stories/GettingStarted.mdx
@@ -1,20 +1,30 @@
-{/* GettingStarted.mdx */}
-
-import {Meta} from '@storybook/blocks';
+import {Meta, Unstyled} from '@storybook/blocks';
 
 <Meta title="Docs/Getting Started" />
+<Unstyled>
 
 # Canvas Tokens Web
 
 This package provides Canvas design tokens for web applications.
 
-## Design Tokens
+## Getting Started
+
+Canvas design tokens are used throughout our Canvas components. Whether you're using them directly
+or indirectly, you'll want to understand what they are and how they work. This doc will get up and
+running quickly and answer basic questions along the way.
 
-Design tokens are a mechanism to encapsulate and share design data such as color, space, typography,
-shape, etc. across platforms. Our Canvas Tokens infrastructure is designed to connect these tokens
-to Figma and our product platforms: web, iOS, and Android.
+> **What's a design token?**
+>
+> Design tokens are a mechanism to encapsulate and share design data such as color, space,
+> typography, shape, etc. across platforms. Our Canvas Tokens infrastructure connects these tokens
+> to Figma and our product platforms: web, iOS, and Android.
 
-## Getting Started
+Our tokens live in a single package but are organized into three types: `base`, `brand`, and
+`system`. [Base tokens](/docs/docs-base-tokens--docs) are the foundation of our token system and
+exist to provide the values for our brand and system tokens.
+[Brand tokens](/docs/docs-brand-tokens--docs) are themeable tokens intended for brand / tenant
+customization. [System tokens](/docs/docs-system-tokens--docs) are themeable tokens intended for
+application-wide customization.
 
 ### Installation
 
@@ -24,9 +34,15 @@ npm install @workday/canvas-tokens-web
 
 ### Usage
 
+Canvas Tokens can be consumed as either JavaScript variables or as CSS variables and class names.
+The JavaScript token values reference CSS variable names, so if you're using JS tokens, you'll also
+need to import the CSS variables in your application.
+
 #### Importing CSS Variables
 
-CSS variables can be imported directly into CSS files,
+You should import our CSS variables at the top-level of your application to prevent duplicate
+imports and avoid unintentional overwrites. You can import these variables in a native CSS file or
+in a JavaScript / TypeScript file as shown in the examples below.
 
 ```css
 /* index.css */
@@ -35,10 +51,8 @@ CSS variables can be imported directly into CSS files,
 @import '@workday/canvas-tokens-web/css/brand/_variables.css';
 ```
 
-or in JavaScript / TypeScript files.
-
 ```ts
-// index.js
+// index.ts
 import '@workday/canvas-tokens-web/css/base/_variables.css';
 import '@workday/canvas-tokens-web/css/system/_variables.css';
 import '@workday/canvas-tokens-web/css/brand/_variables.css';
@@ -61,3 +75,17 @@ const cardStyles = {
   padding: `var(${system.space.x4})`,
 };
 ```
+
+## Usage in Storybook
+
+If you'd like to import these tokens in Storybook, it's best to add them to `.storybook/preview.ts`.
+This will ensure they're available in every story.
+
+```ts
+// .storybook/preview.ts
+import '@workday/canvas-tokens-web/css/base/_variables.css';
+import '@workday/canvas-tokens-web/css/system/_variables.css';
+import '@workday/canvas-tokens-web/css/brand/_variables.css';
+```
+
+</Unstyled>