style-dictionary 4.1.4 → 4.3.0

package/examples/advanced/tailwind-preset/README.md

@@ -0,0 +1,94 @@
+# Tailwind preset
+
+Builds [Tailwind preset](https://tailwindcss.com/docs/presets#creating-a-preset) from tokens.
+
+## Building the preset
+
+Run `npm run build-tokens` to generate these files in `build/tailwind`:
+
+### cssVarPlugin.js
+
+A [Tailwind plugin](https://tailwindcss.com/docs/plugins) for registering new [base styles](https://tailwindcss.com/docs/plugins#adding-base-styles).
+
+The [rgbChannels](./config/transform.js) transform removes the color space function for compatability with [Tailwind's opacity modifier syntax](https://tailwindcss.com/docs/text-color#changing-the-opacity).
+
+```js
+import plugin from 'tailwindcss/plugin.js';
+
+export default plugin(function ({ addBase }) {
+	addBase({
+		':root': {
+			'--sd-text-small': '0.75',
+			'--sd-text-base': '46 46 70',
+			'--sd-text-secondary': '100 100 115',
+			'--sd-text-tertiary': '129 129 142',
+			'--sd-text-neutral': '0 0 0 / 0.55',
+			'--sd-theme': '31 197 191',
+			'--sd-theme-light': '153 235 226',
+			'--sd-theme-dark': '0 179 172',
+			'--sd-theme-secondary': '106 80 150',
+			'--sd-theme-secondary-dark': '63 28 119',
+			'--sd-theme-secondary-light': '196 178 225',
+		},
+	});
+});
+```
+
+### themeColors.js
+
+Tailwind theme color values that reference the plugin [css vars](https://tailwindcss.com/docs/customizing-colors#using-css-variables).
+
+```js
+export default {
+	'sd-text-base': 'rgb(var(--sd-text-base))',
+	'sd-text-secondary': 'rgb(var(--sd-text-secondary))',
+	'sd-text-tertiary': 'rgb(var(--sd-text-tertiary))',
+	'sd-text-neutral': 'rgb(var(--sd-text-neutral))',
+	'sd-theme': 'rgb(var(--sd-theme))',
+	'sd-theme-light': 'rgb(var(--sd-theme-light))',
+	'sd-theme-dark': 'rgb(var(--sd-theme-dark))',
+	'sd-theme-secondary': 'rgb(var(--sd-theme-secondary))',
+	'sd-theme-secondary-dark': 'rgb(var(--sd-theme-secondary-dark))',
+	'sd-theme-secondary-light': 'rgb(var(--sd-theme-secondary-light))',
+};
+```
+
+### preset.js
+
+[Tailwind preset](https://tailwindcss.com/docs/presets) file that imports the colors and plugin.
+
+```js
+import themeColors from './themeColors.js';
+import cssVarsPlugin from './cssVarsPlugin.js';
+
+export default {
+	theme: {
+		extend: {
+			colors: {
+				...themeColors, // <-- theme colors defined here
+			},
+		},
+	},
+	plugins: [cssVarsPlugin], // <-- plugin imported here
+};
+```
+
+## Building the CSS
+
+The [Tailwind preset](https://tailwindcss.com/docs/presets#creating-a-preset) is imported from the build directory in `tailwind.config.js`.
+
+```js
+import tailwindPreset from './build/tailwind/preset.js';
+
+/** @type {import('tailwindcss').Config} */
+export default {
+	theme: {
+		extend: {},
+	},
+	presets: [tailwindPreset],
+	content: ['./demo/**/*.{html,js}'],
+	plugins: [],
+};
+```
+
+Run `npm run build-css` to watch the `demo/index.html` file for changes -- any Tailwind classes used will be compiled into `demo/output.css`.

package/examples/advanced/tailwind-preset/config/filter.js

@@ -0,0 +1,3 @@
+export function isColor(token) {
+	return (token?.$type || token?.type) === 'color';
+}

package/examples/advanced/tailwind-preset/config/filter.test.js

@@ -0,0 +1,12 @@
+import { expect } from 'chai';
+import { describe, it } from 'mocha';
+import { isColor } from './filter.js';
+
+describe('isColor', () => {
+	it('should handle legacy and dtcg formats', () => {
+		expect(isColor({ type: 'color' })).to.equal(true);
+		expect(isColor({ $type: 'color' })).to.equal(true);
+		expect(isColor({ type: 'fontSize' })).to.equal(false);
+		expect(isColor({ $type: 'fontSize' })).to.equal(false);
+	});
+});

package/examples/advanced/tailwind-preset/config/format.js

@@ -0,0 +1,60 @@
+import { isColor } from './filter.js';
+
+/**
+ * Exports tailwind plugin for declaring root CSS vars
+ * @see https://tailwindcss.com/docs/plugins#overview
+ */
+export function cssVarsPlugin({ dictionary }) {
+	const vars = dictionary.allTokens
+		.map((token) => {
+			const value = token?.$value || token?.value;
+			return `'--${token.name}': '${value}'`;
+		})
+		.join(',\n\t\t\t');
+
+	return `import plugin from 'tailwindcss/plugin.js';
+
+export default plugin(function ({ addBase }) {
+\taddBase({
+\t\t':root': {
+\t\t\t${vars},
+\t\t},
+\t});
+});\n`;
+}
+
+/**
+ * Exports theme color definitions
+ * @see https://tailwindcss.com/docs/customizing-colors#using-css-variables
+ */
+export function themeColors({ dictionary, options }) {
+	const tokens = dictionary.allTokens.filter((token) => isColor(token, options));
+
+	const theme = tokens
+		.map((token) => {
+			return `\t'${token.name}': 'rgb(var(--${token.name}))'`;
+		})
+		.join(',\n');
+
+	return `export default {\n${theme},\n};\n`;
+}
+
+/**
+ * Exports tailwind preset
+ * @see https://tailwindcss.com/docs/presets
+ */
+export function preset() {
+	return `import themeColors from './themeColors.js';
+import cssVarsPlugin from './cssVarsPlugin.js';
+
+export default {
+\ttheme: {
+\t\textend: {
+\t\t\tcolors: {
+\t\t\t\t...themeColors, // <-- theme colors defined here
+\t\t\t},
+\t\t},
+\t},
+\tplugins: [cssVarsPlugin], // <-- plugin imported here
+};\n`;
+}

package/examples/advanced/tailwind-preset/config/transform.js

@@ -0,0 +1,21 @@
+export function rgbChannels(token) {
+	const value = token?.$value || token?.value;
+	const { r, g, b, a } = parseRGBA(value);
+	const hasAlpha = a !== undefined;
+	return `${r} ${g} ${b}${hasAlpha ? ' / ' + a : ''}`;
+}
+
+function parseRGBA(value) {
+	const regex = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+%?))?\s*\)/;
+	const matches = value.match(regex);
+	if (!matches) {
+		throw new Error(`Value '${value}' is not a valid rgb or rgba format.`);
+	}
+	const [, r, g, b, a] = matches;
+	return {
+		r,
+		g,
+		b,
+		a: a !== undefined ? (a.endsWith('%') ? parseFloat(a) / 100 : parseFloat(a)) : undefined,
+	};
+}

package/examples/advanced/tailwind-preset/config/transform.test.js

@@ -0,0 +1,37 @@
+import { expect } from 'chai';
+import { describe, it } from 'mocha';
+import { rgbChannels } from './transform.js';
+
+describe('rgbChannels', () => {
+	it('should extract RGB channels from valid RGB string', () => {
+		const tokenValue = 'rgb(255, 255, 255)';
+		expect(rgbChannels({ value: tokenValue })).to.equal('255 255 255');
+		expect(rgbChannels({ $value: tokenValue })).to.equal('255 255 255');
+	});
+
+	it('should extract RGB and alpha channels from valid RGBA string', () => {
+		const tokenValue = 'rgba(255, 255, 255, 0.5)';
+		expect(rgbChannels({ value: tokenValue })).to.equal('255 255 255 / 0.5');
+		expect(rgbChannels({ $value: tokenValue })).to.equal('255 255 255 / 0.5');
+	});
+
+	it('should handle different whitespace variations', () => {
+		let tokenValue = 'rgb( 123 ,  45,67 )';
+		expect(rgbChannels({ value: tokenValue })).to.equal('123 45 67');
+		tokenValue = 'rgba( 12, 34 , 56 , 0.75 )';
+		expect(rgbChannels({ value: tokenValue })).to.equal('12 34 56 / 0.75');
+	});
+
+	it('should handle different alpha formats', () => {
+		const tokenValues = ['rgb(1, 2, 3, 50%)', 'rgb(1, 2, 3, .5)', 'rgb(1, 2, 3, .50)'];
+		for (const tokenValue of tokenValues) {
+			expect(rgbChannels({ value: tokenValue })).to.equal('1 2 3 / 0.5');
+		}
+	});
+
+	it('should throw error for invalid RGB string', () => {
+		const expectedErr = "Value 'mock' is not a valid rgb or rgba format.";
+		expect(() => rgbChannels({ value: 'mock' })).to.throw(expectedErr);
+		expect(() => rgbChannels({ $value: 'mock' })).to.throw(expectedErr);
+	});
+});

package/examples/advanced/tailwind-preset/config.js

@@ -0,0 +1,55 @@
+import StyleDictionary from 'style-dictionary';
+import { isColor } from './config/filter.js';
+import { cssVarsPlugin, preset, themeColors } from './config/format.js';
+import { rgbChannels } from './config/transform.js';
+
+StyleDictionary.registerTransform({
+	name: 'color/rgb-channels',
+	type: 'value',
+	filter: isColor,
+	transform: rgbChannels,
+});
+
+StyleDictionary.registerTransformGroup({
+	name: 'tailwind',
+	transforms: ['name/kebab', 'color/rgb', 'color/rgb-channels'],
+});
+
+StyleDictionary.registerFormat({
+	name: 'tailwind/css-vars-plugin',
+	format: cssVarsPlugin,
+});
+
+StyleDictionary.registerFormat({
+	name: 'tailwind/theme-colors',
+	format: themeColors,
+});
+
+StyleDictionary.registerFormat({
+	name: 'tailwind/preset',
+	format: preset,
+});
+
+export default {
+	source: ['./tokens/**/*.json'],
+	platforms: {
+		tailwindPreset: {
+			buildPath: 'build/tailwind/',
+			transformGroup: 'tailwind',
+			files: [
+				{
+					destination: 'cssVarsPlugin.js',
+					format: 'tailwind/css-vars-plugin',
+				},
+				{
+					destination: 'themeColors.js',
+					format: 'tailwind/theme-colors',
+				},
+				{
+					destination: 'preset.js',
+					format: 'tailwind/preset',
+				},
+			],
+		},
+	},
+};

package/examples/advanced/tailwind-preset/demo/index.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<!--
+		Run `npm run build-tokens` to generate build/preset.js.
+		Then run `npm run build-css` to generate `output.css`.
+		-->
+		<link href="./output.css" rel="stylesheet" />
+	</head>
+	<body>
+		<div class="h-screen w-full bg-sd-theme-secondary/10">
+			<div class="p-4 grid grid-cols-1 gap-4 text-5xl">
+				<span class="text-sd-theme-dark">Hello tokens</span>
+				<span class="text-sd-theme-dark/50">Hello tokens</span>
+				<span class="text-sd-theme-dark/30">Hello tokens</span>
+				<span class="text-sd-theme-dark/20">Hello tokens</span>
+				<span class="text-sd-theme-secondary-dark">Hello tokens</span>
+				<span class="text-sd-theme-secondary-dark/50">Hello tokens</span>
+				<span class="text-sd-theme-secondary-dark/30">Hello tokens</span>
+				<span class="text-sd-theme-secondary-dark/20">Hello tokens</span>
+				<span class="text-sd-text-neutral">Hello tokens</span>
+			</div>
+		</div>
+	</body>
+</html>

package/examples/advanced/tailwind-preset/demo/input.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

package/examples/advanced/tailwind-preset/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "tailwind-preset",
+  "version": "1.0.0",
+  "description": "Builds tailwind preset from tokens",
+  "type": "module",
+  "scripts": {
+    "build-tokens": "style-dictionary build --config ./config.js",
+    "build-css": "npx tailwindcss -i ./demo/input.css -o ./demo/output.css --watch",
+    "test": "mocha 'config/**/*test.js'"
+  },
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "style-dictionary": "^4.3.0",
+    "tailwindcss": "^3.4.15",
+    "mocha": "^10.2.0",
+    "chai": "^5.1.1"
+  }
+}

package/examples/advanced/tailwind-preset/tailwind.config.js

@@ -0,0 +1,11 @@
+import tailwindPreset from './build/tailwind/preset.js';
+
+/** @type {import('tailwindcss').Config} */
+export default {
+	theme: {
+		extend: {},
+	},
+	presets: [tailwindPreset],
+	content: ['./demo/**/*.{html,js}'],
+	plugins: [],
+};

package/examples/advanced/tailwind-preset/tokens/tokens.json

@@ -0,0 +1,49 @@
+{
+	"sd": {
+		"text": {
+			"small": {
+				"$value": "0.75",
+				"$type": "fontSize"
+			},
+			"base": {
+				"$type": "color",
+				"$value": "#2E2E46"
+			},
+			"secondary": {
+				"$type": "color",
+				"$value": "#646473"
+			},
+			"tertiary": {
+				"$type": "color",
+				"$value": "#81818E"
+			},
+			"neutral": {
+				"$type": "color",
+				"$value": "#0000008C"
+			}
+		},
+		"theme": {
+			"$type": "color",
+			"_": {
+				"$value": "#1FC5BF"
+			},
+			"light": {
+				"$value": "#99EBE2"
+			},
+			"dark": {
+				"$value": "#00B3AC"
+			},
+			"secondary": {
+				"_": {
+					"$value": "#6A5096"
+				},
+				"dark": {
+					"$value": "#3F1C77"
+				},
+				"light": {
+					"$value": "#C4B2E1"
+				}
+			}
+		}
+	}
+}

package/examples/advanced/tokens-deprecation/build.js

@@ -1,5 +1,6 @@
 import StyleDictionary from 'style-dictionary';
 import { fileHeader } from 'style-dictionary/utils';
+import { commentStyles } from 'style-dictionary/enums';
 import { dirname } from 'path';
 import { fileURLToPath } from 'url';
 import webScssTemplate from './templates/web-scss.template.js';
@@ -15,7 +16,7 @@ sd.registerFormat({
   name: 'custom/format/scss',
   format: async ({ dictionary, file, options }) => {
     const { allTokens } = dictionary;
-    const header = await fileHeader({ file, commentStyle: 'long' });
+    const header = await fileHeader({ file, commentStyle: commentStyles.long });
     return webScssTemplate({ allTokens, file, options, header });
   },
 });

package/examples/advanced/tokens-deprecation/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.1.4"
+    "style-dictionary": "^4.3.0"
   }
 }

package/examples/advanced/transitive-transforms/package.json

@@ -12,6 +12,6 @@
   "license": "ISC",
   "devDependencies": {
     "colorjs.io": "^0.5.2",
-    "style-dictionary": "^4.1.4"
+    "style-dictionary": "^4.3.0"
   }
 }

package/examples/advanced/transitive-transforms/sd.config.js

@@ -1,12 +1,15 @@
 import StyleDictionary from 'style-dictionary';
 import { usesReferences } from 'style-dictionary/utils';
+import { formats, transforms } from 'style-dictionary/enums';
 import Color from 'colorjs.io';
 
+const { attributeCti, colorCss, nameKebab } = transforms;
+
 const colorTransform = (token) => {
   const { value, modify = [] } = token;
 
   // This assumes "hex" format, if you want to support { h, s, l } format you have to do
-  // `new Color('hsl', [value.h, value.s, value.l]);`
+  // 'new Color('hsl', [value.h, value.s, value.l]);'
   const color = new Color(value);
 
   // defer until reference is resolved
@@ -42,14 +45,14 @@ const colorTransform = (token) => {
 export default {
   // This will match any files ending in json or json5
   // I am using json5 here so I can add comments in the token files for reference
-  source: [`tokens/**/*.@(json|json5)`],
+  source: ['tokens/**/*.@(json|json5)'],
 
   // I am directly defining transforms here
   // This would work if you were to call StyleDictionary.registerTransform() as well
   hooks: {
     transforms: {
       colorTransform: {
-        type: `value`,
+        type: 'value',
         // only transforms that have transitive: true will be applied to tokens
         // that alias/reference other tokens
         transitive: true,
@@ -59,8 +62,8 @@ export default {
 
       // For backwards compatibility, all built-in transforms are not transitive
       // by default. This will make the 'color/css' transform transitive
-      'color/css': {
-        ...StyleDictionary.hooks.transforms[`color/css`],
+      [colorCss]: {
+        ...StyleDictionary.hooks.transforms[colorCss],
         transitive: true,
       },
     },
@@ -68,12 +71,12 @@ export default {
 
   platforms: {
     css: {
-      transforms: [`attribute/cti`, `name/kebab`, `colorTransform`, `color/css`],
-      buildPath: `build/`,
+      transforms: [attributeCti, nameKebab, 'colorTransform', colorCss],
+      buildPath: 'build/',
       files: [
         {
-          destination: `variables.css`,
-          format: `css/variables`,
+          destination: 'variables.css',
+          format: formats.cssVariables,
         },
       ],
     },

package/examples/advanced/variables-in-outputs/package.json

@@ -11,6 +11,6 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
-    "style-dictionary": "^4.1.4"
+    "style-dictionary": "^4.3.0"
   }
 }

package/examples/advanced/variables-in-outputs/sd.config.js

@@ -1,3 +1,8 @@
+import { formats, transformGroups } from 'style-dictionary/enums';
+
+const { cssVariables, jsonNested, scssVariables } = formats;
+const { css, js } = transformGroups;
+
 export default {
   hooks: {
     formats: {
@@ -37,13 +42,13 @@ export default {
       files: [
         {
           destination: 'tokens.json',
-          format: 'json/nested',
+          format: jsonNested,
         },
       ],
     },
     js: {
       buildPath: 'build/',
-      transformGroup: 'js',
+      transformGroup: js,
       files: [
         {
           destination: 'tokens.js',
@@ -55,19 +60,19 @@ export default {
       ],
     },
     css: {
-      transformGroup: 'css',
+      transformGroup: css,
       buildPath: 'build/',
       files: [
         {
           destination: 'tokens.css',
-          format: 'css/variables',
+          format: cssVariables,
           options: {
             outputReferences: true, // new setting, if true will use variable references
           },
         },
         {
           destination: 'tokens.scss',
-          format: 'scss/variables',
+          format: scssVariables,
           options: {
             outputReferences: true, // new setting, if true will use variable references
           },

package/examples/advanced/yaml-tokens/package.json

@@ -10,7 +10,7 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^4.1.4",
+    "style-dictionary": "^4.3.0",
     "yaml": "^1.10.0"
   }
 }

package/examples/advanced/yaml-tokens/sd.config.js

@@ -1,4 +1,5 @@
 import yaml from 'yaml';
+import { formats, transformGroups } from 'style-dictionary/enums';
 
 export default {
   hooks: {
@@ -20,12 +21,12 @@ export default {
   source: [`tokens/**/*.yaml`],
   platforms: {
     css: {
-      transformGroup: 'css',
+      transformGroup: transformGroups.css,
       buildPath: 'build/',
       files: [
         {
           destination: 'variables.css',
-          format: 'css/variables',
+          format: formats.cssVariables,
         },
       ],
     },

package/lib/Register.d.ts

@@ -7,7 +7,7 @@ export class Register {
      *
      * Therefore, we have to make use of static props vs instance props and use getters and setters to merge these together.
      */
-    static hooks: Required<import("../types/Config.ts").Hooks>;
+    static hooks: Required<import("../types/Config.d.ts").Hooks>;
     /**
      * @param {typeof Register | Register} target
      * @param {keyof Hooks} hook
@@ -101,10 +101,10 @@ export class Register {
     /**
      * @param {Required<Hooks>} v
      */
-    set hooks(v: Required<import("../types/Config.ts").Hooks>);
+    set hooks(v: Required<Hooks>);
     /** @type {Required<Hooks>} */
-    get hooks(): Required<import("../types/Config.ts").Hooks>;
-    _hooks: Required<import("../types/Config.ts").Hooks> | undefined;
+    get hooks(): Required<Hooks>;
+    _hooks: Required<import("../types/Config.d.ts").Hooks> | undefined;
     /**
      * @param {Transform} cfg
      */
@@ -144,11 +144,11 @@ export class Register {
         fileHeader: FileHeader;
     }): void;
 }
-export type FileHeader = import("../types/File.ts").FileHeader;
-export type Parser = import("../types/Parser.ts").Parser;
-export type Preprocessor = import("../types/Preprocessor.ts").Preprocessor;
-export type Transform = import("../types/Transform.ts").Transform;
-export type Filter = import("../types/Filter.ts").Filter;
-export type Format = import("../types/Format.ts").Format;
-export type Action = import("../types/Action.ts").Action;
-export type Hooks = import("../types/Config.ts").Hooks;
+export type FileHeader = import("../types/File.d.ts").FileHeader;
+export type Parser = import("../types/Parser.d.ts").Parser;
+export type Preprocessor = import("../types/Preprocessor.d.ts").Preprocessor;
+export type Transform = import("../types/Transform.d.ts").Transform;
+export type Filter = import("../types/Filter.d.ts").Filter;
+export type Format = import("../types/Format.d.ts").Format;
+export type Action = import("../types/Action.d.ts").Action;
+export type Hooks = import("../types/Config.d.ts").Hooks;