terrazzo-plugin-figma-json 0.1.1 → 0.3.0

package/README.md

@@ -4,18 +4,16 @@ A [Terrazzo](https://terrazzo.app) plugin that converts W3C DTCG design tokens i
 
 ## Requirements
 
-This plugin requires Terrazzo 2.0.0-beta.0 or later:
+This plugin requires Terrazzo 2.0:
 
 ```bash
-npm install @terrazzo/cli@2.0.0-beta.0 @terrazzo/parser@2.0.0-beta.0
+npm install @terrazzo/cli
 ```
 
 ## Installation
 
 ```bash
 npm install terrazzo-plugin-figma-json
-# or
-pnpm add terrazzo-plugin-figma-json
 ```
 
 ## Basic Usage
@@ -61,11 +59,11 @@ With a resolver file, the plugin splits output by resolver sets and modifier con
 
 ```
 dist/
-├── primitive.figma.json       # From "primitive" set
-├── semantic.figma.json        # From "semantic" set
-├── colorScheme-light.figma.json
-├── colorScheme-dark.figma.json
-└── breakpoint-small.figma.json
+├── primitive.tokens.figma.json       # From "primitive" set
+├── semantic.tokens.figma.json        # From "semantic" set
+├── colorScheme-light.tokens.figma.json
+├── colorScheme-dark.tokens.figma.json
+└── breakpoint-small.tokens.figma.json
 ```
 
 Without a resolver, all tokens are output to a single file (`tokens.figma.json` by default).
@@ -81,6 +79,9 @@ Without a resolver, all tokens are output to a single file (`tokens.figma.json`
 | `fontWeight` | Number or String | Values pass through with validation |
 | `number` | Number or Boolean | Numbers pass through; use `com.figma.type: "boolean"` for booleans |
 | `typography` | Split tokens | Split into fontFamily, fontSize, fontWeight, lineHeight, letterSpacing |
+| `shadow` | Split tokens | Split into color, offsetX, offsetY, blur, spread; indexed for multiple layers (`inset` not applicable in Figma) |
+| `border` | Split tokens (partial) | Split into color, width (`style` not applicable in Figma) |
+| `gradient` | Split tokens (partial) | Stop colors extracted (`position` not applicable in Figma) |
 
 ### Typography Token Splitting
 
@@ -121,11 +122,113 @@ Figma doesn't support composite typography tokens, so they're automatically spli
 
 Note: `lineHeight` is converted from a unitless multiplier to absolute px (see [Figma Limitations](#figma-limitations)).
 
+### Shadow Token Splitting
+
+Shadow tokens are split into individual sub-tokens. Array shadows (multiple layers) use indexed prefixes.
+
+**Input:**
+```json
+{
+  "shadow": {
+    "$type": "shadow",
+    "medium": {
+      "$value": {
+        "color": { "colorSpace": "srgb", "components": [0, 0, 0], "alpha": 0.2 },
+        "offsetX": { "value": 0, "unit": "px" },
+        "offsetY": { "value": 4, "unit": "px" },
+        "blur": { "value": 8, "unit": "px" },
+        "spread": { "value": 0, "unit": "px" }
+      }
+    }
+  }
+}
+```
+
+**Output:**
+```json
+{
+  "shadow": {
+    "medium": {
+      "color": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0, 0, 0], "alpha": 0.2 } },
+      "offsetX": { "$type": "dimension", "$value": { "value": 0, "unit": "px" } },
+      "offsetY": { "$type": "dimension", "$value": { "value": 4, "unit": "px" } },
+      "blur": { "$type": "dimension", "$value": { "value": 8, "unit": "px" } },
+      "spread": { "$type": "dimension", "$value": { "value": 0, "unit": "px" } }
+    }
+  }
+}
+```
+
+Note: Single shadows produce flat sub-tokens. Multiple shadow layers (arrays with 2+ items) use indexed prefixes (`0.color`, `0.offsetX`, ..., `1.color`, etc.). The `inset` property is dropped since variables cannot be applied to inset shadows in Figma.
+
+### Border Token Splitting (Partial)
+
+Border tokens are partially split — only `color` and `width` are extracted. The `style` property is dropped since variables cannot be applied to border style in Figma.
+
+**Input:**
+```json
+{
+  "border": {
+    "$type": "border",
+    "default": {
+      "$value": {
+        "color": { "colorSpace": "srgb", "components": [0.8, 0.8, 0.8] },
+        "width": { "value": 1, "unit": "px" },
+        "style": "solid"
+      }
+    }
+  }
+}
+```
+
+**Output:**
+```json
+{
+  "border": {
+    "default": {
+      "color": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0.8, 0.8, 0.8], "alpha": 1 } },
+      "width": { "$type": "dimension", "$value": { "value": 1, "unit": "px" } }
+    }
+  }
+}
+```
+
+### Gradient Token Splitting (Partial)
+
+Gradient tokens are partially split — only stop colors are extracted. Stop `position` values are dropped since variables cannot be applied to gradient stop positions in Figma.
+
+**Input:**
+```json
+{
+  "gradient": {
+    "$type": "gradient",
+    "primary": {
+      "$value": [
+        { "color": { "colorSpace": "srgb", "components": [1, 0, 0] }, "position": 0 },
+        { "color": { "colorSpace": "srgb", "components": [0, 0, 1] }, "position": 1 }
+      ]
+    }
+  }
+}
+```
+
+**Output:**
+```json
+{
+  "gradient": {
+    "primary": {
+      "0": { "color": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [1, 0, 0], "alpha": 1 } } },
+      "1": { "color": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0, 0, 1], "alpha": 1 } } }
+    }
+  }
+}
+```
+
 ## Unsupported Token Types
 
 The following DTCG token types are **not supported** by Figma and will be skipped:
 
-- `shadow`, `border`, `gradient`, `transition`, `strokeStyle`, `cubicBezier`
+- `transition`, `strokeStyle`, `cubicBezier`
 
 ## Alias Handling
 

package/dist/build/aliases.d.ts

@@ -0,0 +1,80 @@
+import type { TokenNormalized } from '@terrazzo/parser';
+import type { SupportedType } from '../constants.js';
+import type { PartialAliasOf } from '../types.js';
+import type { AliasReferenceOptions, ParsedTokenValue } from './types.js';
+/**
+ * Extract partialAliasOf from a token if present.
+ * This property is added by terrazzo parser for composite tokens but not in public types.
+ *
+ * @param token - The token object to inspect
+ * @returns The partialAliasOf record mapping sub-properties to alias targets, or undefined
+ */
+export declare function getPartialAliasOf(token: unknown): PartialAliasOf | undefined;
+/**
+ * Get the correct alias reference for a composite sub-property.
+ * When a composite property references another composite token of the same type,
+ * the alias needs to point to the corresponding sub-token.
+ *
+ * @param aliasOf - The raw alias target token ID, or undefined if not an alias
+ * @param propertyName - The sub-property name (e.g., "color", "width")
+ * @param allTokens - Map of all tokens for type checking
+ * @param parentType - The parent composite token's type (e.g., "border", "shadow")
+ * @returns The resolved alias target (with sub-property suffix if needed), or undefined
+ */
+export declare function getSubTokenAlias(aliasOf: string | undefined, propertyName: string, allTokens: Record<string, {
+    $type?: string;
+}> | undefined, parentType: SupportedType): string | undefined;
+/**
+ * Compute the direct alias target for a simple (non-composite) token.
+ *
+ * @param token - The normalized token to inspect
+ * @returns The direct alias target token ID, or undefined if the token is not an alias
+ */
+export declare function getDirectAliasTarget(token: TokenNormalized): string | undefined;
+/**
+ * For tokens without a direct alias, check if all sub-property references
+ * in partialAliasOf point to the same token. If so, the token can be treated
+ * as a unified alias to that single target.
+ *
+ * This handles cases like JSON pointer references where individual sub-properties
+ * (e.g., colorSpace, components[0], components[1], etc.) all reference the same
+ * source token.
+ *
+ * Works for any token type with partialAliasOf — colors, borders, shadows, etc.
+ *
+ * @param token - The normalized token to inspect
+ * @returns The unified alias target token ID, or undefined if refs are mixed or absent
+ */
+export declare function getUnifiedPartialAlias(token: TokenNormalized): string | undefined;
+/**
+ * Compute the alias target for a token, considering direct aliases and
+ * unified partial aliases (where all sub-property refs point to the same token).
+ *
+ * @param token - The normalized token to inspect
+ * @returns The alias target token ID, or undefined if the token is not an alias
+ */
+export declare function computeAliasTarget(token: TokenNormalized): string | undefined;
+/**
+ * Compute alias targets for each sub-property of a composite token.
+ *
+ * @param token - The normalized composite token
+ * @param subTokenSuffixes - Array of sub-property suffixes to resolve (e.g., ["color", "width"])
+ * @param allTokens - Map of all tokens for type checking during alias resolution
+ * @returns Map from sub-property suffix to alias target token ID (or undefined if not aliased)
+ */
+export declare function computeSubTokenAliases(token: TokenNormalized, subTokenSuffixes: string[], allTokens: Record<string, TokenNormalized> | undefined): Map<string, string | undefined>;
+/**
+ * Resolve an alias reference and return a new ParsedTokenValue with the
+ * appropriate $value or $extensions set.
+ *
+ * - 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
+ *
+ * Returns the original value unchanged if no alias handling applies.
+ *
+ * @param parsedValue - The parsed token value to potentially augment with alias info
+ * @param options - Alias resolution options including target, source context, and reference maps
+ * @returns A new ParsedTokenValue with alias reference syntax or extension, or the original value unchanged
+ */
+export declare function withAliasReference(parsedValue: ParsedTokenValue, { aliasOf, sourceName, tokenSources, tokenOutputPaths, preserveReferences }: AliasReferenceOptions): ParsedTokenValue;
+//# sourceMappingURL=aliases.d.ts.map

package/dist/build/aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../../src/build/aliases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAyB,MAAM,aAAa,CAAC;AAGzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAc,MAAM,YAAY,CAAC;AAEtF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAQ5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,EACzD,UAAU,EAAE,aAAa,GACxB,MAAM,GAAG,SAAS,CASpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAc/E;AAuBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAsBjF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,eAAe,EACtB,gBAAgB,EAAE,MAAM,EAAE,EAC1B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,GACrD,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAWjC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,gBAAgB,EAC7B,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,EAAE,qBAAqB,GACjG,gBAAgB,CAgDlB"}

package/dist/build/helpers.d.ts

@@ -0,0 +1,52 @@
+import type { Resolver } from '@terrazzo/parser';
+import type { ParsedTokenValue } from './types.js';
+/**
+ * Set a nested property on an object using dot-notation path.
+ * Creates intermediate objects as needed.
+ * Note: this intentionally mutates `obj` for efficient output tree construction.
+ *
+ * @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" } } }
+ */
+export declare function setNestedProperty(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * 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 - The token path that may contain ".$root" segments
+ * @returns The path with ".$root" replaced by ".root"
+ */
+export declare function normalizeRootInPath(path: string): string;
+/**
+ * Check if this resolver is the auto-generated default (no user-defined resolver file).
+ * The default resolver has only an "allTokens" set and a "tzMode" modifier with "." context.
+ *
+ * @param resolverSource - The resolver source configuration to inspect
+ * @returns True if this is the auto-generated default resolver
+ */
+export declare function isDefaultResolver(resolverSource: NonNullable<Resolver['source']>): boolean;
+/**
+ * Build a default input from the resolver's first permutation.
+ *
+ * @param resolver - The terrazzo resolver instance
+ * @returns The first permutation input object, or an empty object if none exist
+ */
+export declare function getDefaultInput(resolver: Resolver): Record<string, string>;
+/**
+ * Return a new ParsedTokenValue with $description and filtered $extensions added.
+ *
+ * @param parsedValue - The parsed token value to augment
+ * @param token - The source token containing $description and $extensions metadata
+ * @returns A new ParsedTokenValue with description and Figma-specific extensions merged in
+ */
+export declare function withTokenMetadata(parsedValue: ParsedTokenValue, token: {
+    $description?: string;
+    $extensions?: Record<string, unknown>;
+}): ParsedTokenValue;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/build/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/build/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGjD,OAAO,KAAK,EAAyB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAkBlG;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,GAAG,OAAO,CAsB1F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAG1E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,gBAAgB,EAC7B,KAAK,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACtE,gBAAgB,CAqBlB"}

package/dist/build/index.d.ts

@@ -0,0 +1,11 @@
+import type { BuildOptions } from './types.js';
+export type { BuildOptions } from './types.js';
+/**
+ * Build the Figma-compatible JSON output from transformed tokens.
+ * Uses the resolver to determine output file structure.
+ *
+ * @param options - Build options including getTransforms, exclude patterns, tokenName, preserveReferences, and resolver
+ * @returns Map of output name to JSON string (e.g., "primitive" → "{...}", "default" for single-file output)
+ */
+export default function buildFigmaJson({ getTransforms, exclude, tokenName, preserveReferences, resolver, }: BuildOptions): Map<string, string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/build/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAE3D,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CAAC,EACrC,aAAa,EACb,OAAO,EACP,SAAS,EACT,kBAAyB,EACzB,QAAQ,GACT,EAAE,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAgKpC"}

package/dist/build/output.d.ts

@@ -0,0 +1,28 @@
+import type { TokenNormalized } from '@terrazzo/parser';
+import type { FigmaJsonPluginOptions } from '../types.js';
+import type { SourceInfo } from './types.js';
+/**
+ * Process a single transform and place it in the output object.
+ * Handles both simple tokens (string value) and composite tokens (Record<string, string> value).
+ *
+ * Alias resolution is computed here from the token metadata (transform.token)
+ * rather than from embedded internal metadata in the value.
+ *
+ * Note: this intentionally mutates `output` via setNestedProperty for efficient
+ * output tree construction.
+ *
+ * @param transform - The transform result containing the token and its transformed value
+ * @param output - The mutable output object to place the token into (mutated in place)
+ * @param sourceName - The current source/context name for alias resolution
+ * @param tokenName - Optional custom function to control the output token name
+ * @param tokenOutputPaths - Map of token IDs to their output paths
+ * @param tokenSources - Map of token IDs to their source info for cross-file alias resolution
+ * @param preserveReferences - Whether to preserve alias references in output
+ * @param shouldExclude - Function to check if a token ID should be excluded
+ * @param allTokens - Map of all tokens for composite alias resolution
+ */
+export declare function processTransform(transform: {
+    token: TokenNormalized;
+    value: string | Record<string, string>;
+}, output: Record<string, unknown>, sourceName: string, tokenName: FigmaJsonPluginOptions['tokenName'], tokenOutputPaths: Map<string, string>, tokenSources: Map<string, SourceInfo[]>, preserveReferences: boolean, shouldExclude: (id: string) => boolean, allTokens: Record<string, TokenNormalized> | undefined): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/build/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/build/output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAI1D,OAAO,KAAK,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE;IACT,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC,EACD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,sBAAsB,CAAC,WAAW,CAAC,EAC9C,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,EACvC,kBAAkB,EAAE,OAAO,EAC3B,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,EACtC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,GACrD,IAAI,CA2EN"}

package/dist/build/source-maps.d.ts

@@ -0,0 +1,20 @@
+import type { Resolver } from '@terrazzo/parser';
+import type { TokenIdInfo, TokenSourceMaps } from './types.js';
+/**
+ * Extract token IDs from a resolver group (token definitions).
+ * Recursively walks the group structure to find all token IDs.
+ *
+ * @param group - The resolver group object containing nested token definitions
+ * @param prefix - Dot-notation prefix for building full token paths (used in recursion)
+ * @returns Array of token ID info objects with normalized IDs and output paths
+ */
+export declare function extractTokenIds(group: Record<string, unknown>, prefix?: string): TokenIdInfo[];
+/**
+ * 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 containing sets and modifiers
+ * @returns Token source maps with tokenSources, tokenOutputPaths, and allContexts
+ */
+export declare function buildTokenSourceMaps(resolverSource: NonNullable<Resolver['source']>): TokenSourceMaps;
+//# sourceMappingURL=source-maps.d.ts.map

package/dist/build/source-maps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-maps.d.ts","sourceRoot":"","sources":["../../src/build/source-maps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAc,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,SAAK,GAAG,WAAW,EAAE,CAsB1F;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,GAAG,eAAe,CAqErG"}

package/dist/build/types.d.ts

@@ -0,0 +1,69 @@
+import type { BuildHookOptions, Resolver } from '@terrazzo/parser';
+import type { FigmaJsonPluginOptions } from '../types.js';
+/**
+ * Options for the build function.
+ */
+export interface BuildOptions {
+    exclude: FigmaJsonPluginOptions['exclude'];
+    tokenName?: FigmaJsonPluginOptions['tokenName'];
+    getTransforms: BuildHookOptions['getTransforms'];
+    preserveReferences?: FigmaJsonPluginOptions['preserveReferences'];
+    resolver: Resolver;
+}
+/**
+ * Token source tracking info — records which resolver set or modifier context
+ * a token belongs to.
+ */
+export interface SourceInfo {
+    source: string;
+    isModifier: boolean;
+    modifierName?: string;
+    contextName?: string;
+}
+/**
+ * Token ID info including the output path (which may differ from the
+ * normalized ID due to $root renaming).
+ */
+export interface TokenIdInfo {
+    id: string;
+    outputPath: string;
+}
+/**
+ * Options for alias reference resolution.
+ */
+export interface AliasReferenceOptions {
+    aliasOf: string;
+    sourceName: string;
+    tokenSources: Map<string, SourceInfo[]>;
+    tokenOutputPaths: Map<string, string>;
+    preserveReferences: boolean;
+}
+/**
+ * Figma extensions object shape for build output.
+ */
+export interface FigmaOutputExtensions {
+    'com.figma.type'?: string;
+    'com.figma.aliasData'?: {
+        targetVariableSetName: string;
+        targetVariableName: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Shape of a parsed transform value after JSON.parse.
+ */
+export interface ParsedTokenValue {
+    $type: string;
+    $value: unknown;
+    $description?: string;
+    $extensions?: FigmaOutputExtensions;
+}
+/**
+ * Result of building token source maps from a resolver.
+ */
+export interface TokenSourceMaps {
+    tokenSources: Map<string, SourceInfo[]>;
+    tokenOutputPaths: Map<string, string>;
+    allContexts: Set<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/build/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAC3C,SAAS,CAAC,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;IAChD,aAAa,EAAE,gBAAgB,CAAC,eAAe,CAAC,CAAC;IACjD,kBAAkB,CAAC,EAAE,sBAAsB,CAAC,oBAAoB,CAAC,CAAC;IAClE,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IACxC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE;QACtB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,kBAAkB,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IACxC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1B"}

package/dist/constants.d.ts

@@ -1,26 +1,14 @@
 export declare const PLUGIN_NAME = "terrazzo-plugin-figma-json";
 export declare const FORMAT_ID = "figma-json";
-/**
- * Internal metadata property keys used for token processing.
- * These are added during transform and removed during build.
- */
-export declare const INTERNAL_KEYS: {
-    /** Target token ID for alias references */
-    readonly ALIAS_OF: "_aliasOf";
-    /** Parent token ID for split sub-tokens (e.g., typography) */
-    readonly SPLIT_FROM: "_splitFrom";
-    /** Token ID for split sub-tokens */
-    readonly TOKEN_ID: "_tokenId";
-};
 /**
  * Token types supported by Figma.
  */
-export declare const SUPPORTED_TYPES: readonly ["color", "dimension", "duration", "fontFamily", "fontWeight", "number", "typography"];
+export declare const SUPPORTED_TYPES: readonly ["color", "dimension", "duration", "fontFamily", "fontWeight", "number", "typography", "shadow", "border", "gradient"];
 export type SupportedType = (typeof SUPPORTED_TYPES)[number];
 /**
  * Token types that are not supported by Figma and will be dropped with a warning.
  */
-export declare const UNSUPPORTED_TYPES: readonly ["shadow", "border", "gradient", "transition", "strokeStyle", "cubicBezier"];
+export declare const UNSUPPORTED_TYPES: readonly ["transition", "strokeStyle", "cubicBezier"];
 export type UnsupportedType = (typeof UNSUPPORTED_TYPES)[number];
 /**
  * Color spaces that Figma natively supports.

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,+BAA+B,CAAC;AAExD,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,aAAa;IACxB,2CAA2C;;IAE3C,8DAA8D;;IAE9D,oCAAoC;;CAE5B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,eAAe,iGAQlB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,iBAAiB,uFAAwF,CAAC;AAEvH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,kBAAkB,0BAA2B,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,+BAA+B,CAAC;AAExD,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC;;GAEG;AACH,eAAO,MAAM,eAAe,iIAWlB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,iBAAiB,uDAAwD,CAAC;AAEvF,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,kBAAkB,0BAA2B,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/converters/border.d.ts

@@ -0,0 +1,12 @@
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * Convert a DTCG border value to Figma-compatible format.
+ * Border tokens are partially split into individual sub-tokens.
+ * Only color and width are supported; style is dropped.
+ *
+ * @param value - The DTCG border value (object with color, width, and optional style)
+ * @param context - Converter context with logger and plugin options
+ * @returns Split result with color and width sub-tokens, or skip indicator for invalid values
+ */
+export declare function convertBorder(value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=border.d.ts.map

package/dist/converters/border.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"border.d.ts","sourceRoot":"","sources":["../../src/converters/border.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAY,MAAM,aAAa,CAAC;AAK/E;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAsDxF"}

package/dist/converters/color.d.ts

@@ -19,6 +19,10 @@ import type { ConverterContext, ConverterResult } from '../types.js';
  *   components: [0.7, 0.15, 150]
  * }, context);
  * // => { value: { colorSpace: "srgb", components: [...], alpha: 1 } }
+ *
+ * @param value - The DTCG color value to convert (should match DTCGColorValue structure)
+ * @param context - Converter context with logger and plugin options
+ * @returns Converted color value in sRGB or HSL, or skip indicator for invalid values
  */
 export declare function convertColor(value: unknown, context: ConverterContext): ConverterResult;
 //# sourceMappingURL=color.d.ts.map

package/dist/converters/color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/converters/color.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAkB,MAAM,aAAa,CAAC;AAoDrF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAoFvF"}
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/converters/color.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAkB,MAAM,aAAa,CAAC;AAoDrF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAoFvF"}

package/dist/converters/dimension.d.ts

@@ -12,6 +12,10 @@ import type { ConverterContext, ConverterResult } from '../types.js';
  * // rem values are converted to px (default base: 16px)
  * convertDimension({ value: 1.5, unit: "rem" }, context);
  * // => { value: { value: 24, unit: "px" } }
+ *
+ * @param value - The DTCG dimension value to convert (should match DTCGDimensionValue structure)
+ * @param context - Converter context with logger and plugin options (includes remBasePx)
+ * @returns Converted dimension in px units, or skip indicator for unsupported units
  */
 export declare function convertDimension(value: unknown, context: ConverterContext): ConverterResult;
 //# sourceMappingURL=dimension.d.ts.map

package/dist/converters/dimension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dimension.d.ts","sourceRoot":"","sources":["../../src/converters/dimension.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGrE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAoD3F"}
+{"version":3,"file":"dimension.d.ts","sourceRoot":"","sources":["../../src/converters/dimension.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGrE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAoD3F"}

package/dist/converters/duration.d.ts

@@ -12,6 +12,10 @@ import type { ConverterContext, ConverterResult } from '../types.js';
  * // ms values are converted to s
  * convertDuration({ value: 500, unit: "ms" }, context);
  * // => { value: { value: 0.5, unit: "s" } }
+ *
+ * @param value - The DTCG duration value to convert (should match DTCGDurationValue structure)
+ * @param context - Converter context with logger and plugin options
+ * @returns Converted duration in seconds, or skip indicator for unsupported units
  */
 export declare function convertDuration(value: unknown, context: ConverterContext): ConverterResult;
 //# sourceMappingURL=duration.d.ts.map

package/dist/converters/duration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../src/converters/duration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGrE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAoD1F"}
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../src/converters/duration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGrE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAoD1F"}

package/dist/converters/font-family.d.ts

@@ -12,6 +12,10 @@ import type { ConverterContext, ConverterResult } from '../types.js';
  * // Arrays are truncated to the first element
  * convertFontFamily(["Inter", "Helvetica", "sans-serif"], context);
  * // => { value: "Inter" } (with warning about dropped fallbacks)
+ *
+ * @param value - The DTCG fontFamily value (string or string array)
+ * @param context - Converter context with logger and plugin options
+ * @returns Single font family string, or skip indicator for invalid values
  */
 export declare function convertFontFamily(value: unknown, context: ConverterContext): ConverterResult;
 //# sourceMappingURL=font-family.d.ts.map

package/dist/converters/font-family.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"font-family.d.ts","sourceRoot":"","sources":["../../src/converters/font-family.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAqC5F"}
+{"version":3,"file":"font-family.d.ts","sourceRoot":"","sources":["../../src/converters/font-family.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAqC5F"}

package/dist/converters/font-weight.d.ts

@@ -12,6 +12,10 @@ import type { ConverterContext, ConverterResult } from '../types.js';
  * // String aliases pass through if valid
  * convertFontWeight("bold", context);
  * // => { value: "bold" }
+ *
+ * @param value - The DTCG fontWeight value (number 1-1000 or string alias like "bold")
+ * @param context - Converter context with logger and plugin options
+ * @returns Font weight value with outputType set to 'number' or 'string', or skip indicator for invalid values
  */
 export declare function convertFontWeight(value: unknown, context: ConverterContext): ConverterResult;
 //# sourceMappingURL=font-weight.d.ts.map

package/dist/converters/font-weight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"font-weight.d.ts","sourceRoot":"","sources":["../../src/converters/font-weight.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA0BrE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAqC5F"}
+{"version":3,"file":"font-weight.d.ts","sourceRoot":"","sources":["../../src/converters/font-weight.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA0BrE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAqC5F"}

package/dist/converters/gradient.d.ts

@@ -0,0 +1,12 @@
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * Convert a DTCG gradient value to Figma-compatible format.
+ * Gradient tokens are partially split: only stop colors are extracted.
+ * Stop positions are dropped since they can't be represented as Figma variables.
+ *
+ * @param value - The DTCG gradient value (array of gradient stops with color and position)
+ * @param context - Converter context with logger and plugin options
+ * @returns Split result with color sub-tokens for each stop, or skip indicator for invalid values
+ */
+export declare function convertGradient(value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=gradient.d.ts.map

package/dist/converters/gradient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gradient.d.ts","sourceRoot":"","sources":["../../src/converters/gradient.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAY,MAAM,aAAa,CAAC;AAI/E;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAmD1F"}

package/dist/converters/index.d.ts

@@ -7,10 +7,16 @@ import type { ConverterContext, ConverterResult } from '../types.js';
 export type Converter = (value: unknown, context: ConverterContext) => ConverterResult;
 /**
  * Check if a token type is supported by Figma.
+ *
+ * @param type - The DTCG token type string
+ * @returns True if the type is one of the Figma-supported token types
  */
 export declare function isSupportedType(type: string): type is SupportedType;
 /**
  * Check if a value is an alias reference (curly brace syntax).
+ *
+ * @param value - The value to check
+ * @returns True if value is a string wrapped in curly braces (e.g., "{color.primary}")
  */
 export declare function isAlias(value: unknown): value is string;
 /**

package/dist/converters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/converters/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAgC,KAAK,aAAa,EAAqB,MAAM,iBAAiB,CAAC;AACtG,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AASrE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,KAAK,eAAe,CAAC;AAevF;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,aAAa,CAEnE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEvD;AA6CD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAgE/G"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/converters/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAgC,KAAK,aAAa,EAAqB,MAAM,iBAAiB,CAAC;AACtG,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAYrE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,KAAK,eAAe,CAAC;AAkBvF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,aAAa,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEvD;AAiDD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAiD/G"}