feat(docs): update colors page to use new layout

packages/docs/components/ColorCards/ColorCard.tsx

@@ -0,0 +1,84 @@
+import { Flex, Link, Small, Text } from '@bigcommerce/big-design';
+import React, { useContext } from 'react';
+import styled, { ThemeContext } from 'styled-components';
+
+import { ColorDetails } from './availableColors';
+
+const StyledColor = styled(Flex)`
+  height: ${({ theme }) => theme.helpers.remCalc(160)};
+  width: ${({ theme }) => theme.helpers.remCalc(184)};
+  border-radius: ${({ theme }) => theme.borderRadius.normal};
+`;
+
+interface ColorCardProps {
+  colorCard: ColorDetails;
+}
+
+const ColorCard: React.FC<ColorCardProps> = ({ colorCard }) => {
+  const { colors } = useContext(ThemeContext);
+  const { description } = colorCard;
+  const colorValue = colors[colorCard.name];
+  const hasHexColor = colorValue.startsWith('#');
+  const hasSecondaryTextColor = colorCard.secondaryTextColor !== undefined;
+
+  const renderContrast = () => {
+    if (hasSecondaryTextColor) {
+      return (
+        <Flex alignItems="flex-end">
+          <Text marginRight="xSmall" marginBottom="none" color={colorCard.textColor}>
+            {colorCard.contrast}
+          </Text>
+          <Text marginBottom="none" color={colorCard.secondaryTextColor}>
+            {colorCard.contrast}
+          </Text>
+        </Flex>
+      );
+    }
+
+    return (
+      <Text margin="none" color={colorCard.textColor}>
+        {colorCard.contrast}
+      </Text>
+    );
+  };
+
+  return (
+    <StyledColor
+      backgroundColor={colorCard.name}
+      justifyContent={hasHexColor ? 'space-between' : 'baseline'}
+      flexDirection="column"
+      border="box"
+    >
+      <Text margin="small" color={colorCard.textColor} bold>
+        {getColorLabel(colorCard.name)}
+      </Text>
+
+      {description && (
+        <Small color={colorCard.textColor} margin="small">
+          {description?.text}{' '}
+          {description?.href && (
+            <Link href={description.href} target="_blank">
+              <Small color="inherit">Read more</Small>
+            </Link>
+          )}
+        </Small>
+      )}
+
+      {hasHexColor && (
+        <Flex margin="small" justifyContent="space-between" flexWrap="wrap">
+          <Text margin="none" color={colorCard.textColor}>
+            {colorValue}
+          </Text>
+
+          {renderContrast()}
+        </Flex>
+      )}
+    </StyledColor>
+  );
+};
+
+function getColorLabel(color: string) {
+  return color.includes('40') ? `${color} / ${color.replace('40', '')}` : color;
+}
+
+export default ColorCard;

packages/docs/components/ColorCards/ColorCards.tsx

@@ -0,0 +1,23 @@
+import { Flex, FlexItem } from '@bigcommerce/big-design';
+import React from 'react';
+
+import { ColorDetails } from './availableColors';
+import ColorCard from './ColorCard';
+
+interface ColorCardsProps {
+  colorCards: ColorDetails[];
+}
+
+export const ColorCards: React.FC<ColorCardsProps> = ({ colorCards }) => (
+  <Flex flexWrap="wrap">
+    {colorCards.map((colorCard) => {
+      return (
+        <FlexItem key={colorCard.name} margin="xxSmall">
+          <ColorCard colorCard={colorCard} />
+        </FlexItem>
+      );
+    })}
+  </Flex>
+);
+
+export default ColorCards;

packages/docs/components/ColorCards/availableColors.ts

@@ -0,0 +1,106 @@
+import { ThemeInterface } from '@bigcommerce/big-design-theme';
+
+type Colors = ThemeInterface['colors'];
+type Color = keyof Colors;
+
+export interface ColorDetails {
+  contrast?: 'AAA' | 'AA' | 'A';
+  description?: {
+    text: string;
+    href?: string;
+  };
+  name: Color;
+  secondaryTextColor?: Color;
+  textColor: Color;
+}
+
+export const accentColors: ColorDetails[] = [
+  { contrast: 'AA', name: 'primary40', textColor: 'white' },
+  { contrast: 'AAA', name: 'primary10', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'primary20', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'primary30', textColor: 'secondary70' },
+  { contrast: 'AA', name: 'primary50', textColor: 'white' },
+  { contrast: 'AAA', name: 'primary60', textColor: 'white' },
+  { contrast: 'AAA', name: 'primary70', textColor: 'white' },
+];
+
+export const typeColors: ColorDetails[] = [
+  { contrast: 'AAA', name: 'secondary70', textColor: 'white' },
+  { contrast: 'AA', name: 'secondary60', textColor: 'white' },
+  { contrast: 'A', name: 'secondary50', secondaryTextColor: 'secondary70', textColor: 'white' },
+  { contrast: 'AAA', name: 'white', textColor: 'secondary70' },
+];
+
+export const fillsAndStrokesColors: ColorDetails[] = [
+  { contrast: 'AAA', name: 'white', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'secondary10', textColor: 'secondary70' },
+  { contrast: 'AA', name: 'secondary20', textColor: 'secondary70' },
+  { contrast: 'A', name: 'secondary30', textColor: 'secondary70' },
+  { contrast: 'A', name: 'secondary40', textColor: 'secondary70' },
+];
+
+export const statusSuccessColors: ColorDetails[] = [
+  { contrast: 'AA', name: 'success40', textColor: 'white' },
+  { contrast: 'AAA', name: 'success10', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'success20', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'success30', textColor: 'secondary70' },
+  { contrast: 'AA', name: 'success50', textColor: 'white' },
+  { contrast: 'AAA', name: 'success60', textColor: 'white' },
+  { contrast: 'AAA', name: 'success70', textColor: 'white' },
+];
+
+export const statusDangerColors: ColorDetails[] = [
+  { contrast: 'AA', name: 'danger40', textColor: 'white' },
+  { contrast: 'AAA', name: 'danger10', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'danger20', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'danger30', textColor: 'secondary70' },
+  { contrast: 'AA', name: 'danger50', textColor: 'white' },
+  { contrast: 'AAA', name: 'danger60', textColor: 'white' },
+  { contrast: 'AAA', name: 'danger70', textColor: 'white' },
+];
+
+export const statusWarningColors: ColorDetails[] = [
+  { contrast: 'AA', name: 'warning40', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'warning10', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'warning20', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'warning30', textColor: 'secondary70' },
+  { contrast: 'AA', name: 'warning50', textColor: 'secondary70' },
+  { contrast: 'AAA', name: 'warning60', textColor: 'secondary70' },
+  { contrast: 'A', name: 'warning70', secondaryTextColor: 'white', textColor: 'secondary70' },
+];
+
+export const additionalColors: ColorDetails[] = [
+  {
+    description: {
+      text: 'Current value of an element’s color property.',
+      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#currentcolor_keyword',
+    },
+    name: 'currentColor',
+    textColor: 'white',
+  },
+  {
+    description: {
+      text: 'Element inherits value from parent element.',
+      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/inherit',
+    },
+    name: 'inherit',
+    textColor: 'secondary70',
+  },
+  {
+    description: {
+      text: 'Renders background behind colored item completely visible.',
+      href: 'https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#transparent_keyword',
+    },
+    name: 'transparent',
+    textColor: 'secondary70',
+  },
+  {
+    contrast: 'AA',
+    description: {
+      text: 'Used by BigCommerce branded assets.',
+      href: '',
+    },
+    name: 'brand',
+    textColor: 'white',
+  },
+];

packages/docs/components/ColorCards/index.ts

@@ -0,0 +1,2 @@
+export * from './availableColors';
+export * from './ColorCards';

packages/docs/components/index.tsx

@@ -2,6 +2,7 @@ export * from './BetaRibbon';
 export * from './Code';
 export * from './CodePreview';
 export * from './CodeSnippet';
+export * from './ColorCards';
 export * from './Collapsible';
 export * from './ContentRoutingTabs';
 export * from './GuidelinesTable';

packages/docs/pages/colors.tsx

@@ -1,91 +1,77 @@
-import { Box, Flex, H1, Panel, Text } from '@bigcommerce/big-design';
-import { ThemeInterface } from '@bigcommerce/big-design-theme';
-import React, { useContext } from 'react';
-import styled, { ThemeContext } from 'styled-components';
+import { H1, Panel, Text } from '@bigcommerce/big-design';
+import React, { Fragment } from 'react';
 
-import { CodePreview, PageNavigation } from '../components';
+import { ColorCards } from '../components';
+import {
+  accentColors,
+  additionalColors,
+  fillsAndStrokesColors,
+  statusDangerColors,
+  statusSuccessColors,
+  statusWarningColors,
+  typeColors,
+} from '../components/ColorCards';
 
-const COLORS_TO_OMIT = ['primary', 'secondary', 'danger', 'warning', 'success'];
-type Colors = ThemeInterface['colors'];
-type Color = keyof Colors;
+const ColorsPage = () => {
+  return (
+    <>
+      <H1>Colors</H1>
 
-const StyledColor = styled(Box)`
-  height: ${({ theme }) => theme.helpers.remCalc(30)};
-  width: ${({ theme }) => theme.helpers.remCalc(300)};
-`;
+      <Panel header="Overview" headerId="overview">
+        <Text>
+          The BigDesign color system has five palette types named semantically for their use across the application. The
+          color system is derived from the BigCommerce brand and provides a consistent user experience for our merchants
+          and partners.
+        </Text>
+        <Text>
+          BigDesign uses color tokens to manage colors within each palette and are named for their role or hierarchy in
+          the palette. Color tokens improve communication between design and development and establish an organized use
+          of color in the BigCommerce application.
+        </Text>
+      </Panel>
 
-const ColorsPage = () => {
-  const { colors } = useContext(ThemeContext);
+      <Panel header="Accent" headerId="accent">
+        <Text>
+          Accent colors are used for interactions or to denote an interaction has taken place. Common accent uses
+          include buttons, icons, navigation, links and selections. Use accent colors sparingly to avoid confusion.
+        </Text>
 
-  const items = [
-    {
-      id: 'examples',
-      title: 'Examples',
-      render: () => (
-        <>
-          <Panel header="Applying to components">
-            <Text>Colors can be used directly on some of our components that expect a color as a prop.</Text>
+        <ColorCards colorCards={accentColors} />
+      </Panel>
 
-            <CodePreview>
-              {/* jsx-to-string:start */}
-              <Box backgroundColor="secondary20" padding="medium">
-                Box example
-              </Box>
-              {/* jsx-to-string:end */}
-            </CodePreview>
-          </Panel>
-          <Panel header="Applying to styles">
-            <Text>You can also use the colors directly from the theme to style other components, for example:</Text>
+      <Panel header="Type" headerId="type">
+        <Text>Type colors are used for text, iconography, and foreground elements in BigDesign interfaces.</Text>
 
-            <CodePreview>
-              {/* jsx-to-string:start */}
-              {function Example() {
-                const StyledBox = styled(Box)(({ theme }) => ({
-                  backgroundColor: theme.colors.secondary20,
-                  padding: theme.spacing.medium,
-                }));
+        <ColorCards colorCards={typeColors} />
+      </Panel>
 
-                return <StyledBox>StyledBox Example</StyledBox>;
-              }}
-              {/* jsx-to-string:end */}
-            </CodePreview>
-          </Panel>
-        </>
-      ),
-    },
-    {
-      id: 'colors',
-      title: 'Available colors',
-      render: () => (
-        <Panel header="Available colors">
-          <Flex flexDirection="column">
-            {getFilteredColors(colors).map((color) => (
-              <Flex alignItems="center" key={color}>
-                <StyledColor backgroundColor={color as Color} />
-                <Text marginLeft="medium">{getColorLabel(color)}</Text>
-              </Flex>
-            ))}
-          </Flex>
-        </Panel>
-      ),
-    },
-  ];
+      <Panel header="Fills and strokes" headerId="fills-and-strokes">
+        <Text>
+          Fills and strokes are used as the building blocks of BigDesign interfaces. They are used in combination to
+          create layering of backgrounds, panels, overlays and hierarchical UI elements.
+        </Text>
 
-  return (
-    <>
-      <H1>Colors</H1>
+        <ColorCards colorCards={fillsAndStrokesColors} />
+      </Panel>
+
+      <Panel header="Status" headerId="status">
+        <Text>
+          Status colors are reserved to indicate a system status such as errors, success or warnings. These colors
+          should be used sparingly and only for imformative purposes.
+        </Text>
+
+        <ColorCards colorCards={statusSuccessColors} />
+        <ColorCards colorCards={statusDangerColors} />
+        <ColorCards colorCards={statusWarningColors} />
+      </Panel>
 
-      <PageNavigation items={items} />
+      <Panel header="Additional colors" headerId="additional-colors">
+        <Text>Additional colors exist in the BigDesign color palette for edge cases and BigCommerce branding.</Text>
+
+        <ColorCards colorCards={additionalColors} />
+      </Panel>
     </>
   );
 };
 
-function getFilteredColors(colors: Colors) {
-  return Object.keys(colors).filter((color) => !COLORS_TO_OMIT.includes(color));
-}
-
-function getColorLabel(color: string) {
-  return color.includes('40') ? `${color} / ${color.replace('40', '')}` : color;
-}
-
 export default ColorsPage;