@grantcodes/style-dictionary 1.1.0 → 1.2.0

package/.turbo/turbo-build.log

@@ -0,0 +1,44 @@
+
+> @grantcodes/style-dictionary@1.2.0 build /home/grantcodes/projects/@grantcodes/ui/packages/style-dictionary
+> node ./build.js
+
+🚧 No theme specified, building all themes...
+
+🏗️ Building WIREFRAME theme
+
+🏗️ Building GRANTCODES theme
+
+🏗️ Building TODOMAP theme
+
+css
+✔︎ dist/css/todomap/tokens.css
+✔︎ dist/css/todomap/todomap.css
+
+json
+✔︎ dist/json/todomap/tokens.json
+
+css
+✔︎ dist/css/grantcodes/tokens.css
+✔︎ dist/css/grantcodes/grantcodes.css
+
+json
+✔︎ dist/json/grantcodes/tokens.json
+
+css
+✔︎ dist/css/wireframe/tokens.css
+✔︎ dist/css/wireframe/wireframe.css
+
+json
+✔︎ dist/json/wireframe/tokens.json
+
+ts
+✔︎ dist/js/todomap/style-dictionary.js
+✔︎ dist/js/todomap/style-dictionary.d.ts
+
+ts
+✔︎ dist/js/grantcodes/style-dictionary.js
+✔︎ dist/js/grantcodes/style-dictionary.d.ts
+
+ts
+✔︎ dist/js/wireframe/style-dictionary.js
+✔︎ dist/js/wireframe/style-dictionary.d.ts

package/.turbo/turbo-lint.log

@@ -0,0 +1,5 @@
+
+> @grantcodes/style-dictionary@1.1.0 lint /home/grantcodes/projects/@grantcodes/ui/packages/style-dictionary
+> npx @biomejs/biome lint tokens build.js lib
+
+Checked 48 files in 6ms. No fixes applied.

package/README.md

@@ -1,3 +1,40 @@
 # @grantcodes/style-dictionary
 
 This is my personal [style dictionary](https://github.com/amzn/style-dictionary) that I use for various personal projects.
+
+## Naming & structure
+
+It follows [Brad Frost's](https://bradfrost.com) recommended token structure.
+
+Priciples:
+
+- Clarity over cleverness - keep the names simple and understandable
+- Legibility over succinctiness - long but readable variables > short hard to understand variables
+- Consistency is key
+- Use existing conventions
+- Be environment agnostic - don't name things specifically for the web or mobile
+
+### Tier 1 tokens
+
+| Namespace | Category   | Property | Variant / Scale | CSS Variable |
+---------------------------------------------------------------
+| g         | color      | red       | 100     | --g-color-red-100   |
+| g         | typography |           |         | --g-             |
+| g         | spacing    |           |         | --g-             |
+| g         | border     |           |         | --g-             |
+| g         | shadow     |           |         | --g-             |
+| g         | animation  |           |         | --g-             |
+| g         | breakpoint |           |         | --g-             |
+| g         | z-index    |           |         | --g-             |
+
+
+
+## Usage
+
+```css
+
+@import "@grantcodes/style-dictionary";
+
+
+
+```

package/biome.json

@@ -0,0 +1,9 @@
+{
+	"root": false,
+	"$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+	"extends": ["../biome.json"],
+	"files": {
+		"ignoreUnknown": false,
+		"includes": ["tokens/**", "lib/**", "build.js", "config.js"]
+	}
+}

package/build.js

@@ -0,0 +1,10 @@
+/**
+ * Build script to create style dictionary outputs for each theme
+ * This now uses the config.js file which contains all the build logic
+ */
+
+// The build logic is now in config.js and runs automatically when executed
+// This file can be kept for backwards compatibility or removed
+// Run: node config.js or node build.js (which runs config.js)
+
+import "./config.js";

package/config.js

@@ -0,0 +1,485 @@
+import StyleDictionary from "style-dictionary";
+import minimist from "minimist";
+
+/**
+ * List of themes to build
+ * 1) Add your new theme here in order to have it show up in the dropdown
+ */
+const AVAILABLE_THEMES = ["wireframe", "grantcodes", "todomap"];
+
+/**
+ * Look for args passed on the command line
+ * 1) Used to build a single theme if needed
+ * 2) Pass in the theme name as an argument
+ * 3) If no argument is passed, build all themes
+ */
+const args = minimist(process.argv.slice(2));
+const theme = args.theme;
+
+/**
+ * Helper function to check if token is from tier-2 or tier-3
+ * 1) Used to determine if the token should be included in the theme tokens to apply `theme` prefix
+ */
+const isHigherTierToken = (filePath) => {
+	const isHigherTier =
+		filePath.includes("tier-2-usage") || filePath.includes("tier-3-components");
+	return isHigherTier;
+};
+
+/**
+ * Transform shadow tokens
+ * 1) Used to transform the individual shadow tokens into a single box-shadow-sm, box-shadow-md, etc. with x, y, blur, spread, and color concatenated
+ */
+const transformShadowTokens = (dictionary, size, themeTokens) => {
+	const shadowProps = dictionary.allTokens.filter(
+		(p) =>
+			isHigherTierToken(p.filePath) &&
+			p.path[0] === "box-shadow" &&
+			p.path[1] === size,
+	);
+
+	const x = shadowProps.find((p) => p.path[2] === "x")?.value || "0px";
+	const y = shadowProps.find((p) => p.path[2] === "y")?.value || "0px";
+	const blur = shadowProps.find((p) => p.path[2] === "blur")?.value || "0px";
+	const spread =
+		shadowProps.find((p) => p.path[2] === "spread")?.value || "0px";
+	const color =
+		shadowProps.find((p) => p.path[2] === "color")?.value || "transparent";
+
+	/* 1 */
+	themeTokens.push(
+		`  --g-theme-box-shadow-${size}: ${x} ${y} ${blur} ${spread} ${color};`,
+	);
+};
+
+/**
+ * Transform line height tokens
+ * 1) Used to transform the line height tokens to a unitless value for CSS by dividing the line height by the font size
+ */
+const transformLineHeight = (
+	dictionary,
+	prop,
+	outputArray,
+	formatTokenName,
+) => {
+	const cleanPath = prop.path
+		.map((segment) =>
+			segment.startsWith("@") ? segment.substring(1) : segment,
+		)
+		.filter((segment) => segment !== "")
+		.join("-");
+
+	// For tier-1 tokens (typography.line-height.16), find matching font-size (typography.font-size.16)
+	// For tier-2/3 tokens (typography.headline-lg.line-height), find matching font-size (typography.headline-lg.font-size)
+	const isTier1 =
+		prop.path.length === 3 &&
+		prop.path[0] === "typography" &&
+		prop.path[1] === "line-height";
+	let fontSizePath;
+	if (isTier1) {
+		// Tier-1: typography.line-height.16 -> typography.font-size.16
+		fontSizePath = ["typography", "font-size", prop.path[2]];
+	} else {
+		// Tier-2/3: typography.headline-lg.line-height -> typography.headline-lg.font-size
+		fontSizePath = [...prop.path.slice(0, -1), "font-size"];
+	}
+
+	const fontSizeProp = dictionary.allTokens.find(
+		(p) => p.path.join(".") === fontSizePath.join("."),
+	);
+
+	// Parse line-height value to pixels
+	let lineHeightPx;
+	if (prop.value.endsWith("px")) {
+		lineHeightPx = parseFloat(prop.value.replace("px", ""));
+	} else if (prop.value.endsWith("rem")) {
+		lineHeightPx = parseFloat(prop.value.replace("rem", "")) * 16;
+	} else {
+		lineHeightPx = parseFloat(prop.value);
+	}
+
+	if (fontSizeProp) {
+		// Found matching font-size - use it for calculation
+		let fontSizePx;
+		if (fontSizeProp.value.endsWith("px")) {
+			fontSizePx = parseFloat(fontSizeProp.value.replace("px", ""));
+		} else if (fontSizeProp.value.endsWith("rem")) {
+			fontSizePx = parseFloat(fontSizeProp.value.replace("rem", "")) * 16;
+		} else {
+			fontSizePx = parseFloat(fontSizeProp.value);
+		}
+
+		if (fontSizePx > 0) {
+			const unitlessValue = (lineHeightPx / fontSizePx).toFixed(2);
+			outputArray.push(
+				`  ${formatTokenName(cleanPath, prop)}: ${unitlessValue};`,
+			);
+			return;
+		}
+	} else if (isTier1 && lineHeightPx > 0) {
+		// For tier-1 tokens without matching font-size, use 16px as base font-size
+		const BASE_FONT_SIZE = 16;
+		const unitlessValue = (lineHeightPx / BASE_FONT_SIZE).toFixed(2);
+		outputArray.push(
+			`  ${formatTokenName(cleanPath, prop)}: ${unitlessValue};`,
+		);
+		return;
+	}
+
+	// Fallback: output as-is if we can't calculate
+	outputArray.push(`  ${formatTokenName(cleanPath, prop)}: ${prop.value};`);
+};
+
+/**
+ * Format variables
+ * 1) Used to format the inner contents of the :root or .[theme-name] ruleset
+ */
+const formatVariables = (dictionary) => {
+	const processedShadows = new Set();
+	const tier1Tokens = [];
+	const themeTokens = [];
+
+	/**
+	 * Format token global prefix and tier 2/3 identifier
+	 * 1) If the token is from tier-2 or tier-3, prefix it with `g-theme-`
+	 * 2) Otherwise, prefix it with `g-`
+	 */
+	const formatTokenName = (cleanPath, prop) => {
+		if (isHigherTierToken(prop.filePath)) {
+			return `--g-theme-${cleanPath}`;
+		}
+		return `--g-${cleanPath}`;
+	};
+
+	/**
+	 * Get all box-shadow values from tier 2/3
+	 * 1) Used to determine which box-shadow values to transform into a single box-shadow-sm, box-shadow-md, etc.
+	 */
+	const shadowSizes = dictionary.tokens.shadow
+		? Object.keys(dictionary.tokens.shadow)
+				.map((key) => key.split("-")[0])
+				.filter((value, index, self) => self.indexOf(value) === index) // Get unique sizes
+		: [];
+
+	/**
+	 * Iterate over all tokens and format them
+	 *
+	 */
+	dictionary.allTokens.forEach((prop) => {
+		/**
+		 * 1) Always include z-index and size tokens from core
+		 */
+		if (prop.path[0] === "z-index") {
+			const cleanPath = prop.path
+				.map((segment) =>
+					segment.startsWith("@") ? segment.substring(1) : segment,
+				)
+				.filter((segment) => segment !== "")
+				.join("-");
+			tier1Tokens.push(`  ${formatTokenName(cleanPath, prop)}: ${prop.value};`);
+			return;
+		}
+
+		/**
+		 * Handle box-shadow token transformations
+		 * If the token is from tier-2 or tier-3 and is a box-shadow, transform it into a single box-shadow-sm, box-shadow-md, etc.
+		 */
+		if (
+			isHigherTierToken(prop.filePath) &&
+			prop.path[0] === "box-shadow" &&
+			shadowSizes.includes(prop.path[1])
+		) {
+			const size = prop.path[1];
+			if (processedShadows.has(size)) return;
+			processedShadows.add(size);
+			transformShadowTokens(dictionary, size, themeTokens);
+		} else if (
+			prop.path[0] === "typography" &&
+			prop.path.includes("line-height")
+		) {
+			/**
+			 * Handle line heights in typography (both tier-1 and tier-2/3)
+			 * 1) Transform line-height tokens to unitless values by dividing by font-size
+			 */
+			const outputArray = isHigherTierToken(prop.filePath)
+				? themeTokens
+				: tier1Tokens;
+			transformLineHeight(dictionary, prop, outputArray, formatTokenName);
+		} else if (!prop.path.includes("box-shadow") || prop.path.length > 3) {
+			/**
+			 * Handle all other properties
+			 * 1) If the token is not a box-shadow or typography token, format it as a normal token
+			 */
+			const cleanPath = prop.path
+				.map((segment) =>
+					segment.startsWith("@") ? segment.substring(1) : segment,
+				)
+				.filter((segment) => segment !== "")
+				.join("-");
+
+			const token = `  ${formatTokenName(cleanPath, prop)}: ${prop.value};`;
+			if (isHigherTierToken(prop.filePath)) {
+				themeTokens.push(token);
+			} else {
+				tier1Tokens.push(token);
+			}
+		}
+	});
+
+	return [...new Set([...tier1Tokens, ...themeTokens])].join("\n");
+};
+
+/**
+ * Transform shadow tokens for JSON format
+ * Combines individual shadow properties into a single value
+ */
+const transformShadowTokensJSON = (dictionary, size) => {
+	const shadowProps = dictionary.allTokens.filter(
+		(p) =>
+			isHigherTierToken(p.filePath) &&
+			p.path[0] === "box-shadow" &&
+			p.path[1] === size,
+	);
+
+	const x = shadowProps.find((p) => p.path[2] === "x")?.value || "0px";
+	const y = shadowProps.find((p) => p.path[2] === "y")?.value || "0px";
+	const blur = shadowProps.find((p) => p.path[2] === "blur")?.value || "0px";
+	const spread =
+		shadowProps.find((p) => p.path[2] === "spread")?.value || "0px";
+	const color =
+		shadowProps.find((p) => p.path[2] === "color")?.value || "transparent";
+
+	return `${x} ${y} ${blur} ${spread} ${color}`;
+};
+
+/**
+ * Generate a Theme-Specific Config
+ * This accepts a theme parameter, which is used to control which set of
+ * tokens to compile, and to define theme-specific compiled output.
+ * @param {string} theme
+ */
+const getStyleDictionaryConfig = (theme) => {
+	// Register the JSON formatter
+	StyleDictionary.registerFormat({
+		name: "json/flat/custom",
+		format: function (dictionary) {
+			const transformedTokens = {};
+
+			/**
+			 * Get all box-shadow values from tier 2/3
+			 * 1) Used to determine which box-shadow values to transform into a single box-shadow-sm, box-shadow-md, etc.
+			 */
+			const shadowSizes = dictionary.tokens.shadow
+				? Object.keys(dictionary.tokens.shadow)
+						.map((key) => key.split("-")[0])
+						.filter((value, index, self) => self.indexOf(value) === index) // Get unique sizes
+				: [];
+
+			// Process regular tokens
+			dictionary.allTokens.forEach((token) => {
+				// Remove the isHigherTierToken check to include all tokens
+				if (token.path[0] === "box-shadow" && token.path.length > 2) return;
+				const prefix = isHigherTierToken(token.filePath) ? "g-theme-" : "g-";
+				transformedTokens[`${prefix}${token.path.join("-")}`] = token.value;
+			});
+
+			// Process shadow tokens
+			shadowSizes.forEach((size) => {
+				transformedTokens[`g-theme-box-shadow-${size}`] =
+					transformShadowTokensJSON(dictionary, size);
+			});
+
+			return JSON.stringify(transformedTokens, null, 2);
+		},
+	});
+
+	/**
+	 * Register the CSS formatter
+	 * 1) Used to format the inner contents of the .[theme-name] ruleset for Storybook only or if you want to define tokens using a theme name
+	 */
+	StyleDictionary.registerFormat({
+		name: "css/variables-themed",
+		format: function (dictionary) {
+			return `.${theme} {\n${formatVariables(dictionary)}\n}\n`;
+		},
+	});
+
+	/**
+	 * Define the base pixel value for rem conversion
+	 */
+	const BASE_FONT_SIZE = 16; // Typically 16px = 1rem
+
+	/**
+	 * Register the size/px-to-rem transform
+	 * 1) Used to convert px values to rem values
+	 * 2) Match only properties with px values
+	 * 3) Only transform if it's a valid px value
+	 */
+	StyleDictionary.registerTransform({
+		name: "size/px-to-rem",
+		type: "value",
+		matcher: function (prop) {
+			/* 2 */
+			return (
+				prop &&
+				prop.value &&
+				typeof prop.value === "string" &&
+				prop.value.endsWith("px")
+			);
+		},
+		transform: function (prop) {
+			if (!prop || !prop.value) return prop.value;
+			/* 3 */
+			const pxValue = prop.value.trim();
+			if (!pxValue.endsWith("px")) return prop.value;
+
+			const pixels = parseFloat(pxValue);
+			if (isNaN(pixels)) return prop.value;
+
+			const remValue = Number((pixels / BASE_FONT_SIZE).toFixed(4)).toString();
+			return `${remValue}rem`;
+		},
+	});
+
+	/**
+	 * Register the CSS formatter
+	 * 1) Used to format the inner contents of the :root ruleset for Storybook only or if you want to define tokens with theme prefix
+	 */
+	StyleDictionary.registerFormat({
+		name: "css/custom-variables",
+		format: function (dictionary) {
+			return `:root {\n${formatVariables(dictionary)}\n}`;
+		},
+	});
+
+	/**
+	 * Register the name/theme-prefix transform
+	 * 1) Used to prefix the token name with the theme name
+	 * 2) If the token is from tier-2 or tier-3, prefix it with `GTheme` for JS
+	 * 3) Otherwise, prefix it with `G` for JS
+	 */
+	StyleDictionary.registerTransform({
+		name: "name/theme-prefix",
+		type: "name",
+		transform: function (token) {
+			const cleanPath = token.path
+				.map((segment) =>
+					segment.startsWith("@") ? segment.substring(1) : segment,
+				)
+				.filter((segment) => segment !== "")
+				.join("-");
+
+			/* 2 */
+			if (isHigherTierToken(token.filePath)) {
+				return `GTheme${cleanPath
+					.split("-")
+					.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+					.join("")}`;
+			}
+
+			/* 3 */
+			return `G${cleanPath
+				.split("-")
+				.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+				.join("")}`;
+		},
+	});
+
+	/**
+	 * Register the custom/css transform group
+	 */
+	StyleDictionary.registerTransformGroup({
+		name: "custom/css",
+		transforms: ["attribute/cti", "name/kebab", "size/px-to-rem"],
+	});
+
+	/**
+	 * Register the custom/js transform group
+	 */
+	StyleDictionary.registerTransformGroup({
+		name: "custom/js",
+		transforms: ["attribute/cti", "name/theme-prefix", "size/px-to-rem"],
+	});
+
+	/**
+	 * Define the config
+	 * 1) Used to define the platforms, prefixes, etc. to build the tokens with/for
+	 */
+	const config = {
+		source: [`./tokens/core/**/*.json`, `./tokens/${theme}/**/*.json`],
+		log: {
+			// Set the log level to show errors, warnings, and info messages
+			verbosity: "verbose",
+		},
+		platforms: {
+			ts: {
+				transformGroup: "custom/js",
+				prefix: "G",
+				buildPath: `./dist/js/${theme}/`,
+				filter: {
+					attributes: {
+						category: "theme",
+					},
+				},
+				files: [
+					{
+						destination: "style-dictionary.js",
+						format: "javascript/es6",
+					},
+					{
+						destination: "style-dictionary.d.ts",
+						format: "typescript/es6-declarations",
+					},
+				],
+			},
+			css: {
+				transformGroup: "custom/css",
+				prefix: "g",
+				buildPath: `./dist/css/${theme}/`,
+				files: [
+					{
+						destination: "tokens.css",
+						format: "css/custom-variables",
+					},
+					{
+						destination: `${theme}.css`,
+						format: "css/variables-themed",
+					},
+				],
+			},
+			json: {
+				transformGroup: "custom/css",
+				prefix: "g",
+				buildPath: `./dist/json/${theme}/`,
+				files: [
+					{
+						destination: "tokens.json",
+						format: "json/flat/custom",
+					},
+				],
+			},
+		},
+	};
+
+	return config;
+};
+
+/**
+ * Build the tokens
+ * 1) If no theme is specified, build all themes
+ * 2) Otherwise, build the specified theme
+ */
+if (!theme) {
+	console.log("🚧 No theme specified, building all themes...");
+	AVAILABLE_THEMES.forEach((themeName) => {
+		console.log(`\n🏗️ Building ${themeName.toUpperCase()} theme`);
+		const themeConfig = getStyleDictionaryConfig(themeName);
+		const StyleDictionaryExtended = new StyleDictionary(themeConfig);
+		StyleDictionaryExtended.buildAllPlatforms();
+	});
+} else {
+	console.log(`🚧 Building ${theme.toUpperCase()} theme`);
+	const config = getStyleDictionaryConfig(theme);
+	const StyleDictionaryExtended = new StyleDictionary(config);
+	StyleDictionaryExtended.buildAllPlatforms();
+}