@openedx/paragon 22.4.0 → 23.0.0-alpha.1

package/tokens/README.md

@@ -0,0 +1,158 @@
+# Design Tokens
+
+This module is responsible for handling design tokens in Paragon, for rationale behind design tokens see [Scaling Paragon's styles architecture with design tokens](https://openedx.atlassian.net/wiki/spaces/BPL/pages/3630923811/Scaling+Paragon+s+styles+architecture+with+design+tokens)
+and relevant ADR(TODO: add link when we merge an ADR). 
+
+## Overview
+
+We heavily rely on [style-dictionary](https://github.com/amzn/style-dictionary) package to build design tokens into various formats,
+it is recommended to read their [documentation](https://amzn.github.io/style-dictionary/#/) as well to know more about the package since we mostly focus on Paragon specifics in this document.
+
+All tokens are located in `src` directory and divided into three categories. We try to follow CTI token naming as described [here](https://amzn.github.io/style-dictionary/#/tokens?id=category-type-item), but our schema does have some differences, see tokens files for an example of that
+
+## Token modifications
+
+Style dictionary allows you to apply certain modifications to tokens during build time, e.g. if you want to make some color darker without
+manually calculating its value or trying to modify it with SASS functions after the variable has been built (note
+that most SASS functions will not work with CSS variables as SASS does not know values during compile time).
+
+All modifications need to be specified with `modify` key when describing a token, e.g.
+```
+{
+  "value": "#D4F880",
+  "modify": [{
+    "type": "darken"
+    "amount": 0.1
+  }]
+}
+```
+`modify` expects a list of modification to apply, each modification is specified with an object that carries necessary metadata, see examples below.
+
+### Color transforms
+
+Paragon uses [chroma-js](https://gka.github.io/chroma.js/) library to perform color modifications. Some of the most common examples are:
+
+1. `darken` – change lightness of a color (same behaviour as in respective SASS function), e.g.
+    ```
+    {
+      "value": "#D4F880",
+      "modify": [{
+        "type": "darken"
+        "amount": 0.1
+      }]
+    }
+    ```
+    outputs `#CFF37B` value
+
+2. `mix` – mix two colors with specific ratio (same behaviour as in respective SASS function), e.g.
+   ```
+   {
+     "value": "#0A3055",
+     "modify": [
+       {
+         "type": "mix",
+         "otherColor": "#FFF",
+         "amount": "0.6"
+       }
+     ]
+   }
+   ```
+   outputs `#9DACBB` value
+
+3. `color-yiq` – [Bootstrap's color contrast function](https://getbootstrap.com/docs/4.0/getting-started/theming/#color-contrast) that outputs black (defaults to `#454545`) or white (defaults to `#FFF`) color depending on the specified base color, e.g.
+   ```
+   {
+     "value": "#0A3055",
+     "modify": [{ "type": "color-yiq" }]
+   }
+   ```
+   outputs `#454545`
+
+Generally every function from `chroma-js` that has similar signature to `darken` function (i.e., first argument is color value and second is amount by which the color should be changed) can be applied to color tokens the same way as `darken` is applied, functions with other signatures are not currently supported except for the `mix`.
+
+### Other transforms
+
+Currently, only one other transform is supported – `str-replace`, that replaces some string with another one across the whole token value, common usage is for values that represent an SVG image
+
+```
+{
+  "value": "url("data:image/svg+xml,<svg><path d='somesvg' fill='{color.primary.base.value}'/></svg>\")",
+  "modify": [{
+    "type": "str-replace",
+    "toReplace": "#",
+    "replaceWith": "%23"
+  }]
+}
+```
+Without `str-replace` the resulting value would be `url("data:image/svg+xml,<svg><path d='somesvg' fill='#0A3055'/></svg>\"`, note that fill color starts with `#` symbol which would cause image to render invalid color, by using `str-replace` fill would become `%230A3055` and the image would render correctly.
+
+## Outputting references
+
+By default, tokens keep references in the output, meaning having such tokens structure
+```
+{
+  "color": {
+    "green": { "value": "#178253" },
+    "success": { "value": "{color.green.value}" }
+}
+```
+the outputted values will be
+```
+--pgn-color-green: #178253,
+--pgn-color-success: var(--pgn-color-green)
+```
+which is usually fine, but you might want to disable this behaviour for some tokens.
+
+Style dictionary uses a simple algorithm while outputting references, i.e. it checks whether outputted value contains any known tokens and replaces them with references to that token, e.g.
+if you have token with value `url("data:image/svg+xml,<svg><path d='somesvg' fill='{color.green.value}'/></svg>\")` then style dictionary would transform it into
+`url("data:image/svg+xml,<svg><path d='somesvg' fill='var(--pgn-color-green)'/></svg>\")` which will obviously not work when rendered, and you get broken SVG.
+
+To disable this feature for specific token use `outputReferences` flag, e.g.
+```
+{
+  "value": "url("data:image/svg+xml,<svg><path d='somesvg' fill='{color.green.value}'/></svg>\")",
+  "outputReferences": false,
+  "modify": [{
+    "type": "str-replace",
+    "toReplace": "#",
+    "replaceWith": "%23"
+  }]
+}
+```
+this will correctly output `url("data:image/svg+xml,<svg><path d='somesvg' fill='%23178253'/></svg>")`
+
+## Utility Classes
+
+Style Dictionary is also able to generate CSS utility classes using design tokens, although currently it is not very-well supported, and you might be better off to just hardcode CSS classes without using Style Dictionary.
+Nevertheless, in some cases it might be useful.
+
+The configuration to do build CSS classes lives in `src/utilities` directory in JSON files, let's take `color.json` as an example and see what it does. Its contents should look something like this:
+```
+{
+  "utilities": [
+    {
+      "filters": {
+        "category": ["color"],
+        "type": ["gray", "primary", "secondary", "brand", "success", "info", "warning", "danger", "light", "dark", "accent"],
+        "item": ["base", "100", "200", "300", "400", "500", "600", "700", "800", "900", "a", "b"]
+      },
+      "utilityFunctionsToApply": ["bgVariant", "textEmphasisVariant", "borderColor"]
+    }
+  ]
+}
+```
+Namely, this is a JSON object with only one key (`utilities`, this is how Style Dictionary knows that this file is used for generating utility classes)
+and one value which is an array of objects that describe how to generate classes and which tokens to use.
+Each such object is composed of 2 keys:
+ - `utilityFunctionsToApply`, which is an array of strings, these strings are the names of functions that will
+   generate utility classes based on tokens. These functions must be defined in `css-utilities.js` module and must follow 
+   the same signature - accept `token` object as its only argument and output CSS class as a string (see any of `bgVariant`, `textEmphasisVariant`, `borderColor` functions for an example)
+ - `filters`, which is an object that describes which tokens will be passed as an argument to functions provided by `utilityFunctionsToApply`.
+   The keys in this object are the attributes of a `token` object and values are arrays of valid values that tokens will be filtered against.
+   For list of possible keys see https://amzn.github.io/style-dictionary/#/tokens?id=category-type-item
+
+Basically, this file tells Style Dictionary to generate utility classes using `["bgVariant", "textEmphasisVariant", "borderColor"]`
+functions from tokens that are of `color` category and theirs `type` is one of `["gray", "primary", ...]`
+and `item` is one of `["base", "100", "200", ...]`.
+
+If you want to generate additional utility classes you need to add a similar JSON file to `src/utilities` directory.

package/tokens/css-utilities.js

@@ -0,0 +1,56 @@
+/**
+ * Implements bg-variant mixin from bootstrap. Creates utility classes for background colors based on theme color.
+ */
+function bgVariant(token) {
+  const { attributes: { type, item }, name, actions } = token;
+  const parent = `.bg-${type}${item === 'base' ? '' : `-${item}`}`;
+  return `${parent} {
+  background-color: ${`var(--${name})`} !important;
+}
+
+a${parent}:hover,
+a${parent}:focus,
+button${parent}:hover,
+button${parent}:focus {
+  background-color: ${actions.default} !important;
+}
+
+`;
+}
+
+/**
+ * Implements text-emphasis-variant mixin from bootstrap. Creates utility classes for text colors based on theme color.
+ */
+function textEmphasisVariant(token) {
+  const { attributes: { type, item }, name, actions } = token;
+  const parent = `.text-${type}${item === 'base' ? '' : `-${item}`}`;
+  return `${parent} {
+  color: ${`var(--${name})`} !important;
+}
+
+a${parent}:hover,
+a${parent}:focus {
+  color: ${actions.default} !important;
+}
+
+`;
+}
+
+/**
+ * Creates utility class for border color.
+ */
+function borderColor(token) {
+  const { attributes: { type, item }, name } = token;
+  const className = `.border-${type}${item === 'base' ? '' : `-${item}`}`;
+  return `${className} {
+  border-color: ${`var(--${name})`} !important;
+}
+
+`;
+}
+
+module.exports = {
+  bgVariant,
+  textEmphasisVariant,
+  borderColor,
+};

package/tokens/map-scss-to-css.js

@@ -0,0 +1,24 @@
+const fs = require('fs');
+const path = require('path');
+const { getSCSStoCSSMap, getFilesWithExtension } = require('./utils');
+
+const BASE_PATH = path.resolve(__dirname, './src');
+const TOKEN_PREFIX = '--pgn';
+
+function mapSCSStoCSS(sourcePath) {
+  const SCSStoCSSMap = {};
+  const tokenPaths = getFilesWithExtension(BASE_PATH, '.json');
+  if (sourcePath) {
+    tokenPaths.push(...getFilesWithExtension(sourcePath, '.json'));
+  }
+
+  tokenPaths.forEach(tokenFile => {
+    const tokenContent = fs.readFileSync(tokenFile, 'utf-8');
+    const parsed = JSON.parse(tokenContent);
+    getSCSStoCSSMap(TOKEN_PREFIX, parsed, SCSStoCSSMap);
+  });
+
+  return SCSStoCSSMap;
+}
+
+module.exports = mapSCSStoCSS;

package/tokens/replace-variables.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+const { program, Option } = require('commander');
+const { transformInPath } = require('./utils');
+const mapSCSStoCSS = require('./map-scss-to-css');
+
+program
+  .version('0.0.1')
+  .description('CLI to replace SCSS variables usages or definitions to CSS variables and vice versa in .scss files.')
+  .requiredOption('-p, --filePath <filePath>', 'Path to the file or directory where to replace variables.')
+  .addOption(new Option('-s, --source <sourcePath>', 'Type of replacement: usage or definition. If set to "definition" the command will only update SCSS variables definitions with CSS variables, if set to "usage" - all occurrences of SCSS variables will we replaced'))
+  .addOption(new Option('-t, --replacementType <replacementType>', 'Type of replacement: usage or definition. If set to "definition" the command will only update SCSS variables definitions with CSS variables, if set to "usage" - all occurrences of SCSS variables will we replaced')
+    .choices(['usage', 'definition'])
+    .default('definition'))
+  .addOption(new Option('-d, --direction <name>', 'Map direction: css-to-scss or scss-to-css, if replacement type parameter is set to "definition" this has no effect.')
+    .choices(['scss-to-css', 'css-to-scss'])
+    .default('scss-to-css'))
+  .action(async (options) => {
+    const {
+      direction,
+      filePath,
+      replacementType,
+      source,
+    } = options;
+    const variablesMap = mapSCSStoCSS(source);
+    if (replacementType === 'usage') {
+      await transformInPath(filePath, variablesMap, 'usage', [], direction);
+    } else {
+      await transformInPath(filePath, variablesMap);
+    }
+  });
+
+program.parse(process.argv);

package/tokens/sass-helpers.js

@@ -0,0 +1,98 @@
+const path = require('path');
+const fs = require('fs');
+const chroma = require('chroma-js');
+const chalk = require('chalk');
+
+/**
+ * Javascript version of bootstrap's color-yiq function. Decides whether to return light color variant or dark one
+ * based on contrast value of the input color
+ *
+ * @param {Object} args
+ * @param {Object} args.tokenName - Name of design token, used to log warnings
+ * @param {Object} args.backgroundColor - chroma-js color instance
+ * @param {String} args.light - light color variant from ./src/themes/{themeVariant}/global/other.json
+ * @param {String} args.dark - dark color variant from ./src/themes/{themeVariant}/global/other.json
+ * @param {Number} args.threshold - contrast threshold from ./src/core/global/other.json
+ * @param {String} [args.themeVariant] - theme variant name that will be used to find default contrast colors
+ *
+ * @return chroma-js color instance (one of dark or light variants)
+ */
+function colorYiq({
+  tokenName,
+  backgroundColor,
+  light,
+  dark,
+  threshold,
+  themeVariant = 'light',
+}) {
+  const defaultThresholdFile = fs.readFileSync(path.resolve(__dirname, 'src/core/global', 'other.json'), 'utf8');
+  const defaultThreshold = JSON.parse(defaultThresholdFile)['yiq-contrasted-threshold'];
+
+  const defaultColorsFile = fs.readFileSync(path.resolve(__dirname, `src/themes/${themeVariant}/global`, 'other.json'), 'utf8');
+  const {
+    'yiq-text-dark': defaultDark,
+    'yiq-text-light': defaultLight,
+  } = JSON.parse(defaultColorsFile);
+
+  const contrastThreshold = threshold || defaultThreshold;
+  const lightColor = light || defaultLight;
+  const darkColor = dark || defaultDark;
+
+  const [r, g, b] = backgroundColor.rgb();
+  const yiq = ((r * 299) + (g * 587) + (b * 114)) * 0.001;
+
+  let result = yiq >= contrastThreshold ? chroma(darkColor) : chroma(lightColor);
+
+  const maxAttempts = 10; // maximum number of attempts to darken/brighten color to pass contrast ratio
+  if (yiq >= contrastThreshold) {
+    // check whether the resulting combination of colors passes a11y contrast ratio of 4:5:1
+    // if not - darken resulting color until it does until maxAttempts is reached.
+    let numDarkenAttempts = 1;
+    while (chroma.contrast(backgroundColor, result) < 4.5 && numDarkenAttempts <= maxAttempts) {
+      result = result.darken(0.1);
+      numDarkenAttempts += 1;
+      if (numDarkenAttempts === maxAttempts) {
+        const title = `[a11y] Warning: Failed to sufficiently darken token ${chalk.keyword('orange').bold(tokenName)} to pass contrast ratio of 4.5:1.`;
+        const warningMetadata = [
+          `Background color: ${backgroundColor.hex()}`,
+          `Attempted foreground color: ${result.hex()}`,
+        ].join('\n    ');
+        const warn = `${title}\n    ${warningMetadata}`;
+        // eslint-disable-next-line no-console
+        console.log(chalk.keyword('yellow').bold(warn));
+      }
+    }
+    return result;
+  }
+
+  // check whether the resulting combination of colors passes a11y contrast ratio of 4:5:1
+  // if not - brighten resulting color until it does until maxAttempts is reached.
+  let numBrightenAttempts = 1;
+  while (chroma.contrast(backgroundColor, result) < 4.5 && numBrightenAttempts <= maxAttempts) {
+    result = result.brighten(0.1);
+    numBrightenAttempts += 1;
+    if (numBrightenAttempts === maxAttempts) {
+      const title = `[a11y] Warning: Failed to sufficiently brighten token ${chalk.keyword('orange').bold(tokenName)} to pass contrast ratio of 4.5:1.`;
+      const warningMetadata = [
+        `Background color: ${backgroundColor.hex()}`,
+        `Attempted foreground color: ${result.hex()}`,
+      ].join('\n    ');
+      const warn = `${title}\n    ${warningMetadata}`;
+      // eslint-disable-next-line no-console
+      console.log(chalk.keyword('yellow').bold(warn));
+    }
+  }
+  return result;
+}
+
+/**
+ * Overrides chroma-js's lighten / darken functions to behave the same way SASS functions do.
+ */
+const lighten = (color, hslPercent) => color.set('hsl.l', color.get('hsl.l') + hslPercent);
+const darken = (color, hslPercent) => lighten(color, -hslPercent);
+
+module.exports = {
+  colorYiq,
+  darken,
+  lighten,
+};

package/tokens/src/core/alias/size.json

@@ -0,0 +1,15 @@
+{
+  "size": {
+    "border": {
+      "width": { "value": "1px", "type": "dimension", "source": "$border-width", "description": "Default border width." },
+      "radius": {
+        "base": { "value": "6px", "type": "dimension", "source": "$border-radius", "description": "Default border radius." },
+        "lg": { "value": "7px", "type": "dimension", "source": "$border-radius-lg", "description": "Large border radius." },
+        "sm": { "value": "4px", "type": "dimension", "source": "$border-radius-sm", "description": "Small border radius." }
+      }
+    },
+    "rounded": {
+      "pill": { "value": "50rem", "type": "dimension", "source": "$rounded-pill", "description": "Pill border radius." }
+    }
+  }
+}

package/tokens/src/core/components/ActionRow.json

@@ -0,0 +1,10 @@
+{
+  "spacing": {
+    "action-row": {
+      "gap": {
+        "x": { "value": ".5rem", "type": "dimension", "source": "$action-row-gap-x" },
+        "y": { "value": ".5rem", "type": "dimension", "source": "$action-row-gap-y" }
+      }
+    }
+  }
+}

package/tokens/src/core/components/Alert.json

@@ -0,0 +1,30 @@
+{
+  "spacing": {
+    "alert": {
+      "padding": {
+        "y": { "value": "1.5rem", "type": "dimension", "source": "$alert-padding-y" },
+        "x": { "value": "1.5rem", "type": "dimension", "source": "$alert-padding-x" }
+      },
+      "margin-bottom": { "value": "1rem", "type": "dimension", "source": "$alert-margin-bottom" },
+      "actions-gap": { "value": "{spacing.spacer.3}", "type": "dimension", "source": "$alert-actions-gap" },
+      "icon-space": { "value": ".8rem", "type": "dimension", "source": "$alert-icon-space" }
+    }
+  },
+  "typography": {
+    "alert": {
+      "font": {
+        "weight-link": { "value": "{typography.font.weight.normal}", "type": "fontWeight", "source": "$alert-link-font-weight" },
+        "size": { "value": ".875rem", "type": "dimension", "source": "$alert-font-size" }
+      },
+      "line-height": { "value": "1.5rem", "type": "dimension", "source": "$alert-line-height" }
+    }
+  },
+  "size": {
+    "alert": {
+      "border": {
+        "radius": { "value": "{size.border.radius.base}", "type": "dimension", "source": "$alert-border-radius" },
+        "width": { "value": "0", "type": "dimension", "source": "$alert-border-width" }
+      }
+    }
+  }
+}

package/tokens/src/core/components/Annotation.json

@@ -0,0 +1,25 @@
+{
+  "spacing": {
+    "annotation": {
+      "padding": { "value": ".5rem", "type": "dimension", "source": "$annotation-padding" },
+      "arrow-side": {
+        "margin": { "value": ".25rem", "type": "dimension", "source": "$annotation-arrow-side-margin" }
+      }
+    }
+  },
+  "typography": {
+    "annotation": {
+      "font-size": { "value": "{typography.font.size.sm}", "type": "dimension", "source": "$annotation-font-size" },
+      "line-height": { "value": "{typography.line-height.sm}", "type": "dimension", "source": "$annotation-line-height" }
+    }
+  },
+  "size": {
+    "annotation": {
+      "arrow-border": {
+        "width": { "value": ".5rem", "type": "dimension", "source": "$annotation-arrow-border-width" }
+      },
+      "max-width": { "value": "18.75rem", "type": "dimension", "source": "$annotation-max-width" },
+      "border-radius": { "value": ".25rem", "type": "dimension", "source": "$annotation-border-radius" }
+    }
+  }
+}

package/tokens/src/core/components/Avatar.json

@@ -0,0 +1,17 @@
+{
+  "size": {
+    "avatar": {
+      "base": { "value": "3rem", "type": "dimension", "source": "$avatar-size" },
+      "xs": { "value": "1.5rem", "type": "dimension", "source": "$avatar-size-xs" },
+      "sm": { "value": "2.25rem", "type": "dimension", "source": "$avatar-size-sm" },
+      "lg": { "value": "4rem", "type": "dimension", "source": "$avatar-size-lg" },
+      "xl": { "value": "6rem", "type": "dimension", "source": "$avatar-size-xl" },
+      "xxl": { "value": "11.5rem", "type": "dimension", "source": "$avatar-size-xxl" },
+      "huge": { "value": "18.75rem", "type": "dimension", "source": "$avatar-size-huge" },
+      "border": {
+        "base": { "value": "1px", "type": "dimension", "source": "$avatar-border" },
+        "radius": { "value": "100%", "type": "percentage", "source": "$avatar-border-radius" }
+      }
+    }
+  }
+}

package/tokens/src/core/components/AvatarButton.json

@@ -0,0 +1,11 @@
+{
+  "spacing": {
+    "avatar-button": {
+      "padding-left": {
+        "base": { "value": ".25em", "type": "dimension", "source": "$avatar-button-padding-left" },
+        "sm": { "value": ".25em", "type": "dimension", "source": "$avatar-button-padding-left-sm" },
+        "lg": { "value": ".25em", "type": "dimension", "source": "$avatar-button-padding-left-lg" }
+      }
+    }
+  }
+}

package/tokens/src/core/components/Badge.json

@@ -0,0 +1,33 @@
+{
+  "spacing": {
+    "badge": {
+      "padding": {
+        "x": {
+          "base": { "value": ".5rem", "type": "dimension", "source": "$badge-padding-x" },
+          "pill": { "value": ".6em", "type": "dimension", "source": "$badge-pill-padding-x" }
+        },
+        "y": { "value": ".125rem", "type": "dimension", "source": "$badge-padding-y" }
+      }
+    }
+  },
+  "typography": {
+    "badge": {
+      "font": {
+        "size": { "value": "75%", "type": "percentage", "source": "$badge-font-size" },
+        "weight": { "value": "{typography.font.weight.bold}", "type": "fontWeight", "source": "$badge-font-weight" }
+      }
+    }
+  },
+  "size": {
+    "badge": {
+      "border-radius": {
+        "base": { "value": ".25rem", "type": "dimension", "source": "$badge-border-radius" },
+        "pill": { "value": "10rem", "type": "dimension", "source": "$badge-pill-border-radius" }
+      },
+      "focus-width": { "value": "{size.input.btn.focus-width}", "type": "dimension", "source": "$badge-focus-width" }
+    }
+  },
+  "transition": {
+    "badge": { "value": "none", "type": "transition", "source": "$badge-transition" }
+  }
+}

package/tokens/src/core/components/Breadcrumb.json

@@ -0,0 +1,37 @@
+{
+  "typography": {
+    "breadcrumb": {
+      "font-size": { "value": "inherit", "type": "dimension", "source": "$breadcrumb-font-size" }
+    }
+  },
+  "spacing": {
+    "breadcrumb": {
+      "padding": {
+        "y": { "value": ".75rem", "type": "dimension", "source": "$breadcrumb-padding-y" },
+        "x": { "value": "1rem", "type": "dimension", "source": "$breadcrumb-padding-x" },
+        "item": { "value": ".5rem", "type": "dimension", "source": "$breadcrumb-item-padding" }
+      },
+      "margin": {
+        "bottom": { "value": "1rem", "type": "dimension", "source": "$breadcrumb-margin-bottom" },
+        "left": { "value": ".5rem", "type": "dimension", "source": "$breadcrumb-margin-left" }
+      }
+    }
+  },
+  "size": {
+    "breadcrumb": {
+      "border": {
+        "radius": {
+          "base": {
+            "value": "{size.border.radius.base}", "type": "dimension", "source": "$breadcrumb-border-radius"
+          },
+          "focus": { "value": ".125rem", "type": "dimension", "source": "$breadcrumb-focus-border-radius" }
+        },
+        "axis": {
+          "x-focus": { "value": ".25rem", "type": "dimension", "source": "$breadcrumb-border-focus-axis-x" },
+          "y-focus": { "value": ".5rem", "type": "dimension", "source": "$breadcrumb-border-focus-axis-y" }
+        },
+        "width-focus": { "value": ".0625rem", "type": "dimension", "source": "$breadcrumb-border-focus-width" }
+      }
+    }
+  }
+}

package/tokens/src/core/components/Bubble.json

@@ -0,0 +1,10 @@
+{
+  "spacing": {
+    "bubble": {
+      "expandable-padding": {
+        "y": { "value": "0", "type": "transition", "source": "$bubble-expandable-padding-y" },
+        "x": { "value": ".25rem", "type": "transition", "source": "$bubble-expandable-padding-x" }
+      }
+    } 
+  }
+}