terrazzo-plugin-figma-json 0.1.0

package/dist/index.js

@@ -0,0 +1,1454 @@
+import wcmatch from "wildcard-match";
+import Color from "colorjs.io";
+
+//#region src/constants.ts
+const PLUGIN_NAME = "terrazzo-plugin-figma-json";
+const FORMAT_ID = "figma-json";
+/**
+* Internal metadata property keys used for token processing.
+* These are added during transform and removed during build.
+*/
+const INTERNAL_KEYS = {
+	ALIAS_OF: "_aliasOf",
+	SPLIT_FROM: "_splitFrom",
+	TOKEN_ID: "_tokenId"
+};
+/**
+* Token types supported by Figma.
+*/
+const SUPPORTED_TYPES = [
+	"color",
+	"dimension",
+	"duration",
+	"fontFamily",
+	"fontWeight",
+	"number",
+	"typography"
+];
+/**
+* Token types that are not supported by Figma and will be dropped with a warning.
+*/
+const UNSUPPORTED_TYPES = [
+	"shadow",
+	"border",
+	"gradient",
+	"transition",
+	"strokeStyle",
+	"cubicBezier"
+];
+/**
+* Color spaces that Figma natively supports.
+*/
+const FIGMA_COLOR_SPACES = ["srgb", "hsl"];
+
+//#endregion
+//#region src/utils.ts
+/**
+* Create an exclude matcher function from glob patterns.
+*
+* @param patterns - Array of glob patterns to match against token IDs
+* @returns A function that returns true if the token ID should be excluded
+*/
+function createExcludeMatcher(patterns) {
+	return patterns?.length ? wcmatch(patterns) : () => false;
+}
+/**
+* Type guard to check if the resolver has a usable configuration.
+* Terrazzo creates a default resolver even without a resolver file,
+* but it has empty contexts that cause errors when used.
+*
+* @param resolver - The resolver from terrazzo parser
+* @returns true if resolver has user-defined sets or modifiers with contexts
+*/
+function hasValidResolverConfig(resolver) {
+	if (!resolver?.source || !resolver.listPermutations) return false;
+	const source = resolver.source;
+	const sets = source.sets ?? {};
+	const modifiers = source.modifiers ?? {};
+	const hasUserSets = Object.keys(sets).some((name) => name !== "allTokens");
+	const hasModifierContexts = Object.values(modifiers).some((mod) => mod.contexts && Object.keys(mod.contexts).length > 0);
+	return hasUserSets || hasModifierContexts;
+}
+/**
+* Build default input from resolver's modifiers.
+* Creates an input object with each modifier set to its default value.
+*
+* @param resolverSource - The resolver source configuration
+* @returns Input object for resolver.apply() with default modifier values
+*/
+function buildDefaultInput(resolverSource) {
+	const input = {};
+	if (resolverSource.modifiers) {
+		for (const [modifierName, modifier] of Object.entries(resolverSource.modifiers)) if (modifier.default) input[modifierName] = modifier.default;
+	}
+	return input;
+}
+/**
+* Remove internal metadata properties from a parsed token value.
+* These properties are used for internal processing and should not appear in output.
+*
+* @param parsedValue - Token value object to clean (mutated in place)
+*/
+function removeInternalMetadata(parsedValue) {
+	delete parsedValue[INTERNAL_KEYS.ALIAS_OF];
+	delete parsedValue[INTERNAL_KEYS.SPLIT_FROM];
+	delete parsedValue[INTERNAL_KEYS.TOKEN_ID];
+}
+/**
+* Safely parse a transform value that may be a JSON string or already an object.
+* Returns the parsed value or null if parsing fails.
+*
+* @param value - The transform value (string or object)
+* @returns Parsed value or null on error
+*/
+function parseTransformValue(value) {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return null;
+	}
+}
+/**
+* Extract partialAliasOf from a token if present.
+* This property is added by terrazzo parser for composite tokens but not in public types.
+*/
+function getPartialAliasOf(token) {
+	if (token && typeof token === "object" && "partialAliasOf" in token) {
+		const value = token.partialAliasOf;
+		if (value && typeof value === "object") return value;
+	}
+}
+/**
+* Type guard to validate DTCGColorValue structure.
+*/
+function isDTCGColorValue(value) {
+	if (!value || typeof value !== "object") return false;
+	const v = value;
+	if (typeof v.colorSpace !== "string") return false;
+	if (!Array.isArray(v.components) || v.components.length !== 3) return false;
+	for (const c of v.components) if (c !== "none" && typeof c !== "number") return false;
+	if (v.alpha !== void 0 && v.alpha !== "none" && typeof v.alpha !== "number") return false;
+	return true;
+}
+/**
+* Type guard to validate DTCGDimensionValue structure.
+*/
+function isDTCGDimensionValue(value) {
+	if (!value || typeof value !== "object") return false;
+	const v = value;
+	return typeof v.value === "number" && typeof v.unit === "string";
+}
+/**
+* Type guard to validate DTCGDurationValue structure.
+*/
+function isDTCGDurationValue(value) {
+	if (!value || typeof value !== "object") return false;
+	const v = value;
+	return typeof v.value === "number" && typeof v.unit === "string";
+}
+/**
+* Type guard to validate DTCGTypographyValue structure.
+* Only checks that it's an object - individual properties are validated during conversion.
+*/
+function isDTCGTypographyValue(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+//#endregion
+//#region src/build.ts
+/**
+* Set a nested property on an object using dot-notation path.
+* Creates intermediate objects as needed.
+*
+* @param obj - The object to modify
+* @param path - Dot-notation path (e.g., "color.primary.base")
+* @param value - The value to set at the path
+*
+* @example
+* const obj = {};
+* setNestedProperty(obj, "color.primary", { $value: "#ff0000" });
+* // obj = { color: { primary: { $value: "#ff0000" } } }
+*/
+function setNestedProperty(obj, path, value) {
+	const parts = path.split(".");
+	if (parts.length === 0) return;
+	let current = obj;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const part = parts[i];
+		if (!(part in current)) current[part] = {};
+		current = current[part];
+	}
+	const lastPart = parts[parts.length - 1];
+	current[lastPart] = value;
+}
+/**
+* Convert a dot-notation token ID to Figma's slash notation.
+*
+* @param tokenId - Token ID in dot notation
+* @returns Token ID in slash notation for Figma
+*
+* @example
+* toFigmaVariableName("dimension.200") // "dimension/200"
+* toFigmaVariableName("color.primary.base") // "color/primary/base"
+*/
+function toFigmaVariableName(tokenId) {
+	return tokenId.replace(/\./g, "/");
+}
+/**
+* Convert $root in a token ID to root for Figma compatibility.
+* DTCG uses $root for default values, but Figma doesn't support $ in names.
+*
+* @param path - Token path that may contain $root
+* @returns Path with $root replaced by root
+*
+* @example
+* normalizeRootInPath("color.border.warning.$root") // "color.border.warning.root"
+* normalizeRootInPath("color.primary") // "color.primary" (unchanged)
+*/
+function normalizeRootInPath(path) {
+	return path.replace(/\.\$root\b/g, ".root");
+}
+/**
+* Handle alias references by setting the appropriate $value or $extensions.
+* Mutates parsedValue in place.
+*
+* - Same-file references: Sets $value to curly brace syntax (e.g., "{color.primary}")
+* - Cross-file references: Keeps resolved $value and adds com.figma.aliasData extension
+*
+* The function checks for target token in this order:
+* 1. Current context (same-file reference)
+* 2. Set sources only (cross-file reference to primitive/semantic sets)
+* 3. Never references other modifier contexts (e.g., dark won't reference light)
+*
+* @param options - Configuration for alias handling
+* @param options.parsedValue - Token value object to modify (mutated)
+* @param options.aliasOf - Target token ID this token references
+* @param options.sourceName - Name of the current output file/collection
+* @param options.tokenSources - Map of token IDs to their source info
+* @param options.tokenOutputPaths - Map of token IDs to their output paths
+* @param options.preserveReferences - Whether to preserve references (false = no-op)
+*/
+function handleAliasReference({ parsedValue, aliasOf, sourceName, tokenSources, tokenOutputPaths, preserveReferences }) {
+	if (!preserveReferences || !aliasOf) return;
+	const normalizedAliasOf = aliasOf.replace(/\.\$root\b/g, "");
+	const targetOutputPath = tokenOutputPaths.get(normalizedAliasOf) ?? normalizeRootInPath(aliasOf);
+	let targetSources = tokenSources.get(normalizedAliasOf);
+	if (!targetSources) {
+		const parts = normalizedAliasOf.split(".");
+		while (parts.length > 1 && !targetSources) {
+			parts.pop();
+			targetSources = tokenSources.get(parts.join("."));
+		}
+	}
+	if (!targetSources?.length) return;
+	if (targetSources.some((s) => s.source === sourceName)) {
+		parsedValue.$value = `{${targetOutputPath}}`;
+		return;
+	}
+	const setSource = targetSources.find((s) => !s.isModifier);
+	if (setSource) {
+		const extensions = parsedValue.$extensions ?? {};
+		extensions["com.figma.aliasData"] = {
+			targetVariableSetName: setSource.source,
+			targetVariableName: toFigmaVariableName(targetOutputPath)
+		};
+		parsedValue.$extensions = extensions;
+	}
+}
+/**
+* Extract token IDs from a resolver group (token definitions).
+* Recursively walks the group structure to find all token IDs.
+*
+* Handles $root tokens specially per DTCG spec:
+* - Token ID uses parent path (e.g., "color.primary" for "color.primary.$root")
+* - Output path uses "root" without $ for Figma compatibility
+*
+* @param group - Object containing token definitions or nested groups
+* @param prefix - Current path prefix for recursion
+* @returns Array of token ID info with both normalized ID and output path
+*
+* @example
+* extractTokenIds({ color: { primary: { $value: "#ff0000" } } })
+* // [{ id: "color.primary", outputPath: "color.primary" }]
+*/
+function extractTokenIds(group, prefix = "") {
+	const ids = [];
+	for (const [key, value] of Object.entries(group)) {
+		if (key.startsWith("$") && key !== "$root") continue;
+		const outputKey = key === "$root" ? "root" : key;
+		const outputPath = prefix ? `${prefix}.${outputKey}` : outputKey;
+		const normalizedPath = key === "$root" ? prefix : outputPath;
+		if (value && typeof value === "object" && "$value" in value) {
+			if (normalizedPath) ids.push({
+				id: normalizedPath,
+				outputPath
+			});
+		} else if (value && typeof value === "object") ids.push(...extractTokenIds(value, outputPath));
+	}
+	return ids;
+}
+/**
+* Build maps tracking which tokens belong to which sources.
+* Processes both sets and modifier contexts from the resolver source.
+*
+* @param resolverSource - The resolver source configuration
+* @returns Maps for token sources, output paths, and all context keys
+*/
+function buildTokenSourceMaps(resolverSource) {
+	const tokenSources = /* @__PURE__ */ new Map();
+	const tokenOutputPaths = /* @__PURE__ */ new Map();
+	const allContexts = /* @__PURE__ */ new Set();
+	function addTokenSource(tokenId, outputPath, info) {
+		const existing = tokenSources.get(tokenId);
+		if (existing) existing.push(info);
+		else tokenSources.set(tokenId, [info]);
+		if (!tokenOutputPaths.has(tokenId)) tokenOutputPaths.set(tokenId, outputPath);
+	}
+	if (resolverSource.sets) {
+		for (const [setName, set] of Object.entries(resolverSource.sets)) if (set.sources) for (const source of set.sources) {
+			const tokenInfos = extractTokenIds(source);
+			for (const { id, outputPath } of tokenInfos) addTokenSource(id, outputPath, {
+				source: setName,
+				isModifier: false
+			});
+		}
+	}
+	if (resolverSource.modifiers) {
+		for (const [modifierName, modifier] of Object.entries(resolverSource.modifiers)) if (modifier.contexts) for (const [contextName, contextSources] of Object.entries(modifier.contexts)) {
+			const contextKey = `${modifierName}-${contextName}`;
+			allContexts.add(contextKey);
+			if (Array.isArray(contextSources)) for (const source of contextSources) {
+				const tokenInfos = extractTokenIds(source);
+				for (const { id, outputPath } of tokenInfos) addTokenSource(id, outputPath, {
+					source: contextKey,
+					isModifier: true,
+					modifierName,
+					contextName
+				});
+			}
+		}
+	}
+	return {
+		tokenSources,
+		tokenOutputPaths,
+		allContexts
+	};
+}
+/**
+* Build the Figma-compatible JSON output from transformed tokens.
+* Requires a resolver file - legacy mode is not supported.
+* Always returns output split by resolver structure (sets and modifier contexts).
+*
+* @returns Map of output name to JSON string (e.g., "primitive" -> "{...}")
+*/
+function buildFigmaJson({ getTransforms, exclude, tokenName, preserveReferences = true, resolver }) {
+	const shouldExclude = createExcludeMatcher(exclude);
+	if (!hasValidResolverConfig(resolver)) {
+		const transforms = getTransforms({ format: FORMAT_ID });
+		if (transforms.length === 0) return /* @__PURE__ */ new Map();
+		const output = {};
+		for (const transform of transforms) {
+			if (!transform.token) continue;
+			const tokenId = transform.token.id;
+			if (shouldExclude(tokenId)) continue;
+			const outputName = tokenName?.(transform.token) ?? tokenId;
+			const parsedValue = parseTransformValue(transform.value);
+			if (!parsedValue) continue;
+			removeInternalMetadata(parsedValue);
+			setNestedProperty(output, outputName, parsedValue);
+		}
+		const result = /* @__PURE__ */ new Map();
+		result.set("default", JSON.stringify(output, null, 2));
+		return result;
+	}
+	const resolverSource = resolver.source;
+	if (!resolverSource) return /* @__PURE__ */ new Map();
+	const { tokenSources, tokenOutputPaths, allContexts } = buildTokenSourceMaps(resolverSource);
+	const outputBySource = /* @__PURE__ */ new Map();
+	for (const contextKey of allContexts) outputBySource.set(contextKey, {});
+	const defaultInput = buildDefaultInput(resolverSource);
+	const defaultTransforms = getTransforms({
+		format: FORMAT_ID,
+		input: defaultInput
+	});
+	for (const transform of defaultTransforms) {
+		const parsedValue = parseTransformValue(transform.value);
+		if (!parsedValue) continue;
+		let tokenId;
+		let outputName;
+		let aliasOf;
+		let sourceLookupId;
+		if (transform.token) {
+			tokenId = transform.token.id;
+			outputName = tokenName?.(transform.token) ?? tokenOutputPaths.get(tokenId) ?? tokenId;
+			aliasOf = parsedValue[INTERNAL_KEYS.ALIAS_OF] ?? transform.token.aliasOf;
+			sourceLookupId = tokenId;
+		} else if (parsedValue[INTERNAL_KEYS.SPLIT_FROM] && parsedValue[INTERNAL_KEYS.TOKEN_ID]) {
+			tokenId = parsedValue[INTERNAL_KEYS.TOKEN_ID];
+			const parentId = parsedValue[INTERNAL_KEYS.SPLIT_FROM];
+			const parentOutputPath = tokenOutputPaths.get(parentId);
+			if (parentOutputPath && parentOutputPath !== parentId) outputName = parentOutputPath + tokenId.slice(parentId.length);
+			else outputName = tokenId;
+			aliasOf = parsedValue[INTERNAL_KEYS.ALIAS_OF];
+			sourceLookupId = parentId;
+		} else continue;
+		if (shouldExclude(tokenId)) continue;
+		const setSource = (tokenSources.get(sourceLookupId) ?? []).find((s) => !s.isModifier);
+		if (!setSource) continue;
+		const sourceName = setSource.source;
+		let sourceOutput = outputBySource.get(sourceName);
+		if (!sourceOutput) {
+			sourceOutput = {};
+			outputBySource.set(sourceName, sourceOutput);
+		}
+		if (aliasOf) handleAliasReference({
+			parsedValue,
+			aliasOf,
+			sourceName,
+			tokenSources,
+			tokenOutputPaths,
+			preserveReferences
+		});
+		removeInternalMetadata(parsedValue);
+		setNestedProperty(sourceOutput, outputName, parsedValue);
+	}
+	const modifierTokensByContext = /* @__PURE__ */ new Map();
+	for (const [tokenId, sources] of tokenSources) for (const sourceInfo of sources) {
+		if (!sourceInfo.isModifier) continue;
+		const contextKey = sourceInfo.source;
+		const existing = modifierTokensByContext.get(contextKey);
+		if (existing) existing.add(tokenId);
+		else modifierTokensByContext.set(contextKey, new Set([tokenId]));
+	}
+	for (const [contextKey, tokenIds] of modifierTokensByContext) {
+		let contextInfo;
+		for (const tokenId of tokenIds) {
+			contextInfo = tokenSources.get(tokenId)?.find((s) => s.source === contextKey);
+			if (contextInfo) break;
+		}
+		if (!contextInfo?.modifierName || !contextInfo?.contextName) continue;
+		const input = { ...defaultInput };
+		input[contextInfo.modifierName] = contextInfo.contextName;
+		const contextTransforms = getTransforms({
+			format: FORMAT_ID,
+			input
+		});
+		let contextOutput = outputBySource.get(contextKey);
+		if (!contextOutput) {
+			contextOutput = {};
+			outputBySource.set(contextKey, contextOutput);
+		}
+		for (const tokenId of tokenIds) {
+			if (shouldExclude(tokenId)) continue;
+			const transform = contextTransforms.find((t) => t.token?.id === tokenId);
+			if (!transform) continue;
+			const outputName = tokenName?.(transform.token) ?? tokenOutputPaths.get(tokenId) ?? tokenId;
+			const parsedValue = parseTransformValue(transform.value);
+			if (!parsedValue) continue;
+			const aliasOf = parsedValue[INTERNAL_KEYS.ALIAS_OF] ?? transform.token.aliasOf;
+			if (aliasOf) handleAliasReference({
+				parsedValue,
+				aliasOf,
+				sourceName: contextKey,
+				tokenSources,
+				tokenOutputPaths,
+				preserveReferences
+			});
+			removeInternalMetadata(parsedValue);
+			setNestedProperty(contextOutput, outputName, parsedValue);
+		}
+	}
+	const result = /* @__PURE__ */ new Map();
+	for (const [sourceName, output] of outputBySource) result.set(sourceName, JSON.stringify(output, null, 2));
+	return result;
+}
+
+//#endregion
+//#region src/converters/color.ts
+/**
+* Number of decimal places to round color components to.
+* 6 decimals provides sufficient precision while avoiding floating-point issues.
+*/
+const COLOR_PRECISION = 6;
+/**
+* Round a number to COLOR_PRECISION decimal places and clamp to [0, 1] range.
+* Prevents floating-point precision issues (e.g., 1.0000000000000007 -> 1).
+*
+* @param value - Color component value (typically 0-1 for sRGB)
+* @returns Rounded and clamped value in [0, 1] range
+*/
+function roundAndClamp(value) {
+	const rounded = Math.round(value * 10 ** COLOR_PRECISION) / 10 ** COLOR_PRECISION;
+	return Math.max(0, Math.min(1, rounded));
+}
+/**
+* Normalize color components: round to precision and clamp to valid range.
+* Applies roundAndClamp to each component in the RGB/HSL triplet.
+*
+* @param components - Array of 3 color component values
+* @returns Normalized triplet with values rounded and clamped
+*/
+function normalizeComponents(components) {
+	return components.map(roundAndClamp);
+}
+/**
+* Map DTCG color space names to colorjs.io color space IDs.
+*/
+const DTCG_TO_COLORJS_SPACE = {
+	srgb: "srgb",
+	"srgb-linear": "srgb-linear",
+	hsl: "hsl",
+	hwb: "hwb",
+	lab: "lab",
+	lch: "lch",
+	oklab: "oklab",
+	oklch: "oklch",
+	"display-p3": "p3",
+	"a98-rgb": "a98rgb",
+	"prophoto-rgb": "prophoto",
+	rec2020: "rec2020",
+	"xyz-d65": "xyz-d65",
+	"xyz-d50": "xyz-d50"
+};
+/**
+* Convert a DTCG color value to Figma-compatible format.
+* Figma only supports sRGB and HSL color spaces.
+*
+* @example
+* // sRGB colors pass through unchanged
+* convertColor({
+*   colorSpace: "srgb",
+*   components: [0.5, 0.5, 0.5],
+*   alpha: 1
+* }, context);
+* // => { value: { colorSpace: "srgb", components: [0.5, 0.5, 0.5], alpha: 1 } }
+*
+* @example
+* // OKLCH colors are converted to sRGB
+* convertColor({
+*   colorSpace: "oklch",
+*   components: [0.7, 0.15, 150]
+* }, context);
+* // => { value: { colorSpace: "srgb", components: [...], alpha: 1 } }
+*/
+function convertColor(value, context) {
+	if (!isDTCGColorValue(value)) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has invalid color value: expected object with colorSpace and components`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	const color = value;
+	if (FIGMA_COLOR_SPACES.includes(color.colorSpace)) {
+		const components = color.components.map((c) => c === "none" ? 0 : c);
+		const normalizedComponents = color.colorSpace === "srgb" ? normalizeComponents(components) : components;
+		return { value: {
+			...color,
+			components: normalizedComponents,
+			alpha: color.alpha === "none" ? 1 : color.alpha ?? 1
+		} };
+	}
+	const components = color.components.map((c) => c === "none" ? 0 : c);
+	const colorjsSpace = DTCG_TO_COLORJS_SPACE[color.colorSpace];
+	if (!colorjsSpace) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has unknown color space: ${color.colorSpace}`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	try {
+		const srgbColor = new Color(colorjsSpace, components).to("srgb");
+		if (!srgbColor.inGamut()) {
+			context.logger.warn({
+				group: "plugin",
+				label: PLUGIN_NAME,
+				message: `Token "${context.tokenId}" color was clipped to sRGB gamut (original color space: ${color.colorSpace})`
+			});
+			srgbColor.toGamut({ method: "css" });
+		}
+		const srgbChannels = normalizeComponents(srgbColor.coords);
+		context.logger.info({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" color converted from ${color.colorSpace} to sRGB`
+		});
+		return { value: {
+			colorSpace: "srgb",
+			components: srgbChannels,
+			alpha: color.alpha === "none" ? 1 : color.alpha ?? 1
+		} };
+	} catch (err) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" color conversion failed: ${err instanceof Error ? err.message : String(err)}`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+}
+
+//#endregion
+//#region src/converters/dimension.ts
+/**
+* Convert a DTCG dimension value to Figma-compatible format.
+* Figma only supports px units.
+*
+* @example
+* // px values pass through unchanged
+* convertDimension({ value: 16, unit: "px" }, context);
+* // => { value: { value: 16, unit: "px" } }
+*
+* @example
+* // rem values are converted to px (default base: 16px)
+* convertDimension({ value: 1.5, unit: "rem" }, context);
+* // => { value: { value: 24, unit: "px" } }
+*/
+function convertDimension(value, context) {
+	if (!isDTCGDimensionValue(value)) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has invalid dimension value: expected object with value (number) and unit (string)`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	const dimension = value;
+	if (!Number.isFinite(dimension.value)) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has invalid dimension value: ${dimension.value}`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	if (dimension.unit === "px") return { value: dimension };
+	if (dimension.unit === "rem") {
+		const remBasePx = context.options.remBasePx ?? 16;
+		const pxValue = dimension.value * remBasePx;
+		context.logger.info({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" converted from ${dimension.value}rem to ${pxValue}px (base: ${remBasePx}px)`
+		});
+		return { value: {
+			value: pxValue,
+			unit: "px"
+		} };
+	}
+	context.logger.warn({
+		group: "plugin",
+		label: PLUGIN_NAME,
+		message: `Token "${context.tokenId}" has unsupported dimension unit: "${dimension.unit}". Figma only supports px units. Convert the value to px or use the 'transform' option to handle this token.`
+	});
+	return {
+		value: void 0,
+		skip: true
+	};
+}
+
+//#endregion
+//#region src/converters/duration.ts
+/**
+* Convert a DTCG duration value to Figma-compatible format.
+* Figma only supports seconds (s) unit.
+*
+* @example
+* // s values pass through unchanged
+* convertDuration({ value: 0.5, unit: "s" }, context);
+* // => { value: { value: 0.5, unit: "s" } }
+*
+* @example
+* // ms values are converted to s
+* convertDuration({ value: 500, unit: "ms" }, context);
+* // => { value: { value: 0.5, unit: "s" } }
+*/
+function convertDuration(value, context) {
+	if (!isDTCGDurationValue(value)) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has invalid duration value: expected object with value (number) and unit (string)`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	const duration = value;
+	if (!Number.isFinite(duration.value)) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has invalid duration value: ${duration.value}`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	if (duration.unit === "s") return { value: duration };
+	if (duration.unit === "ms") {
+		const sValue = duration.value / 1e3;
+		context.logger.info({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" converted from ${duration.value}ms to ${sValue}s`
+		});
+		return { value: {
+			value: sValue,
+			unit: "s"
+		} };
+	}
+	context.logger.warn({
+		group: "plugin",
+		label: PLUGIN_NAME,
+		message: `Token "${context.tokenId}" has unsupported duration unit: "${duration.unit}". Figma only supports seconds (s). Convert the value to seconds or use the 'transform' option to handle this token.`
+	});
+	return {
+		value: void 0,
+		skip: true
+	};
+}
+
+//#endregion
+//#region src/converters/font-family.ts
+/**
+* Convert a DTCG fontFamily value to Figma-compatible format.
+* Figma requires a single string, not an array.
+*
+* @example
+* // String values pass through unchanged
+* convertFontFamily("Inter", context);
+* // => { value: "Inter" }
+*
+* @example
+* // Arrays are truncated to the first element
+* convertFontFamily(["Inter", "Helvetica", "sans-serif"], context);
+* // => { value: "Inter" } (with warning about dropped fallbacks)
+*/
+function convertFontFamily(value, context) {
+	if (typeof value === "string") return { value };
+	if (Array.isArray(value)) {
+		if (value.length === 0) {
+			context.logger.warn({
+				group: "plugin",
+				label: PLUGIN_NAME,
+				message: `Token "${context.tokenId}" has empty fontFamily array`
+			});
+			return {
+				value: void 0,
+				skip: true
+			};
+		}
+		const firstFont = value[0];
+		if (value.length > 1) context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" fontFamily array truncated to first element "${firstFont}" (dropped: ${value.slice(1).join(", ")})`
+		});
+		return { value: firstFont };
+	}
+	context.logger.warn({
+		group: "plugin",
+		label: PLUGIN_NAME,
+		message: `Token "${context.tokenId}" has invalid fontFamily value: ${typeof value}`
+	});
+	return {
+		value: void 0,
+		skip: true
+	};
+}
+
+//#endregion
+//#region src/converters/font-weight.ts
+/**
+* Valid string aliases for font weights as per W3C DTCG spec.
+*/
+const FONT_WEIGHT_ALIASES = {
+	thin: 100,
+	hairline: 100,
+	"extra-light": 200,
+	"ultra-light": 200,
+	light: 300,
+	normal: 400,
+	regular: 400,
+	book: 400,
+	medium: 500,
+	"semi-bold": 600,
+	"demi-bold": 600,
+	bold: 700,
+	"extra-bold": 800,
+	"ultra-bold": 800,
+	black: 900,
+	heavy: 900,
+	"extra-black": 950,
+	"ultra-black": 950
+};
+/**
+* Convert a DTCG fontWeight value to Figma-compatible format.
+* Output type matches input type (string stays string, number stays number).
+*
+* @example
+* // Number values pass through with validation (1-1000)
+* convertFontWeight(400, context);
+* // => { value: 400 }
+*
+* @example
+* // String aliases pass through if valid
+* convertFontWeight("bold", context);
+* // => { value: "bold" }
+*/
+function convertFontWeight(value, context) {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value) || value < 1 || value > 1e3) {
+			context.logger.warn({
+				group: "plugin",
+				label: PLUGIN_NAME,
+				message: `Token "${context.tokenId}" has invalid fontWeight value: ${value} (must be 1-1000)`
+			});
+			return {
+				value: void 0,
+				skip: true
+			};
+		}
+		return {
+			value,
+			outputType: "number"
+		};
+	}
+	if (typeof value === "string") {
+		if (!(value.toLowerCase() in FONT_WEIGHT_ALIASES)) {
+			const validAliases = Object.keys(FONT_WEIGHT_ALIASES).slice(0, 5).join(", ");
+			context.logger.warn({
+				group: "plugin",
+				label: PLUGIN_NAME,
+				message: `Token "${context.tokenId}" has unknown fontWeight alias: "${value}". Valid aliases include: ${validAliases}, etc. Use a valid alias or a numeric weight (1-1000).`
+			});
+			return {
+				value: void 0,
+				skip: true
+			};
+		}
+		return {
+			value,
+			outputType: "string"
+		};
+	}
+	context.logger.warn({
+		group: "plugin",
+		label: PLUGIN_NAME,
+		message: `Token "${context.tokenId}" has invalid fontWeight type: ${typeof value}`
+	});
+	return {
+		value: void 0,
+		skip: true
+	};
+}
+
+//#endregion
+//#region src/converters/number.ts
+/**
+* Convert a DTCG number value to Figma-compatible format.
+* Can output as Boolean if token has com.figma.type extension set to "boolean".
+*
+* @example
+* // Regular number token
+* convertNumber(1.5, context) // => { value: 1.5 }
+*
+* @example
+* // Boolean extension: 0 becomes false, non-zero becomes true
+* // Token with $extensions: { "com.figma": { "type": "boolean" } }
+* convertNumber(0, contextWithBooleanExt) // => { value: false }
+* convertNumber(1, contextWithBooleanExt) // => { value: true }
+*/
+function convertNumber(value, context) {
+	if (typeof value !== "number") {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has invalid number value: ${typeof value}`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	if (!Number.isFinite(value)) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has non-finite number value: ${value}`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	if (context.extensions?.["com.figma.type"] === "boolean") return { value: value !== 0 };
+	return { value };
+}
+
+//#endregion
+//#region src/converters/line-height.ts
+/**
+* Convert a W3C DTCG lineHeight value to Figma-compatible format.
+*
+* ## W3C DTCG vs Figma Incompatibility
+*
+* The W3C DTCG specification defines lineHeight as a **number** type -
+* a unitless multiplier relative to fontSize (e.g., `1.5` means 1.5× the
+* font size). This matches CSS behavior where `line-height: 1.5` is unitless.
+*
+* However, Figma Variables require lineHeight to be a **dimension** type
+* with explicit px units. There is no way to represent a unitless multiplier
+* in Figma's variable system.
+*
+* ## Conversion Strategy
+*
+* This converter calculates the absolute lineHeight by multiplying the
+* unitless multiplier with the fontSize:
+*
+*   `absoluteLineHeight = lineHeight × fontSize`
+*
+* For example: `lineHeight: 1.5` with `fontSize: 16px` → `24px`
+*
+* ## Trade-off: Loss of Token Reference
+*
+* When converting a multiplier to an absolute dimension, any reference to
+* a primitive number token is lost. This is unavoidable because:
+*
+* 1. Figma does not support unitless multipliers for lineHeight
+* 2. We must compute a concrete px value at build time
+* 3. The computed value cannot maintain an alias to the original number token
+*
+* This approach is the most token-setup-agnostic solution, as it works
+* regardless of how the source tokens are structured.
+*
+* @example
+* // Input: W3C DTCG typography with number lineHeight
+* // lineHeight: 1.5, fontSize: { value: 16, unit: "px" }
+* convertLineHeight(1.5, { ...context, fontSize: { value: 16, unit: "px" } });
+* // Output: { value: { value: 24, unit: "px" } }
+*/
+function convertLineHeight(value, context) {
+	if (typeof value !== "number") {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has invalid lineHeight value: expected number (per W3C DTCG spec), got ${typeof value}`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	if (!Number.isFinite(value)) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has non-finite lineHeight value: ${value}`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	if (!context.fontSize) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has lineHeight multiplier (${value}) but no fontSize is defined. Cannot calculate absolute lineHeight for Figma. Provide a fontSize in the typography token.`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	const rawLineHeight = value * context.fontSize.value;
+	const shouldRound = context.options.roundLineHeight !== false;
+	const absoluteLineHeight = shouldRound ? Math.round(rawLineHeight) : rawLineHeight;
+	const roundingNote = shouldRound && rawLineHeight !== absoluteLineHeight ? ` (rounded from ${rawLineHeight})` : "";
+	context.logger.info({
+		group: "plugin",
+		label: PLUGIN_NAME,
+		message: `Token "${context.tokenId}" lineHeight: ${value} × ${context.fontSize.value}px = ${absoluteLineHeight}px${roundingNote} (converted from W3C multiplier to Figma dimension)`
+	});
+	return { value: {
+		value: absoluteLineHeight,
+		unit: "px"
+	} };
+}
+
+//#endregion
+//#region src/converters/typography.ts
+/**
+* Get the correct alias reference for a typography sub-property.
+* When a typography property references another typography token,
+* the alias needs to point to the corresponding sub-token.
+*
+* @param aliasOf - The referenced token ID, or undefined if not an alias
+* @param propertyName - The sub-property name (fontFamily, fontSize, etc.)
+* @param allTokens - Map of all tokens for type lookup
+* @returns Adjusted alias target, or undefined if not an alias
+*
+* @example
+* // If typography.base is a typography token:
+* getSubTokenAlias("typography.base", "fontFamily", tokens)
+* // "typography.base.fontFamily"
+*
+* // If dimension.100 is a primitive:
+* getSubTokenAlias("dimension.100", "fontSize", tokens)
+* // "dimension.100" (unchanged)
+*/
+function getSubTokenAlias(aliasOf, propertyName, allTokens) {
+	if (!aliasOf) return;
+	if ((allTokens?.[aliasOf])?.$type === "typography") return `${aliasOf}.${propertyName}`;
+	return aliasOf;
+}
+/**
+* Convert a DTCG typography value to Figma-compatible format.
+* Typography tokens are split into individual sub-tokens since Figma
+* doesn't support the composite typography type.
+*
+* @example
+* // Input typography token
+* convertTypography({
+*   fontFamily: "Inter",
+*   fontSize: { value: 16, unit: "px" },
+*   fontWeight: 400,
+*   lineHeight: 1.5,
+*   letterSpacing: { value: 0, unit: "px" }
+* }, context);
+* // => { value: undefined, split: true, subTokens: [...] }
+*/
+function convertTypography(value, context) {
+	if (!isDTCGTypographyValue(value)) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has invalid typography value: expected object, got ${typeof value}`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	const typography = value;
+	const partialAliasOf = context.partialAliasOf;
+	const subTokens = [];
+	if (typography.fontFamily !== void 0) {
+		const aliasOf = getSubTokenAlias(partialAliasOf?.fontFamily, "fontFamily", context.allTokens);
+		const result = convertFontFamily(typography.fontFamily, {
+			...context,
+			tokenId: `${context.tokenId}.fontFamily`
+		});
+		if (!result.skip) subTokens.push({
+			idSuffix: "fontFamily",
+			$type: "fontFamily",
+			value: result.value,
+			aliasOf
+		});
+	}
+	let resolvedFontSize;
+	if (typography.fontSize !== void 0) {
+		const aliasOf = getSubTokenAlias(partialAliasOf?.fontSize, "fontSize", context.allTokens);
+		const result = convertDimension(typography.fontSize, {
+			...context,
+			tokenId: `${context.tokenId}.fontSize`
+		});
+		if (!result.skip) {
+			resolvedFontSize = result.value;
+			subTokens.push({
+				idSuffix: "fontSize",
+				$type: "dimension",
+				value: result.value,
+				aliasOf
+			});
+		}
+	}
+	if (typography.fontWeight !== void 0) {
+		const aliasOf = getSubTokenAlias(partialAliasOf?.fontWeight, "fontWeight", context.allTokens);
+		const result = convertFontWeight(typography.fontWeight, {
+			...context,
+			tokenId: `${context.tokenId}.fontWeight`
+		});
+		if (!result.skip) subTokens.push({
+			idSuffix: "fontWeight",
+			$type: result.outputType ?? "fontWeight",
+			value: result.value,
+			aliasOf
+		});
+	}
+	if (typography.lineHeight !== void 0) {
+		const result = convertLineHeight(typography.lineHeight, {
+			...context,
+			tokenId: `${context.tokenId}.lineHeight`,
+			fontSize: resolvedFontSize
+		});
+		if (!result.skip) subTokens.push({
+			idSuffix: "lineHeight",
+			$type: "dimension",
+			value: result.value
+		});
+	}
+	if (typography.letterSpacing !== void 0) {
+		const aliasOf = getSubTokenAlias(partialAliasOf?.letterSpacing, "letterSpacing", context.allTokens);
+		const result = convertDimension(typography.letterSpacing, {
+			...context,
+			tokenId: `${context.tokenId}.letterSpacing`
+		});
+		if (!result.skip) subTokens.push({
+			idSuffix: "letterSpacing",
+			$type: "dimension",
+			value: result.value,
+			aliasOf
+		});
+	}
+	if (subTokens.length === 0) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" typography value has no valid sub-properties`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	return {
+		value: void 0,
+		split: true,
+		subTokens
+	};
+}
+
+//#endregion
+//#region src/converters/index.ts
+/**
+* Registry of converters by token type.
+*/
+const converters = {
+	color: convertColor,
+	dimension: convertDimension,
+	duration: convertDuration,
+	fontFamily: convertFontFamily,
+	fontWeight: convertFontWeight,
+	number: convertNumber,
+	typography: convertTypography
+};
+/**
+* Check if a token type is supported by Figma.
+*/
+function isSupportedType(type) {
+	return SUPPORTED_TYPES.includes(type);
+}
+/**
+* Check if a value is an alias reference (curly brace syntax).
+*/
+function isAlias(value) {
+	return typeof value === "string" && value.startsWith("{") && value.endsWith("}");
+}
+/**
+* Extract the token ID from an alias reference.
+* @param alias - The alias string, e.g., "{color.primary}"
+* @returns The token ID, e.g., "color.primary"
+*/
+function extractAliasTarget(alias) {
+	return alias.slice(1, -1);
+}
+/**
+* Validate an alias reference and return any warnings.
+*/
+function validateAlias(alias, context) {
+	const targetId = extractAliasTarget(alias);
+	if (!context.allTokens) return { valid: true };
+	const targetToken = context.allTokens[targetId];
+	if (!targetToken) return {
+		valid: false,
+		warning: `Token "${context.tokenId}" references non-existent token "${targetId}". Check the token path for typos or ensure the referenced token is defined.`
+	};
+	if (!isSupportedType(targetToken.$type)) return {
+		valid: false,
+		warning: UNSUPPORTED_TYPES.includes(targetToken.$type) ? `Token "${context.tokenId}" aliases unsupported type "${targetToken.$type}" (from "${targetId}"). This alias will be preserved but may not work in Figma. Consider referencing a supported token type instead.` : `Token "${context.tokenId}" aliases unknown type "${targetToken.$type}" (from "${targetId}"). This alias will be preserved but may not work in Figma. Verify the target token has a supported type.`
+	};
+	return { valid: true };
+}
+/**
+* Convert a token value to Figma-compatible format.
+*
+* @param token - The normalized token
+* @param value - The token value to convert
+* @param context - Converter context with logger and options
+* @returns Converted value or skip indicator
+*/
+function convertToken(token, value, context) {
+	const { $type } = token;
+	if (!$type) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" is missing $type. Ensure all tokens have a valid $type defined either directly or inherited from a parent group.`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	if (value === void 0 || value === null) {
+		context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: `Token "${context.tokenId}" has no value (${value}). Ensure $value is defined for this token.`
+		});
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	if (isAlias(value)) {
+		const validation = validateAlias(value, context);
+		if (validation.warning) context.logger.warn({
+			group: "plugin",
+			label: PLUGIN_NAME,
+			message: validation.warning
+		});
+		return { value };
+	}
+	if (!isSupportedType($type)) {
+		const isKnownUnsupported = UNSUPPORTED_TYPES.includes($type);
+		if (context.options.warnOnUnsupported !== false) {
+			const suggestion = isKnownUnsupported ? ` Consider excluding this token with the 'exclude' option, or use a supported type (color, dimension, duration, fontFamily, fontWeight, number).` : ` If this is a custom type, consider using the 'transform' option to convert it to a supported format.`;
+			context.logger.warn({
+				group: "plugin",
+				label: PLUGIN_NAME,
+				message: isKnownUnsupported ? `Token "${context.tokenId}" has unsupported type "${$type}" and will be skipped.${suggestion}` : `Token "${context.tokenId}" has unknown type "${$type}" and will be skipped.${suggestion}`
+			});
+		}
+		return {
+			value: void 0,
+			skip: true
+		};
+	}
+	const converter = converters[$type];
+	return converter(value, context);
+}
+
+//#endregion
+//#region src/transform.ts
+/**
+* Register a transform with optional resolver input.
+* Encapsulates the conditional logic for input presence.
+*/
+function registerTransform(setTransform, id, value, input) {
+	if (input) setTransform(id, {
+		format: FORMAT_ID,
+		value,
+		input
+	});
+	else setTransform(id, {
+		format: FORMAT_ID,
+		value
+	});
+}
+/**
+* Filter extensions to only include Figma-specific ones (com.figma.*).
+* Removes non-Figma extensions to keep output clean.
+*
+* @param extensions - Token extensions object that may include various namespaces
+* @returns Object with only com.figma.* keys, or undefined if none exist
+*
+* @example
+* filterFigmaExtensions({ "com.figma.type": "boolean", "custom.ext": "value" })
+* // { "com.figma.type": "boolean" }
+*/
+function filterFigmaExtensions(extensions) {
+	if (!extensions) return;
+	const figmaExtensions = {};
+	let hasFigmaExtensions = false;
+	for (const [key, value] of Object.entries(extensions)) if (key.startsWith("com.figma")) {
+		figmaExtensions[key] = value;
+		hasFigmaExtensions = true;
+	}
+	return hasFigmaExtensions ? figmaExtensions : void 0;
+}
+/**
+* Transform a single token and register it via setTransform.
+* Handles custom transforms, split tokens (typography), and alias references.
+*
+* @param token - The normalized token from terrazzo parser
+* @param rawValue - The resolved token value
+* @param aliasOf - Target token ID if this is an alias, undefined otherwise
+* @param options - Plugin configuration options
+* @param context - Plugin hook context with logger
+* @param allTokens - Map of all tokens for alias validation
+* @param setTransform - Terrazzo callback to register transformed value
+* @param input - Optional resolver input. When omitted, uses legacy mode without resolver.
+*/
+function transformToken(token, rawValue, aliasOf, options, context, allTokens, setTransform, input) {
+	const customValue = options.transform?.(token);
+	if (customValue !== void 0) {
+		registerTransform(setTransform, token.id, JSON.stringify(customValue), input);
+		return;
+	}
+	const partialAliasOf = getPartialAliasOf(token);
+	const result = convertToken(token, rawValue, {
+		logger: context.logger,
+		options,
+		tokenId: token.id,
+		extensions: token.$extensions,
+		allTokens,
+		originalValue: token.originalValue?.$value,
+		partialAliasOf
+	});
+	if (result.skip) return;
+	if (result.split && result.subTokens) {
+		for (const subToken of result.subTokens) {
+			const subId = `${token.id}.${subToken.idSuffix}`;
+			const transformedValue = {
+				$type: subToken.$type,
+				$value: subToken.value,
+				[INTERNAL_KEYS.SPLIT_FROM]: token.id,
+				[INTERNAL_KEYS.TOKEN_ID]: subId
+			};
+			if (subToken.aliasOf) transformedValue[INTERNAL_KEYS.ALIAS_OF] = subToken.aliasOf;
+			if (token.$description) transformedValue.$description = token.$description;
+			const subTokenFigmaExtensions = filterFigmaExtensions(token.$extensions);
+			if (subTokenFigmaExtensions) transformedValue.$extensions = subTokenFigmaExtensions;
+			registerTransform(setTransform, subId, JSON.stringify(transformedValue), input);
+		}
+		return;
+	}
+	const transformedValue = {
+		$type: result.outputType ?? token.$type,
+		$value: result.value
+	};
+	if (token.$description) transformedValue.$description = token.$description;
+	const figmaExtensions = filterFigmaExtensions(token.$extensions);
+	if (figmaExtensions) transformedValue.$extensions = figmaExtensions;
+	if (aliasOf) {
+		const originalValueStr = token.originalValue?.$value;
+		let directAliasOf = aliasOf;
+		if (typeof originalValueStr === "string" && originalValueStr.startsWith("{") && originalValueStr.endsWith("}")) directAliasOf = originalValueStr.slice(1, -1);
+		transformedValue[INTERNAL_KEYS.ALIAS_OF] = directAliasOf;
+	} else if (token.$type === "color" && partialAliasOf) {
+		const colorPartialAlias = partialAliasOf;
+		const refs = [];
+		if (colorPartialAlias.colorSpace) refs.push(colorPartialAlias.colorSpace);
+		if (colorPartialAlias.components) {
+			for (const comp of colorPartialAlias.components) if (comp) refs.push(comp);
+		}
+		if (refs.length > 0) {
+			const uniqueRefs = [...new Set(refs)];
+			if (uniqueRefs.length === 1) transformedValue[INTERNAL_KEYS.ALIAS_OF] = uniqueRefs[0];
+		}
+	}
+	registerTransform(setTransform, token.id, JSON.stringify(transformedValue), input);
+}
+/**
+* Transform DTCG tokens into Figma-compatible format.
+* Supports both resolver-based and non-resolver workflows.
+*/
+function transformFigmaJson({ transform, options }) {
+	const { setTransform, context, resolver, tokens } = transform;
+	const shouldExclude = createExcludeMatcher(options.exclude);
+	if (!hasValidResolverConfig(resolver)) {
+		for (const token of Object.values(tokens)) {
+			if (shouldExclude(token.id)) continue;
+			transformToken(token, token.$value, token.aliasOf, options, context, tokens, setTransform);
+		}
+		return;
+	}
+	const permutations = resolver.listPermutations();
+	for (const input of permutations) {
+		const contextTokens = resolver.apply(input);
+		for (const token of Object.values(contextTokens)) {
+			if (shouldExclude(token.id)) continue;
+			transformToken(token, token.$value, token.aliasOf, options, context, contextTokens, setTransform, input);
+		}
+	}
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* Terrazzo plugin to convert DTCG design tokens to Figma-compatible JSON format.
+*
+* @example
+* // Basic usage
+* import { defineConfig } from "@terrazzo/cli";
+* import figmaJson from "terrazzo-plugin-figma-json";
+*
+* export default defineConfig({
+*   plugins: [
+*     figmaJson({ filename: "tokens.figma.json" }),
+*   ],
+* });
+*
+* @example
+* // With all options
+* figmaJson({
+*   filename: "design-tokens.figma.json",
+*   exclude: ["internal.*", "deprecated.*"],
+*   remBasePx: 16,
+*   warnOnUnsupported: true,
+*   preserveReferences: true,
+*   tokenName: (token) => token.id.replace("color.", "brand."),
+*   transform: (token) => {
+*     if (token.id === "special.token") return { custom: true };
+*     return undefined; // Use default transformation
+*   },
+* });
+*
+*/
+function figmaJsonPlugin(options) {
+	const { skipBuild } = options ?? {};
+	const filename = options?.filename ?? "tokens.figma.json";
+	return {
+		name: PLUGIN_NAME,
+		async transform(transformOptions) {
+			if (transformOptions.getTransforms({
+				format: FORMAT_ID,
+				id: "*"
+			}).length) return;
+			transformFigmaJson({
+				transform: transformOptions,
+				options: options ?? {}
+			});
+		},
+		async build({ getTransforms, outputFile, resolver }) {
+			if (skipBuild === true) return;
+			const result = buildFigmaJson({
+				getTransforms,
+				exclude: options?.exclude,
+				tokenName: options?.tokenName,
+				preserveReferences: options?.preserveReferences,
+				resolver
+			});
+			for (const [sourceName, contents] of result) outputFile(sourceName === "default" ? filename : `${sourceName}.${filename}`, contents);
+		}
+	};
+}
+
+//#endregion
+export { FIGMA_COLOR_SPACES, FORMAT_ID, INTERNAL_KEYS, PLUGIN_NAME, SUPPORTED_TYPES, UNSUPPORTED_TYPES, buildDefaultInput, createExcludeMatcher, figmaJsonPlugin as default, getPartialAliasOf, hasValidResolverConfig, isDTCGColorValue, isDTCGDimensionValue, isDTCGDurationValue, isDTCGTypographyValue, parseTransformValue, removeInternalMetadata };
+//# sourceMappingURL=index.js.map