@madgex/design-system 9.3.0 → 10.0.0

package/src/tokens/typography.json

@@ -1,206 +1,212 @@
 {
   "font": {
     "family": {
+      "$type": "fontFamily",
       "base": {
-        "value": "\"Helvetica\", Arial, sans-serif"
+        "$value": "\"Helvetica\", Arial, sans-serif"
       },
       "heading": {
         "base": {
-          "value": "{font.family.base.value}"
+          "$value": "{font.family.base}"
         },
         "1": {
-          "value": "{font.family.heading.base.value}"
+          "$value": "{font.family.heading.base}"
         },
         "2": {
-          "value": "{font.family.heading.base.value}"
+          "$value": "{font.family.heading.base}"
         },
         "3": {
-          "value": "{font.family.heading.base.value}"
+          "$value": "{font.family.heading.base}"
         }
       },
       "button": {
         "base": {
-          "value": "{font.family.base.value}"
+          "$value": "{font.family.base}"
         }
       }
     },
     "weight": {
+      "$type": "fontWeight",
       "base": {
-        "value": "400"
+        "$value": "400"
       },
       "heading": {
         "base": {
-          "value": "{font.weight.base.value}"
+          "$value": "{font.weight.base}"
         },
         "1": {
-          "value": "{font.weight.heading.base.value}"
+          "$value": "{font.weight.heading.base}"
         },
         "2": {
-          "value": "{font.weight.heading.base.value}"
+          "$value": "{font.weight.heading.base}"
         },
         "3": {
-          "value": "{font.weight.heading.base.value}"
+          "$value": "{font.weight.heading.base}"
         }
       },
       "button": {
         "base": {
-          "value": "{font.weight.base.value}"
+          "$value": "{font.weight.base}"
         }
       },
       "link": {
         "base": {
-          "value": "inherit"
+          "$value": "inherit"
         }
       }
     },
     "spacing": {
+      "$type": "letterSpacing",
       "base": {
-        "value": "normal"
+        "$value": "normal"
       },
       "heading": {
         "base": {
-          "value": "{font.spacing.base.value}"
+          "$value": "{font.spacing.base}"
         },
         "1": {
-          "value": "{font.spacing.heading.base.value}"
+          "$value": "{font.spacing.heading.base}"
         },
         "2": {
-          "value": "{font.spacing.heading.base.value}"
+          "$value": "{font.spacing.heading.base}"
         },
         "3": {
-          "value": "{font.spacing.heading.base.value}"
+          "$value": "{font.spacing.heading.base}"
         }
       },
       "button": {
-        "value": "{font.spacing.base.value}"
+        "$value": "{font.spacing.base}"
       }
     },
     "type": {
+      "$type": "dimension",
       "s-2": {
         "size": {
-          "value": "0.75rem"
+          "$value": "0.75rem"
         },
-        "line-height": { 
-          "value": "1.35" 
+        "line-height": {
+          "$value": "1.35"
         }
       },
       "s-1": {
         "size": {
-          "value": "0.875rem"
+          "$value": "0.875rem"
         },
-        "line-height": { 
-          "value": "1.35" 
+        "line-height": {
+          "$value": "1.35"
         }
       },
       "s0": {
         "size": {
-          "value": "1rem"
+          "$value": "1rem"
         },
-        "line-height": { 
-          "value": "1.4" 
+        "line-height": {
+          "$value": "1.4"
         }
       },
       "s1": {
         "size": {
-          "value": "clamp(1.067rem, 1.0468rem + 0.1009vi, 1.125rem)"
+          "$value": "clamp(1.067rem, 1.0468rem + 0.1009vi, 1.125rem)"
         },
-        "line-height": { 
-          "value": "1.4" 
+        "line-height": {
+          "$value": "1.4"
         }
       },
       "s2": {
         "size": {
-          "value": "clamp(1.1385rem, 1.0943rem + 0.2211vi, 1.2656rem)"
+          "$value": "clamp(1.1385rem, 1.0943rem + 0.2211vi, 1.2656rem)"
         },
-        "line-height": { 
-          "value": "1.2" 
+        "line-height": {
+          "$value": "1.2"
         }
       },
       "s3": {
         "size": {
-          "value": "clamp(1.2148rem, 1.1421rem + 0.3636vi, 1.4238rem)"
+          "$value": "clamp(1.2148rem, 1.1421rem + 0.3636vi, 1.4238rem)"
         },
-        "line-height": { 
-          "value": "1.2" 
+        "line-height": {
+          "$value": "1.2"
         }
       },
       "s4": {
         "size": {
-          "value": "clamp(1.2962rem, 1.1898rem + 0.5316vi, 1.6018rem)"
+          "$value": "clamp(1.2962rem, 1.1898rem + 0.5316vi, 1.6018rem)"
         },
-        "line-height": { 
-          "value": "1.2" 
+        "line-height": {
+          "$value": "1.2"
         }
       },
       "s5": {
         "size": {
-          "value": "clamp(1.383rem, 1.2372rem + 0.7288vi, 1.802rem)"
+          "$value": "clamp(1.383rem, 1.2372rem + 0.7288vi, 1.802rem)"
         },
-        "line-height": { 
-          "value": "1.2" 
+        "line-height": {
+          "$value": "1.2"
         }
       },
       "s6": {
         "size": {
-          "value": "clamp(1.4757rem, 1.2838rem + 0.9593vi, 2.0273rem)"
+          "$value": "clamp(1.4757rem, 1.2838rem + 0.9593vi, 2.0273rem)"
         },
-        "line-height": { 
-          "value": "1.15" 
+        "line-height": {
+          "$value": "1.15"
         }
       },
       "s7": {
         "size": {
-          "value": "clamp(1.5745rem, 1.3289rem + 1.2281vi, 2.2807rem)"
+          "$value": "clamp(1.5745rem, 1.3289rem + 1.2281vi, 2.2807rem)"
         },
-        "line-height": { 
-          "value": "1.15" 
+        "line-height": {
+          "$value": "1.15"
         }
       },
       "s8": {
         "size": {
-          "value": "clamp(1.68rem, 1.3719rem + 1.5405vi, 2.5658rem)"
+          "$value": "clamp(1.68rem, 1.3719rem + 1.5405vi, 2.5658rem)"
         },
-        "line-height": { 
-          "value": "1.15" 
+        "line-height": {
+          "$value": "1.15"
         }
       },
       "s9": {
         "size": {
-          "value": "clamp(1.7926rem, 1.4121rem + 1.9025vi, 2.8865rem)"
+          "$value": "clamp(1.7926rem, 1.4121rem + 1.9025vi, 2.8865rem)"
         },
-        "line-height": { 
-          "value": "1.15" 
+        "line-height": {
+          "$value": "1.15"
         }
       }
     }
   },
   "text": {
     "transform": {
+      "$type": "textTransform",
       "heading": {
         "base": {
-          "value": "none"
+          "$value": "none"
         },
         "1": {
-          "value": "{text.transform.heading.base.value}"
+          "$value": "{text.transform.heading.base}"
         },
         "2": {
-          "value": "{text.transform.heading.base.value}"
+          "$value": "{text.transform.heading.base}"
         },
         "3": {
-          "value": "{text.transform.heading.base.value}"
+          "$value": "{text.transform.heading.base}"
         }
       },
       "button": {
-        "value": "none"
+        "$value": "none"
       }
     },
     "decoration": {
+      "$type": "textDecoration",
       "link": {
         "base": {
-          "value": "underline"
+          "$value": "underline"
         },
         "hover": {
-          "value": "underline"
+          "$value": "underline"
         }
       }
     }

package/style-dictionary/color-transforms.js

@@ -0,0 +1,143 @@
+const crypto = require('node:crypto');
+const path = require('node:path');
+const os = require('node:os');
+const fs = require('node:fs/promises');
+const { TinyColor } = require('@ctrl/tinycolor');
+
+const TRANSFORM_AMOUNTS = {
+  LIGHT: 10,
+  LIGHTEST: 95,
+  DARK: 10,
+  DARKEST: 12,
+};
+
+/**
+ * @typedef ColorGroupItem
+ * @type {object}
+ * @property {string} $value
+ */
+
+/**
+ * @typedef ColorGroupInput
+ * @type {object}
+ * @property {!ColorGroupItem} base
+ * @property {?ColorGroupItem} light
+ * @property {?ColorGroupItem} lightest
+ * @property {?ColorGroupItem} dark
+ * @property {?ColorGroupItem} darkest
+ */
+
+/**
+ * Replicates Sass lightness($color) function
+
+ * @param {TinyColor} color 
+ * @returns {number}
+ */
+function lightness(color) {
+  const { l } = color.toHsl();
+
+  return l * 100;
+}
+
+/**
+ * adds `light`, `lightest`, `dark` and `darkest` to a token colour group, derived from `colorGroup.base.$value`.
+ *
+ * If keys already exist, they are **not** overwritten.
+ *
+ * @param {ColorGroupInput} colorGroup {base, light?, lightest?, dark?, darkest? }
+ * @returns {ColorGroupInput} {base, light, lightest, dark, darkest }
+ */
+function createColorsFromBase(colorGroup) {
+  const { base = {}, light = {}, lightest = {}, dark = {}, darkest = {} } = colorGroup;
+  const asTinyColor = new TinyColor(base.$value);
+
+  return {
+    base,
+    light: {
+      ...light,
+      $value: light.$value || asTinyColor.lighten(TRANSFORM_AMOUNTS.LIGHT).toHexString(),
+    },
+    lightest: {
+      ...lightest,
+      $value: lightest.$value || asTinyColor.lighten(TRANSFORM_AMOUNTS.LIGHTEST - lightness(asTinyColor)).toHexString(),
+    },
+    dark: {
+      ...dark,
+      $value: dark?.$value || asTinyColor.darken(TRANSFORM_AMOUNTS.DARK).toHexString(),
+    },
+    darkest: {
+      ...darkest,
+      $value: darkest?.$value || asTinyColor.darken(lightness(asTinyColor) - TRANSFORM_AMOUNTS.DARKEST).toHexString(),
+    },
+  };
+}
+
+/**
+ * For each `tokensObject.color.brand.*`, add lightness tokens, if they dont already exist
+ *
+ * @param {object} tokensObject
+ * @returns {object} modified tokensObject
+ */
+function addBrandColorLightnessTokens(tokensObject) {
+  const { brand } = tokensObject.color;
+
+  return {
+    ...tokensObject,
+    color: {
+      ...tokensObject.color,
+      /**
+       * focus on `brand` object
+       *
+       * loop through all brand group keys e.g. "1", "2", "3"
+       *
+       * apply `createColorsFromBase` to each color group
+       */
+      brand: Object.keys(brand).reduce((accu, brandKey) => {
+        const colorGroup = brand[brandKey];
+        const populatedColorGroup = createColorsFromBase(colorGroup);
+        // eslint-disable-next-line no-param-reassign
+        accu[brandKey] = { ...colorGroup, ...populatedColorGroup };
+        return accu;
+      }, {}),
+    },
+  };
+}
+
+module.exports.addBrandColorLightnessTokens = addBrandColorLightnessTokens;
+
+/**
+ * Although `addBrandColorLightnessTokens` does the job of adding lighten tokens to `color.brand.*` JSON, this function purely
+ * exists to: read, transform, and then write the result to a new temporary file.
+ *
+ * For use in Style Dictionary `source` array. Style Dictionary only supports files written to disk for `source` 🥲
+ *
+ * @param {string} originalFilePath path to original tokens json file
+ * @returns {string} new file path
+ */
+async function writeTransformedFileBrandColorLightnessTokens(originalFilePath) {
+  // construct new unique temp file path name where we will save new json file to disk
+  const TMP_DIR = await fs.realpath(os.tmpdir());
+  const filename = path.parse(originalFilePath).name;
+  const newTempFilePath = path.join(
+    TMP_DIR,
+    `/madgex-design-system/${filename}-transformed-${crypto.randomUUID()}.json`
+  );
+  const tmpDirPath = path.dirname(newTempFilePath);
+
+  // create temp folder if it doesn't exist
+  try {
+    await fs.access(tmpDirPath);
+  } catch (error) {
+    await fs.mkdir(tmpDirPath, { recursive: true });
+  }
+
+  // read original tokens file
+  const colorTokens = await fs.readFile(originalFilePath, { encoding: 'utf8' });
+  // transform tokens
+  const transformed = JSON.stringify(addBrandColorLightnessTokens(JSON.parse(colorTokens)), null, '  ');
+  // write new file with transformed tokens
+  await fs.writeFile(newTempFilePath, transformed);
+  // return new file name for use in createStyleDictionary
+  return newTempFilePath;
+}
+module.exports.writeTransformedFileBrandColorLightnessTokens = writeTransformedFileBrandColorLightnessTokens;

package/style-dictionary/index.js

@@ -0,0 +1,215 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { glob } = require('glob');
+const { writeTransformedFileBrandColorLightnessTokens } = require('./color-transforms');
+
+const defaultDistDir = path.resolve(__dirname, '../dist/_tokens/');
+/**
+ * Base Style Dictionary Config which includes our base tokens.
+ * @type {import('style-dictionary').Config}
+ */
+const baseConfig = Object.freeze({
+  log: {
+    verbosity: 'verbose',
+  },
+  // This include path needs to be in posix because combineJSON util inside style dictionary only accepts that
+  include: [path.posix.resolve(__dirname, '../src/tokens/*.json')],
+  hooks: {
+    transforms: {
+      /**
+       * escape when we need to pass through the token value without transformation.
+       *
+       * Try not to use this.
+       *
+       * @example
+       * ```json
+       * {
+       *   "myStrangeItem": {
+       *     "$value": "special-new-css-value",
+       *     "$type": "raw"
+       *   }
+       * }
+       */
+      'css/rawData': {
+        type: 'value',
+        filter: (token) => token.type === 'raw',
+        transform: (token) => token.rawData,
+      },
+    },
+  },
+  /**
+   * various outputs
+   *
+   * transforms match the `type` on each token, built in transforms: https://styledictionary.com/reference/hooks/transforms/predefined/
+   *
+   *
+   */
+  platforms: {
+    /**
+     * Primary CSS Variables render
+     */
+    'css-variables': {
+      transforms: ['name/kebab', 'color/css', 'css/rawData'],
+      buildPath: path.join(defaultDistDir, 'css/'),
+      prefix: 'mds',
+      files: [
+        {
+          destination: 'variables.css',
+          format: 'css/variables',
+          filter: 'removePrivate',
+        },
+      ],
+    },
+    /**
+     * used to render another scss source file! Constants for use in main DS scss build
+     */
+    'scss-variables': {
+      transforms: ['name/kebab'],
+      buildPath: `${path.resolve(__dirname, '../src/scss/constants/')}/`,
+      prefix: 'constant',
+      files: [
+        {
+          destination: '_sd-tokens.scss',
+          format: 'scss/map-deep',
+          options: {
+            themeable: false,
+          },
+          filter(token) {
+            // only keep "private" tokens aka constants
+            return !!(token && token.private);
+          },
+        },
+      ],
+    },
+    /**
+     * used by:
+     *
+     * #### 'template-renderer'
+     * https://github.com/wiley/madgex-template-renderer/blob/e5eb868e6b789a8d751efc98768672d877196fa5/lib/services/dataUtils.js#L101
+     *
+     * #### display-image-render-api
+     * https://github.com/wiley/madgex-display-image-render-api/blob/27e6e219400a98a41f39861c8b362a0849888ea3/lib/services/templates.js#L157
+     */
+    'json-variables': {
+      // transformGroup: 'js',
+      transforms: ['name/kebab', 'color/css'],
+      buildPath: path.join(defaultDistDir, 'json/'),
+      files: [
+        {
+          destination: 'variables.json',
+          format: 'json/nested',
+          // https://github.com/amzn/style-dictionary/blob/f2395f3d4638e1fa57a86bd821b28e2f043067c4/lib/common/filters.js#L28
+          filter: 'removePrivate',
+        },
+      ],
+    },
+    /**
+     * used by Jack's Chrome Extension
+     */
+    'json-variables-flat': {
+      // transformGroup: 'js',
+      transforms: ['name/kebab', 'color/css'],
+      buildPath: path.join(defaultDistDir, 'json/'),
+      files: [
+        {
+          destination: 'variables-flat.json',
+          format: 'json/flat',
+          // https://github.com/amzn/style-dictionary/blob/f2395f3d4638e1fa57a86bd821b28e2f043067c4/lib/common/filters.js#L28
+          filter: 'removePrivate',
+        },
+      ],
+    },
+    /**
+     * only used for fractal docs visualisation of tokens
+     */
+    'js-module': {
+      transforms: ['name/pascal'],
+      buildPath: path.join(defaultDistDir, 'js/'),
+      prefix: 'mds',
+      files: [
+        {
+          destination: '_tokens-module.js',
+          format: 'javascript/module',
+        },
+      ],
+    },
+  },
+});
+
+/**
+ *
+ * Create an instance of Style Dictionary with base Design System tokens already loaded.
+ *
+ * Supplied `source` paths will have brand color transformation applied
+ *
+ * existing Design System `platforms` which can be overriden (e.g. override buildPath)
+ *
+ * - 'css-variables'
+ * - 'scss-variables'
+ * - 'json-variables'
+ * - 'json-variables-flat'
+ * - 'js-module'
+ *
+ * @param {import('style-dictionary').Config} incomingConfig
+ * @param {import('style-dictionary').PlatformConfig} incomingConfig.platforms
+ * @param {Array<string>} incomingConfig.source
+ *
+ * @returns {{styleDictionary:import('style-dictionary').default, cleanTempFiles: Function}} Style Dictionary Config
+ *
+ * @example
+ * ```javascript
+ * // frontend-rollout-tool only wants to build 2 platforms to specific directories
+ * const { styleDictionary, cleanTempFiles } = await createStyleDictionary({
+ *  // override platform defaults, like buildPath
+ *   platforms: {
+ *     'css-variables': { buildPath: Path.join(buildPath, 'css-vars/') },
+ *     'json-variables': { buildPath: Path.join(buildPath, 'json/') },
+ *   },
+ *   source: [Path.join(srcTokensPath, 'brand.json')]
+ * })
+ * await styleDictionary.buildPlatform('css-variables');
+ * await styleDictionary.buildPlatform('json-variables');
+ * await cleanTempFiles();
+ *
+ * ///////////////////////////////
+ *
+ * // Design System wants to build all platforms to default directories
+ * const { styleDictionary, cleanTempFiles } = await createStyleDictionary();
+ * await styleDictionary.buildAllPlatforms();
+ * await cleanTempFiles();
+ * ```
+ */
+async function createStyleDictionary(incomingConfig = {}) {
+  const StyleDictionaryPackage = (await import('style-dictionary')).default;
+
+  // create Style Dictionary instance using base tokens, includes all our all platforms
+  let styleDictionary = new StyleDictionaryPackage(baseConfig);
+
+  // if source was supplied (e.g. by frontend-rollout-tool brand.json), make sure brand lightness is generated
+  const transformedSource = [];
+  // use `glob` on `source` as this is what style-dictionary uses, keep api compatability
+  const sourceFilePaths = await glob(incomingConfig?.source || []);
+
+  for (const sourceFilePath of sourceFilePaths) {
+    // forced to write new source files to disk (required for style-dictionary, unfortunately)
+    const newSourceFilePath = await writeTransformedFileBrandColorLightnessTokens(sourceFilePath);
+    transformedSource.push(newSourceFilePath);
+  }
+
+  const cleanTempFiles = async () => {
+    for (const sourceFilePath of sourceFilePaths) {
+      try {
+        await fs.unlink(sourceFilePath);
+      } catch (error) {
+        console.warn('couldnt clean temp file ', sourceFilePath);
+      }
+    }
+  };
+  // merged incomingConfig & transformed incomingConfig.source to our base styleDictionary
+  styleDictionary = await styleDictionary.extend({ ...incomingConfig, source: transformedSource });
+
+  await styleDictionary.hasInitialized;
+  return { styleDictionary, cleanTempFiles };
+}
+
+module.exports.createStyleDictionary = createStyleDictionary;

package/tasks/tokens.js

@@ -1,32 +1,14 @@
-const path = require('path');
-const fs = require('fs');
-const { promisify } = require('util');
-const StyleDictionaryPackage = require('style-dictionary');
-const { registerTransforms } = require('./registerTransforms');
-const transformTokens = require('./colorTransforms');
-
-const readFileAsync = promisify(fs.readFile);
-const writeFileAsync = promisify(fs.writeFile);
-
-async function transformBaseTokens(filePath) {
-  const baseTokens = await readFileAsync(filePath, { encoding: 'utf8' });
-  const transformed = JSON.stringify(transformTokens(JSON.parse(baseTokens)), null, '  ')
-    // Add a space after every key, before the `:`
-    .replace(/: "(?:[^"]+|\\")*",?$/gm, ' $&');
-
-  return writeFileAsync(filePath, transformed);
-}
+const { createStyleDictionary } = require('../style-dictionary');
 
+/**
+ * build tokens via style-dictionary
+ *
+ */
 async function tokens() {
-  try {
-    await transformBaseTokens(path.resolve(__dirname, '../src/tokens/color.json'));
-    const StyleDictionary = StyleDictionaryPackage.extend(path.resolve(__dirname, '../src/tokens/_config'));
+  const { styleDictionary, cleanTempFiles } = await createStyleDictionary();
 
-    await registerTransforms(StyleDictionary);
-    await StyleDictionary.buildAllPlatforms();
-  } catch (e) {
-    console.error(e);
-  }
+  await styleDictionary.buildAllPlatforms();
+  await cleanTempFiles();
 }
 
 exports.tokens = tokens;