docs: document design tokens

docs/collections.ts

@@ -11,6 +11,7 @@ interface Collections {
   pages: Collection<{ index?: number }>[];
   components: Collection<{ deprecated?: boolean }>[];
   componentsV1: Collection[];
+  foundations: Collection[];
 }
 
 /*
@@ -28,6 +29,7 @@ const collections: Collections = (require as any)
     (collections: Collections, key: string) => {
       const pagesMatch = minimatch(key, './pages/*.mdx');
       const componentMatch = minimatch(key, './pages/components/*.mdx');
+      const foundationMatch = minimatch(key, './pages/foundations/*.mdx');
       const filepath = `docs${key.substring(1)}`;
 
       if (pagesMatch) {
@@ -64,11 +66,28 @@ const collections: Collections = (require as any)
           ...props
         };
         collections.components.push(component);
+      } else if (foundationMatch) {
+        const name = key.match(/(\w+)\.mdx$/)?.[1] || '';
+        const {
+          default: Component,
+          title,
+          path,
+          ...props
+        } = require(`./pages/foundations/${name}.mdx`);
+        const component = {
+          name,
+          title,
+          Component,
+          path: path || `/foundations/${name}`,
+          filepath,
+          ...props
+        };
+        collections.foundations.push(component);
       }
 
       return collections;
     },
-    { pages: [], components: [], componentsV1: [] }
+    { pages: [], components: [], componentsV1: [], foundations: [] }
   );
 
 // Pages should first be sorted by their index, then alphabetical
@@ -88,3 +107,7 @@ export const pages = [
 export const components = [...collections.components].sort((a, b) =>
   a.name.localeCompare(b.name)
 );
+
+export const foundations = [...collections.foundations].sort((a, b) =>
+  a.name.localeCompare(b.name)
+);

docs/components/Colors.css

@@ -0,0 +1,65 @@
+:root {
+  --hex-font-size: 0.7rem;
+  --border-color: #f0f0f0;
+  --color-text-white: #fefefe;
+  --color-text-gray: var(--accent-dark);
+}
+
+.Colors {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: var(--space-small);
+}
+
+.Color {
+  width: var(--color-width);
+  height: var(--color-height);
+  display: inline-block;
+  margin-right: 20px var(--space-medium);
+  border: 1px solid var(--border-color);
+}
+
+.Color__bg {
+  height: 3rem;
+  position: relative;
+  border-bottom: solid 1px var(--border-color);
+}
+
+.Color__title {
+  display: inline-block;
+  font-size: var(--text-size-smallest);
+  padding-left: var(--space-half);
+}
+
+.Color__hex {
+  font-size: var(--hex-font-size);
+  position: absolute;
+  left: var(--space-half);
+  bottom: var(--space-half);
+}
+
+.Color__hex--gray {
+  color: var(--color-text-gray);
+}
+
+.Color__hex--white {
+  color: var(--color-text-white);
+}
+
+@media (max-width: 42rem) {
+  .Colors {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+
+@media (max-width: 36rem) {
+  .Colors {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (max-width: 24rem) {
+  .Colors {
+    grid-template-columns: repeat(1, 1fr);
+  }
+}

docs/components/Colors.tsx

@@ -0,0 +1,98 @@
+import React, { useMemo } from 'react';
+
+import './Colors.css';
+import classNames from 'classnames';
+import { useThemeContext } from '../../packages/react/lib';
+
+interface ColorsProps extends React.HTMLAttributes<HTMLDivElement> {
+  colorGroup: string;
+  colorNames: string[];
+}
+
+interface ColorProps {
+  name: string;
+  value: string;
+}
+
+const LUMINANCE_TEXT_DIFFERENTIAL = 0.45;
+const LUMINANCE_FRAME_DIFFERENTIAL = 0.95;
+
+const GRAY_TEXT = 'Color__hex--gray';
+const WHITE_TEXT = 'Color__hex--white';
+
+function calculateLuminance(hexColor: string) {
+  // Remove the "#" character if it exists
+  hexColor = hexColor.replace(/^#/, '');
+
+  if (hexColor.length === 3) {
+    hexColor = hexColor
+      .split('')
+      .map((char) => char + char)
+      .join('');
+  }
+
+  // Convert the hex color to RGB
+  const r = parseInt(hexColor.slice(0, 2), 16);
+  const g = parseInt(hexColor.slice(2, 4), 16);
+  const b = parseInt(hexColor.slice(4, 6), 16);
+
+  // Calculate the relative luminance
+  const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+
+  return luminance;
+}
+
+const getColorValueByName = (color: string) =>
+  getComputedStyle(document.documentElement).getPropertyValue(`--${color}`);
+const normalizeVarValue = (color: string) => {
+  const isVar = color.includes('var');
+
+  if (isVar) {
+    const varName = color.match(/var\(([^)]+)\)/); // get real color variable
+
+    return varName ? getColorValueByName(varName[1]) : '';
+  }
+
+  return getColorValueByName(color);
+};
+const isNeedFrame = (color: string) => {
+  const luminance = calculateLuminance(color);
+
+  return luminance > LUMINANCE_FRAME_DIFFERENTIAL;
+};
+
+const Color = ({ name, value }: ColorProps) => {
+  const textColorClass = useMemo(
+    () =>
+      calculateLuminance(value) > LUMINANCE_TEXT_DIFFERENTIAL
+        ? GRAY_TEXT
+        : WHITE_TEXT,
+    [value]
+  );
+
+  return (
+    <div className={'Color'}>
+      <div className={classNames('Color__bg')} style={{ background: value }}>
+        <span className={classNames('Color__hex', textColorClass)}>
+          {value.toUpperCase()}
+        </span>
+      </div>
+      <div className={'Color__title'}>{name}</div>
+    </div>
+  );
+};
+
+export default function Colors({ colorGroup, colorNames }: ColorsProps) {
+  const colors: ColorProps[] = colorNames.map((color: string) => ({
+    name: color,
+    value: normalizeVarValue(color)
+  }));
+
+  return (
+    <section className={`Colors Colors--${colorGroup}`}>
+      {colors.map((color: ColorProps, index: number) => (
+        <Color key={index} name={color.name} value={color.value} />
+      ))}
+    </section>
+  );
+}

docs/components/CssParamsTable.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow
+} from '@deque/cauldron-react';
+
+import { getCssVariablesStartingWith } from '../utils/getCssVariablesStartingWith';
+
+interface CssParamsTableProps {
+  param?: string;
+  renderExample?: (name: string, value: string) => JSX.Element;
+  formatName?: (name: string) => string;
+}
+
+const CssParamsTable = ({
+  param = '--text-size',
+  renderExample,
+  formatName = (name: string) => name
+}: CssParamsTableProps) => {
+  const textSizes = getCssVariablesStartingWith(param);
+
+  return (
+    <Table>
+      <TableHead>
+        <TableRow>
+          <TableHeader scope="col">Name</TableHeader>
+          <TableHeader scope="col">Value</TableHeader>
+          <TableHeader scope="col">Description</TableHeader>
+          {renderExample && <TableHeader scope="col">Example</TableHeader>}
+        </TableRow>
+      </TableHead>
+      <TableBody>
+        {Object.entries(textSizes).map(([name, value], index) => (
+          <TableRow key={index}>
+            <TableCell>{formatName(name)}</TableCell>
+            <TableCell>{value}</TableCell>
+            <TableCell>-</TableCell>
+            {renderExample && (
+              <TableCell>{renderExample(name, value)}</TableCell>
+            )}
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+};
+
+export default CssParamsTable;

docs/components/Navigation.tsx

@@ -1,7 +1,7 @@
 import React, { useState, useEffect } from 'react';
 import { Icon, ClickOutsideListener, Scrim } from '@deque/cauldron-react';
 import { Link, useLocation } from 'react-router-dom';
-import { components, pages } from '../collections';
+import { components, pages, foundations } from '../collections';
 import './Navigation.css';
 
 interface NavigationLinkProps {
@@ -63,13 +63,13 @@ function Navigation(
   };
 
   const activeComponents = components.filter(
-    component => !component.deprecated
+    (component) => !component.deprecated
   );
   const deprecatedComponents = components.filter(
-    component => component.deprecated
+    (component) => component.deprecated
   );
 
-  const renderListItem = ({ path, name }: typeof components[number]) => {
+  const renderListItem = ({ path, name }: (typeof components)[number]) => {
     const isActive = path === location.pathname;
     return (
       <li key={path}>
@@ -95,6 +95,10 @@ function Navigation(
         <Icon type="info-circle" /> Getting Started
       </h2>
       <ul>{pages.map(renderListItem)}</ul>
+      <h2>
+        <Icon type="info-circle" /> Foundations
+      </h2>
+      <ul>{foundations.map(renderListItem)}</ul>
       <h2>
         <Icon type="gears" />
         Components

docs/components/Spacing.css

@@ -0,0 +1,13 @@
+:root {
+  --spacing-list-base-size: 14px;
+  --spacing-example-color: #0077cc;
+}
+
+.cauldron--theme-dark {
+  --spacing-list-name-color: var(--gray-20);
+  --spacing-list-base-color: var(--gray-40);
+}
+
+.Spacing__example {
+  background: var(--spacing-example-color);
+}

docs/components/Spacing.tsx

@@ -0,0 +1,18 @@
+import React from 'react';
+
+import './Spacing.css';
+import CssParamsTable from './CssParamsTable';
+
+const Spacing = () => {
+  const renderExample = (name: string, value: string) => {
+    return <div className="Spacing__example" style={{ padding: value }}></div>;
+  };
+
+  return (
+    <div className="Spacing">
+      <CssParamsTable param="--space" renderExample={renderExample} />
+    </div>
+  );
+};
+
+export default Spacing;

docs/index.js

@@ -24,7 +24,7 @@ import {
   Icon,
   ThemeProvider
 } from '@deque/cauldron-react';
-import { components, pages } from './collections';
+import { components, foundations, pages } from './collections';
 import logo from './assets/img/logo.svg';
 import darkLogo from './assets/img/dark-logo.svg';
 import '@fontsource/roboto';
@@ -259,6 +259,15 @@ const App = () => {
 
             return <Route key={name} exact path={path} component={render} />;
           })}
+          {foundations.map(({ name, path, Component, ...props }) => {
+            const render = () => (
+              <ComponentLayout {...props}>
+                <Component components={mdxComponents} />
+              </ComponentLayout>
+            );
+
+            return <Route key={name} exact path={path} component={render} />;
+          })}
           <Route
             component={({ location }) =>
               location.state && location.state.title ? (

docs/mdx-components.tsx

@@ -15,6 +15,7 @@ import {
 import Example from './components/Example';
 import ComponentProps from './components/ComponentProps';
 import Note from './components/Note';
+import CssParamsTable from './components/CssParamsTable';
 
 interface HeadingProps extends React.HTMLAttributes<HTMLHeadingElement> {
   level: number;
@@ -103,7 +104,8 @@ const mdxComponents = {
   ),
   Example,
   ComponentProps,
-  Note
+  Note,
+  CssParamsTable
 };
 
 export default mdxComponents;