From 5ee235b7a54e0c774483738ee8f3ccfc58b2bc6b Mon Sep 17 00:00:00 2001
From: Peter Kulko <93188219+PKulkoRaccoonGang@users.noreply.github.com>
Date: Fri, 15 Sep 2023 10:15:00 +0300
Subject: [PATCH] docs: replaced SCSS variables with CSS variables on the
 Colors page (#2376)

* docs: replaced SCSS variables with CSS variables on the Colors page of the documentation site

* refactor: refactoring after review

* refactor: refactoring after review

* fix: removed extra commons.css generation

* refactor: code refactoring

* refactor: removed Colors package
---
 www/package.json                      |   6 +-
 www/src/components/PageLayout.tsx     |   5 -
 www/src/components/_doc-elements.scss |   6 +
 www/src/pages/foundations/colors.tsx  | 176 +++++++-------------------
 4 files changed, 57 insertions(+), 136 deletions(-)

diff --git a/www/package.json b/www/package.json
index ac60345b42..6b5f81fbac 100644
--- a/www/package.json
+++ b/www/package.json
@@ -11,7 +11,6 @@
     "analytics-node": "^6.0.0",
     "axios": "^0.27.2",
     "classnames": "^2.3.1",
-    "color": "^4.2.3",
     "gatsby": "^4.23.1",
     "gatsby-plugin-manifest": "^4.17.0",
     "gatsby-plugin-mdx": "^3.17.0",
@@ -37,8 +36,8 @@
     "rehype-slug": "^4.0.1",
     "sass": "^1.53.0",
     "sass-loader": "12.6.0",
-    "uuid": "^9.0.0",
-    "slugify": "^1.6.5"
+    "slugify": "^1.6.5",
+    "uuid": "^9.0.0"
   },
   "keywords": [
     "paragon",
@@ -69,7 +68,6 @@
     "@babel/preset-typescript": "^7.16.7",
     "@edx/eslint-config": "^3.1.0",
     "@svgr/webpack": "6.5.1",
-    "@types/color": "^3.0.3",
     "@types/mdx": "^2.0.3",
     "@types/mdx-js__react": "^1.5.5",
     "@types/react-helmet": "^6.1.6",
diff --git a/www/src/components/PageLayout.tsx b/www/src/components/PageLayout.tsx
index 440e9f4577..a5e1375819 100644
--- a/www/src/components/PageLayout.tsx
+++ b/www/src/components/PageLayout.tsx
@@ -27,11 +27,6 @@ import { SettingsContext } from '../context/SettingsContext';
 import LeaveFeedback from './LeaveFeedback';
 import AutoToc from './AutoToc';
 
-if (process.env.NODE_ENV === 'development') {
-  /* eslint-disable-next-line global-require */
-  require('~paragon-style/scss/core/core.scss');
-}
-
 export interface ILayout {
   children: React.ReactNode,
   showMinimizedTitle: boolean,
diff --git a/www/src/components/_doc-elements.scss b/www/src/components/_doc-elements.scss
index e2c29574f2..94d3e937cd 100644
--- a/www/src/components/_doc-elements.scss
+++ b/www/src/components/_doc-elements.scss
@@ -324,3 +324,9 @@
 .pgn-doc__box-shadow-toolkit--controls-box--remove-btn svg {
   color: var(--pgn-color-white);
 }
+
+.color-palette {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(19rem, 1fr));
+  grid-row-gap: 2rem;
+}
diff --git a/www/src/pages/foundations/colors.tsx b/www/src/pages/foundations/colors.tsx
index c0da271087..695243d62d 100644
--- a/www/src/pages/foundations/colors.tsx
+++ b/www/src/pages/foundations/colors.tsx
@@ -2,10 +2,8 @@ import React, { useContext } from 'react';
 import { graphql } from 'gatsby';
 import PropTypes from 'prop-types';
 import classNames from 'classnames';
-import Color from 'color';
 import { Container, DataTable } from '~paragon-react';
 import SEO from '../../components/SEO';
-import MeasuredItem from '../../components/MeasuredItem';
 import Layout from '../../components/PageLayout';
 import { SettingsContext } from '../../context/SettingsContext';
 
@@ -52,36 +50,36 @@ function parseColors(cssSelectors: { selector: string; declarations: string; }[]
   });
 }
 
+export type CSSStyleDeclarationType = CSSStyleDeclaration | null;
+
 export interface ISwatch {
   name: string,
   colorClassName: string,
   isUnused?: boolean,
+  styles: CSSStyleDeclarationType,
 }
 
-function Swatch({ name, colorClassName, isUnused }: ISwatch) {
+function Swatch({
+  name, colorClassName, isUnused, styles,
+}: ISwatch) {
+  const computedValue = styles?.getPropertyValue(name);
+
   return (
     <div className="d-flex align-items-center mb-2">
-      <MeasuredItem
-        properties={['background-color']}
-        renderAfter={(measurements: { [x: string]: JSX.Element; }) => (
-          <div style={{ lineHeight: 1 }} className="small">
-            <code className="mb-0 d-block text-lowercase text-dark-700">
-              {name}
-            </code>
-            {measurements['background-color'] && (
-            <code style={{ fontSize: '65%' }} className="text-muted">
-              {Color(measurements['background-color']).hex()}
-            </code>
-            )}
-          </div>
-        )}
-      >
-        <div
-          className={classNames('p-3 mr-2 rounded', colorClassName, {
-            'unused-level': isUnused,
-          })}
-        />
-      </MeasuredItem>
+      <div
+        className={classNames('p-3 mr-2 rounded', colorClassName, {
+          'unused-level': isUnused,
+        })}
+      />
+      <div style={{ lineHeight: 1 }} className="small">
+        <code className="mb-0 d-block text-lowercase text-dark-700">
+          {`var(${name})`}
+        </code>
+
+        <code style={{ fontSize: '65%' }} className="text-muted">
+          {computedValue}
+        </code>
+      </div>
     </div>
   );
 }
@@ -96,18 +94,18 @@ Swatch.defaultProps = {
   isUnused: false,
 };
 
-const renderColorRamp = (themeName: string, unusedLevels: number[]) => (
+const renderColorRamp = (themeName: string, unusedLevels: number[], styles: CSSStyleDeclarationType) => (
   <div
     key={`${themeName}`}
-    style={{ flexBasis: '24%', marginRight: '1%', marginBottom: '2rem' }}
   >
     <p className="h5">{themeName}</p>
     {levels.map(level => (
       <Swatch
-        key={`$${themeName}-${level}`}
-        name={`$${themeName}-${level}`}
+        key={`${themeName}-${level}`}
+        name={`--pgn-color-${themeName}-${level}`}
         colorClassName={utilityClasses.bg(themeName, level)}
         isUnused={unusedLevels.includes(level)}
+        styles={styles}
       />
     ))}
   </div>
@@ -124,6 +122,8 @@ export interface IColorsPage {
 // eslint-disable-next-line react/prop-types
 export default function ColorsPage({ data }: IColorsPage) {
   const { settings } = useContext(SettingsContext);
+  const styles = typeof window !== 'undefined' ? getComputedStyle(document.body) : null;
+
   parseColors(data.allCssUtilityClasses.nodes); // eslint-disable-line react/prop-types
 
   return (
@@ -132,123 +132,45 @@ export default function ColorsPage({ data }: IColorsPage) {
       <SEO title="Colors" />
       <Container size={settings.containerWidth} className="py-5">
         <h1>Colors</h1>
-        <div className="d-flex flex-wrap">
+        <div className="color-palette mb-3">
           {colors
             .slice(0, 3)
-            .map(({ themeName, unusedLevels }) => renderColorRamp(themeName, unusedLevels))}
-          <div
-            style={{
-              flexBasis: '19%',
-              marginRight: '1%',
-              marginBottom: '2rem',
-            }}
-          >
+            .map(({ themeName, unusedLevels }) => renderColorRamp(themeName, unusedLevels, styles))}
+          {colors
+            .slice(3)
+            .map(({ themeName, unusedLevels }) => renderColorRamp(themeName, unusedLevels, styles))}
+          <div>
             <p className="h5">accents</p>
 
-            <Swatch name="$accent-a" colorClassName="bg-accent-a" />
-            <Swatch name="$accent-b" colorClassName="bg-accent-b" />
+            <Swatch name="--pgn-color-accent-a" colorClassName="bg-accent-a" styles={styles} />
+            <Swatch name="--pgn-color-accent-b" colorClassName="bg-accent-b" styles={styles} />
           </div>
-
-          {colors
-            .slice(3)
-            .map(({ themeName, unusedLevels }) => renderColorRamp(themeName, unusedLevels))}
         </div>
 
-        <h3>SCSS Color Usage</h3>
-        <p>Include these colors in scss files in one of two ways:</p>
+        <h3>CSS Color Usage</h3>
 
         <h4>Variable name</h4>
         <code className="d-block mb-4 lead bg-gray-100 p-3">
-          {'// $color_name-level '}
+          {'// var(--pgn-color-name-level) '}
           <br />
-          $primary-100
+          var(--pgn-color-primary-100)
           <br />
-          $primary-200
+          var(--pgn-color-primary-200)
           <br />
-          $brand-100
+          var(--pgn-color-brand-100)
           <br />
-          $brand-200
-        </code>
-
-        <h4>Mixin (deprecated)</h4>
-        <code className="d-block mb-4 lead bg-gray-100 p-3">
-          theme-color($color-name, $variant)
+          var(--pgn-color-brand-200)
         </code>
 
+        <h4>With default value</h4>
         <p>
-          Using the variable name instead of the theme-color mixin will make
-          later upgrade paths easier. Paragon may begin to adopt CSS variables
-          for theming and attempt to eliminate mixins from the public api.
+          Using a default value in CSS variables allows to set a default value for a variable,
+          which will be used if the primary value of the variable is not defined or not available.
         </p>
-
-        <table className="pgn-doc__table mb-2">
-          <tbody>
-            <tr>
-              <td className="p-3">
-                <strong>Color Name</strong>
-                <br />A theme color
-              </td>
-              <td className="p-3 align-baseline">
-                {colors.map(({ themeName }) => (
-                  <code key={themeName} className="mr-2">
-                    {themeName}
-                  </code>
-                ))}
-              </td>
-            </tr>
-            <tr>
-              <td className="p-3 align-baseline">
-                <strong>Variant</strong>
-                <br />
-                <p>A number level or element type</p>
-              </td>
-              <td className="p-3">
-                <strong className="d-block">Levels </strong>
-                {levels.map((level) => (
-                  <code key={level} className="mr-2">
-                    {level}
-                  </code>
-                ))}
-                <br />
-                <strong className="d-block">Element types </strong>
-                {[
-                  'background',
-                  'disabled-border',
-                  'border',
-                  'icon',
-                  'active-border',
-                  'focus',
-                  'graphic',
-                  'default',
-                  'light-text',
-                  'hover',
-                  'text',
-                  'active',
-                  'dark-text',
-                ].map((element) => (
-                  <code key={element} className="mr-2">
-                    {element}
-                  </code>
-                ))}
-              </td>
-            </tr>
-          </tbody>
-        </table>
-
-        <h4>Example</h4>
-        <code className="d-block mb-2 bg-gray-100 p-3">
-          border: solid 1px <strong>$gray-300</strong>;
-        </code>
-
-        <code className="d-block mb-2 bg-gray-100 p-3">
-          border: solid 1px{' '}
-          <strong>theme-color(&ldquo;gray&rdquo;, &ldquo;border&rdquo;)</strong>
-          ;
-        </code>
-
-        <code className="d-block mb-4 bg-gray-100 p-3">
-          border: solid 1px{' '}
-          <strong>theme-color(&ldquo;gray&rdquo;, 300)</strong>;
+        <code className="d-block mb-4 lead bg-gray-100 p-3">
+          {'// var(--pgn-color-name-level), default variable '}
+          <br />
+          var(--pgn-color-brand-100, var(--pgn-color-primary-200))
         </code>
 
         <h3>CSS Class Utilities</h3>