@madgex/design-system 9.3.0 → 10.0.0

package/README.md

@@ -18,7 +18,7 @@ You'll need to use the Madgex DS CSS file in your project (which you will find i
 
 The design system is using CSS Custom Properties to apply the brand styling of each site so you will need to import the custom properties file found in S3 for each client property id as well.
 
-if you want to use the default styling set in the design system, you can use the `_tokens.css` file found in `dist/_tokens/css`.
+if you want to use the default styling set in the design system, you can use the `variables.css` file found in `dist/_tokens/css`.
 
 ## Working with [hapi.js](https://hapijs.com/), [vision](https://github.com/hapijs/vision) and [Nunjucks](https://mozilla.github.io/nunjucks/)
 
@@ -86,3 +86,54 @@ npm link
 cd [your local path]/jobseekers-frontend
 npm link npm link @madgex/design-system
 ```
+
+## Building Tokens
+
+We use [Style Dictionary](https://styledictionary.com/) to build our Design System tokens.
+
+### createStyleDictionary(overridesObject:StyleDictionaryConfig?) : { styleDictionary:StyleDictionary, cleanTempFiles:Function }
+
+`createStyleDictionary(StyleDictionaryConfig)` is exposed via `@madgex/design-system/style-dictionary`.
+This creates a new [StyleDictionary Instance](https://styledictionary.com/reference/api/#instance-methods), preconfigured with our base tokens, and all platforms we want to build. [See here for the base config we use](style-dictionary/index.js).
+
+You can supply overrides to `createStyleDictionary` which should be the same shape as [Style Dictionary Configuration](https://styledictionary.com/reference/config/#properties).
+
+Typically you will only override `buildPath` on platforms (so the platform builds with the same transforms everywhere), and supply `source` token override file paths.
+
+### pre-configured platforms
+
+A `platform` determines a certain type of output based on the tokens.
+When you create a new StyleDictionary Instance via `createStyleDictionary`, it comes with our pre-configured platforms :
+
+- 'css-variables' : outputs `variables.css` to `buildPath`, CSS Variables
+- 'json-variables' : outputs `variables.json` to `buildPath`, JSON version of CSS Variables, useful for rendering in Node e.g. [display-image-render-api](https://github.com/wiley/madgex-display-image-render-api/blob/27e6e219400a98a41f39861c8b362a0849888ea3/lib/services/templates.js#L157) or [template-renderer](https://github.com/wiley/madgex-template-renderer/blob/e5eb868e6b789a8d751efc98768672d877196fa5/lib/services/dataUtils.js#L101)
+- 'json-variables-flat' : outputs `variables-flat.json` to `buildPath`. similar to 'json-variables' but in a flat object structure
+
+### Example usage, overrides
+
+In this example we override the `buildPath` of our pre-configured `platforms`.
+We also supply paths to override token files via `source`.
+
+We then build only the platforms we want, and then call cleanTempFiles once we're done.
+
+```javascript
+const path = require('node:path');
+const { createStyleDictionary, cleanTempFiles } = require('@madgex/design-system/style-dictionary');
+
+const { styleDictionary, cleanTempFiles } = await createStyleDictionary({
+  platforms: {
+    'css-variables': {
+      buildPath: `${path.resolve(__dirname, '../yes-here')}/`,
+    },
+    'json-variables': {
+      buildPath: `${path.resolve(__dirname, '../yes-here')}/`,
+    },
+  },
+  source: [path.resolve(__dirname, '../brand.json')],
+});
+
+await styleDictionary.buildPlatform('css-variables');
+await styleDictionary.buildPlatform('json-variables');
+
+await cleanTempFiles();
+```

package/dist/_tokens/css/{_tokens.css → variables.css}

@@ -1,6 +1,5 @@
 /**
- * Do not edit directly
- * Generated on Wed, 26 Mar 2025 09:21:17 GMT
+ * Do not edit directly, this file was auto-generated.
  */
 
 :root {
@@ -81,8 +80,8 @@
   --mds-size-main-padding: 0;
   --mds-size-main-margin: 0 auto;
   --mds-size-height-ad-container-leaderboard-min: 0;
-  --mds-custom-badge-1-background: #000;
-  --mds-custom-badge-1-color: #fff;
+  --mds-custom-badge-1-background: #000000;
+  --mds-custom-badge-1-color: #ffffff;
   --mds-custom-card-1-background: #e9f3fc;
   --mds-custom-card-1-border: 1px solid #1b75bb;
   --mds-shadow-site-container: none;