docs: Add system color stories [skip release] (#102)

This PR adds initial system color token docs

[category:Documentation]

packages/canvas-tokens-docs/components/ColorGrid.tsx

@@ -1,6 +1,48 @@
 import * as React from 'react';
 import {TokenGrid, formatJSVar} from './TokenGrid';
 
+const sortMap: Record<string, number> = {
+  softer: 0,
+  soft: 1,
+  default: 2,
+  strong: 3,
+  stronger: 4,
+};
+
+export function sortSystemColorPalette(a: ColorSwatch, b: ColorSwatch) {
+  const aLevel = a.cssVar.split('-').at(-1) || '';
+  const bLevel = b.cssVar.split('-').at(-1) || '';
+  const first = aLevel in sortMap ? sortMap[aLevel] : Infinity;
+  const second = bLevel in sortMap ? sortMap[bLevel] : Infinity;
+  return first - second;
+}
+
+export function buildPalette(prefix: string, tokens: Record<string, string>) {
+  return Object.entries(tokens).map(([value, varName]) =>
+    buildColorSwatch(varName, `${prefix}.${value}`)
+  );
+}
+
+export function buildPaletteGroup(
+  prefix: string,
+  tokens: object,
+  sortFn?: (a: ColorSwatch, b: ColorSwatch) => number
+) {
+  return Object.entries(tokens)
+    .map(([key, value]) => {
+      if (typeof value === 'string') {
+        return buildColorSwatch(value, `${prefix}.${key}`);
+      } else {
+        const palette = buildPalette(`${prefix}.${key}`, value);
+        if (sortFn) {
+          return palette.sort(sortFn);
+        }
+        return palette;
+      }
+    })
+    .flat();
+}
+
 export interface ColorSwatch {
   /** The name of the CSS variable */
   cssVar: string;
@@ -21,9 +63,12 @@ export function buildColorSwatch(varName: string, jsVarName: string): ColorSwatc
   };
 }
 
+type VariableType = 'css' | 'javascript' | 'all';
+
 interface ColorGridProps {
   name: string;
   palette: ColorSwatch[];
+  variableType?: VariableType;
 }
 
 /** transform 'camelCase' names into 'spaced case' */
@@ -43,25 +88,39 @@ function getSwatchStyles(token: ColorSwatch) {
   return {[property]: `var(${token.cssVar})`};
 }
 
+function getHeadings(type: VariableType) {
+  const defaultHeadings = ['Swatch', 'Value'];
+  if (type === 'css') {
+    defaultHeadings.splice(1, 0, 'CSS Variable');
+  } else if (type === 'javascript') {
+    defaultHeadings.splice(1, 0, 'JS Variable');
+  } else {
+    defaultHeadings.splice(1, 0, 'CSS Variable', 'JS Variable');
+  }
+  return defaultHeadings;
+}
+
 /** A configuration of TokenGrid to quickly build tables for colors */
-export function ColorGrid(props: ColorGridProps) {
+export function ColorGrid({name, variableType = 'all', palette}: ColorGridProps) {
   return (
-    <TokenGrid
-      caption={formatName(props.name)}
-      headings={['Swatch', 'CSS Variable', 'JS Variable', 'Value']}
-      rows={props.palette}
-    >
+    <TokenGrid caption={formatName(name)} headings={getHeadings(variableType)} rows={palette}>
       {token => (
         <>
           <TokenGrid.RowItem>
             <TokenGrid.Swatch style={getSwatchStyles(token)} />
           </TokenGrid.RowItem>
-          <TokenGrid.RowItem>
-            <TokenGrid.MonospaceLabel>{token.cssVar}</TokenGrid.MonospaceLabel>
-          </TokenGrid.RowItem>
-          <TokenGrid.RowItem>
-            <TokenGrid.MonospaceLabel>{token.jsVar}</TokenGrid.MonospaceLabel>
-          </TokenGrid.RowItem>
+          {variableType === 'css' ||
+            ('all' && (
+              <TokenGrid.RowItem>
+                <TokenGrid.MonospaceLabel>{token.cssVar}</TokenGrid.MonospaceLabel>
+              </TokenGrid.RowItem>
+            ))}
+          {variableType === 'javascript' ||
+            ('all' && (
+              <TokenGrid.RowItem>
+                <TokenGrid.MonospaceLabel>{token.jsVar}</TokenGrid.MonospaceLabel>
+              </TokenGrid.RowItem>
+            ))}
           <TokenGrid.RowItem>
             <span>{token.value}</span>
           </TokenGrid.RowItem>

packages/canvas-tokens-docs/stories/system/ColorBackground.stories.mdx

@@ -0,0 +1,57 @@
+import {Meta, Unstyled} from '@storybook/blocks';
+
+import {
+  BackgroundColors,
+  BackgroundAlternateColors,
+  BackgroundMutedColors,
+  BackgroundContrastColors,
+  BackgroundStatusColors,
+} from "./examples/Color/Background"
+
+<Meta title="Docs/System Tokens/Color/Background" />
+
+<Unstyled>
+
+# System Background Color Tokens
+
+System background color tokens provide values for surfaces.
+
+## Usage
+
+```ts
+// styles.ts
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  backgroundColor: `var(${system.color.bg.default})`,
+};
+```
+
+```css
+// styles.css
+.card {
+  background-color: var(--cnvs-sys-color-bg-default);
+}
+```
+
+## Tokens
+
+<BackgroundColors />
+
+---
+
+<BackgroundAlternateColors />
+
+---
+
+<BackgroundMutedColors />
+
+---
+
+<BackgroundContrastColors />
+
+---
+
+<BackgroundStatusColors />
+
+</Unstyled>

packages/canvas-tokens-docs/stories/system/ColorBorder.stories.mdx

@@ -0,0 +1,46 @@
+import {Meta, Unstyled} from '@storybook/blocks';
+import {BorderColors, BorderContrastColors, BorderInputColors, BorderStatusColors } from './examples/Color/Border';
+
+<Meta title="Docs/System Tokens/Color/Border" />
+
+<Unstyled>
+
+# System Border Color Tokens
+
+System border color tokens provide values to create clear delineations between content.
+
+## Usage
+
+```ts
+// styles.ts
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  borderColor: `var(${system.color.border.container})`,
+};
+```
+
+```css
+// styles.css
+.card {
+  border-color: var(--cnvs-sys-color-border-container);
+}
+```
+
+## Tokens
+
+<BorderColors />
+
+---
+
+<BorderContrastColors />
+
+---
+
+<BorderInputColors />
+
+---
+
+<BorderStatusColors />
+
+</Unstyled>

packages/canvas-tokens-docs/stories/system/ColorForeground.stories.mdx

@@ -0,0 +1,42 @@
+import {Meta, Unstyled} from '@storybook/blocks';
+
+import { ForegroundColors, ForegroundStatusColors} from './examples/Color/Foreground';
+
+<Meta title="Docs/System Tokens/Color/Foreground" />
+
+<Unstyled>
+
+# System Foreground Color Tokens
+
+System foreground color tokens provide values for foreground elements.
+
+## Usage
+
+```ts
+// styles.ts
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  color: `var(${system.color.fg.default})`,
+};
+```
+
+```css
+// styles.css
+.card {
+  color: var(--cnvs-sys-color-fg-default);
+}
+```
+
+## Tokens
+
+<ForegroundColors />
+
+---
+
+<ForegroundStatusColors />
+
+---
+
+</Unstyled>
+

packages/canvas-tokens-docs/stories/system/ColorIcon.stories.mdx

@@ -0,0 +1,45 @@
+import {Meta, Unstyled} from '@storybook/blocks';
+import {IconColors, IconPrimaryColors, IconStatusColors} from './examples/Color/Icon';
+
+<Meta title="Docs/System Tokens/Color/Icon" />
+
+<Unstyled>
+
+# System Icon Color Tokens
+
+System icon color tokens provide values for icons.
+
+## Usage
+
+```ts
+// styles.ts
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  color: `var(${system.color.icon.default})`,
+};
+```
+
+```css
+// styles.css
+.icon {
+  color: var(--cnvs-sys-color-icon-default);
+}
+```
+
+## Tokens
+
+<IconColors />
+
+---
+
+<IconPrimaryColors />
+
+---
+
+<IconStatusColors />
+
+---
+
+</Unstyled>
+

packages/canvas-tokens-docs/stories/system/ColorStatic.stories.mdx

@@ -0,0 +1,35 @@
+import {Meta, Unstyled} from '@storybook/blocks';
+
+import { StaticColors } from "./examples/Color/Static"
+
+<Meta title="Docs/System Tokens/Color/Static" />
+
+<Unstyled>
+
+# System Static Color Tokens
+
+System static color tokens provide consistent color values.
+
+## Usage
+
+```ts
+// styles.ts
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  backgroundColor: `var(${system.color.static.blue.soft})`,
+};
+```
+
+```css
+// styles.css
+.info-card {
+  background-color: var(--cnvs-sys-color-static-blue-soft);
+}
+```
+
+## Tokens
+
+<StaticColors />
+
+</Unstyled>

packages/canvas-tokens-docs/stories/system/ColorText.stories.mdx

@@ -0,0 +1,43 @@
+import {Meta, Unstyled} from '@storybook/blocks';
+
+import { TextColors, TextStatusColors } from "./examples/Color/Text"
+
+<Meta title="Docs/System Tokens/Color/Text" />
+
+<Unstyled>
+
+# System Text Color Tokens
+
+System text color tokens provide values for typography.
+
+## Usage
+
+```ts
+// styles.ts
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = {
+  color: `var(${system.color.text.default})`,
+};
+```
+
+```css
+// styles.css
+.card-text {
+  color: var(--cnvs-sys-color-text-default);
+}
+```
+
+---
+
+## Tokens
+
+<TextColors />
+
+---
+
+<TextStatusColors />
+
+---
+
+</Unstyled>