terrazzo-plugin-figma-json 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dgtlntv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# terrazzo-plugin-figma-json
+
+A [Terrazzo](https://terrazzo.app) plugin that converts W3C DTCG design tokens into Figma-compatible JSON format for import into Figma Variables.
+
+## Installation
+
+```bash
+npm install terrazzo-plugin-figma-json
+# or
+pnpm add terrazzo-plugin-figma-json
+```
+
+## Basic Usage
+
+Add the plugin to your `terrazzo.config.ts`:
+
+```typescript
+import { defineConfig } from "@terrazzo/cli";
+import figmaJson from "terrazzo-plugin-figma-json";
+
+export default defineConfig({
+  outDir: "./tokens/",
+  plugins: [
+    figmaJson({
+      filename: "tokens.figma.json",
+    }),
+  ],
+});
+```
+
+Run the Terrazzo build:
+
+```bash
+npx tz build
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `filename` | `string` | `"tokens.figma.json"` | Output filename (used as suffix when using resolver) |
+| `exclude` | `string[]` | `[]` | Glob patterns to exclude tokens from output |
+| `transform` | `(token) => unknown` | `undefined` | Custom transform function to override token values |
+| `tokenName` | `(token) => string` | `undefined` | Custom function to control token names in output |
+| `skipBuild` | `boolean` | `false` | Skip generating the output file |
+| `remBasePx` | `number` | `16` | Base pixel value for rem to px conversion |
+| `warnOnUnsupported` | `boolean` | `true` | Log warnings for unsupported token types |
+| `preserveReferences` | `boolean` | `true` | Preserve token aliases in output (see [Alias Handling](#alias-handling)) |
+
+## Output Structure
+
+When using a resolver file (recommended), the plugin automatically splits output by resolver sets and modifier contexts:
+
+```
+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
+```
+
+Without a resolver, all tokens are output to a single file.
+
+## Supported Token Types
+
+| DTCG Type | Figma Variable Type | Transformation |
+|-----------|---------------------|----------------|
+| `color` | Color | sRGB and HSL pass through; other color spaces converted to sRGB |
+| `dimension` | Number | `px` values pass through; `rem` converted to `px` |
+| `duration` | Number | `s` values pass through; `ms` converted to `s` |
+| `fontFamily` | String | Strings pass through; arrays truncated to first element |
+| `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 |
+
+### Typography Token Splitting
+
+Figma doesn't support composite typography tokens, so they're automatically split into individual sub-tokens:
+
+**Input:**
+```json
+{
+  "typography": {
+    "$type": "typography",
+    "heading": {
+      "$value": {
+        "fontFamily": "Inter",
+        "fontSize": { "value": 24, "unit": "px" },
+        "fontWeight": 700,
+        "lineHeight": 1.2,
+        "letterSpacing": { "value": 0, "unit": "px" }
+      }
+    }
+  }
+}
+```
+
+**Output:**
+```json
+{
+  "typography": {
+    "heading": {
+      "fontFamily": { "$type": "fontFamily", "$value": "Inter" },
+      "fontSize": { "$type": "dimension", "$value": { "value": 24, "unit": "px" } },
+      "fontWeight": { "$type": "fontWeight", "$value": 700 },
+      "lineHeight": { "$type": "dimension", "$value": { "value": 29, "unit": "px" } },
+      "letterSpacing": { "$type": "dimension", "$value": { "value": 0, "unit": "px" } }
+    }
+  }
+}
+```
+
+Note: `lineHeight` is converted from a unitless multiplier to absolute px (see [Figma Limitations](#figma-limitations)).
+
+## Unsupported Token Types
+
+The following DTCG token types are **not supported** by Figma and will be skipped:
+
+- `shadow`, `border`, `gradient`, `transition`, `strokeStyle`, `cubicBezier`
+
+## Alias Handling
+
+When `preserveReferences: true` (default):
+
+- **Same-file references**: Use curly brace syntax in `$value` (e.g., `"{color.primary}"`)
+- **Cross-file references**: Use resolved `$value` + `com.figma.aliasData` extension
+
+```json
+{
+  "color": {
+    "brand": {
+      "$type": "color",
+      "$value": "{color.palette.blue.500}"
+    }
+  }
+}
+```
+
+For cross-collection aliases (referencing tokens in a different output file):
+
+```json
+{
+  "color": {
+    "text": {
+      "$type": "color",
+      "$value": { "colorSpace": "srgb", "components": [0.2, 0.4, 0.8], "alpha": 1 },
+      "$extensions": {
+        "com.figma.aliasData": {
+          "targetVariableSetName": "primitive",
+          "targetVariableName": "color/palette/blue/500"
+        }
+      }
+    }
+  }
+}
+```
+
+## Color Space Conversion
+
+Figma only supports **sRGB** and **HSL** color spaces. Other color spaces are converted to sRGB:
+
+- Display P3, Rec2020, A98 RGB, ProPhoto RGB → sRGB
+- OKLCH, OkLab, Lab, LCH → sRGB
+- XYZ-D65, XYZ-D50, HWB, sRGB-linear → sRGB
+
+Colors outside the sRGB gamut will be clipped with a warning.
+
+## Boolean Tokens
+
+Use the `number` type with the `com.figma.type` extension:
+
+```json
+{
+  "feature-flags": {
+    "$type": "number",
+    "dark-mode-enabled": {
+      "$value": 1,
+      "$extensions": { "com.figma.type": "boolean" }
+    }
+  }
+}
+```
+
+- `0` → `false`
+- Non-zero → `true`
+
+## Examples
+
+### Excluding Tokens
+
+```typescript
+figmaJson({
+  exclude: [
+    "internal.*",      // Exclude "internal" group
+    "*.deprecated.*",  // Exclude "deprecated" tokens
+  ],
+})
+```
+
+### Custom Token Names
+
+```typescript
+figmaJson({
+  tokenName: (token) => token.id.replace("color.", "brand.color."),
+})
+```
+
+### Custom Transform
+
+```typescript
+figmaJson({
+  transform: (token) => {
+    if (token.id === "color.special") {
+      return { colorSpace: "srgb", components: [1, 0, 0], alpha: 1 };
+    }
+    return undefined; // Use default transformation
+  },
+})
+```
+
+## Figma Limitations
+
+Figma Variables have constraints that differ from the W3C DTCG specification. This plugin handles these automatically, but be aware of the following:
+
+### lineHeight Conversion
+
+W3C DTCG specifies `lineHeight` as a unitless number (multiplier relative to fontSize, e.g., `1.5`). Figma requires `lineHeight` to be a dimension with px units.
+
+The plugin converts by multiplying: `lineHeight × fontSize`. For example, `lineHeight: 1.5` with `fontSize: 16px` becomes `24px`.
+
+**Trade-off**: Any reference to a primitive number token for lineHeight is lost, since the computed px value cannot maintain an alias to the original multiplier.
+
+### $root Token Naming
+
+The DTCG spec uses `$root` for default mode values. Figma doesn't allow `$` in variable names, so the plugin converts `$root` to `root` in the output.
+
+### Cross-File Alias Resolution
+
+When a token uses a JSON pointer (`$ref`) that points to another token using curly-brace alias syntax, the intermediate reference is lost. For example:
+
+```json
+{
+  "a": { "$value": { "x": "{b.x}" } },
+  "c": { "$ref": "#/a/$value/x" }
+}
+```
+
+Token `c` will resolve to `b.x`, not `a.x`. This is a limitation of how the Terrazzo parser resolves references.
+
+## License
+
+MIT

package/dist/build.d.ts

@@ -0,0 +1,18 @@
+import type { BuildHookOptions, Resolver } from '@terrazzo/parser';
+import type { FigmaJsonPluginOptions } from './types.js';
+export interface BuildOptions {
+    exclude: FigmaJsonPluginOptions['exclude'];
+    tokenName?: FigmaJsonPluginOptions['tokenName'];
+    getTransforms: BuildHookOptions['getTransforms'];
+    preserveReferences?: FigmaJsonPluginOptions['preserveReferences'];
+    resolver?: Resolver;
+}
+/**
+ * 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" -> "{...}")
+ */
+export default function buildFigmaJson({ getTransforms, exclude, tokenName, preserveReferences, resolver, }: BuildOptions): Map<string, string>;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AASzD,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,CAAC,EAAE,QAAQ,CAAC;CACrB;AAsSD;;;;;;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,CAqOpC"}

package/dist/constants.d.ts

@@ -0,0 +1,30 @@
+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 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 type UnsupportedType = (typeof UNSUPPORTED_TYPES)[number];
+/**
+ * Color spaces that Figma natively supports.
+ */
+export declare const FIGMA_COLOR_SPACES: readonly ["srgb", "hsl"];
+export type FigmaColorSpace = (typeof FIGMA_COLOR_SPACES)[number];
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +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"}

package/dist/converters/color.d.ts

@@ -0,0 +1,24 @@
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * 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 } }
+ */
+export declare function convertColor(value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=color.d.ts.map

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

@@ -0,0 +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"}

package/dist/converters/dimension.d.ts

@@ -0,0 +1,17 @@
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * 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" } }
+ */
+export declare function convertDimension(value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=dimension.d.ts.map

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

@@ -0,0 +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"}

package/dist/converters/duration.d.ts

@@ -0,0 +1,17 @@
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * 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" } }
+ */
+export declare function convertDuration(value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=duration.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,17 @@
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * 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)
+ */
+export declare function convertFontFamily(value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=font-family.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,17 @@
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * 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" }
+ */
+export declare function convertFontWeight(value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=font-weight.d.ts.map

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

@@ -0,0 +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"}

package/dist/converters/index.d.ts

@@ -0,0 +1,25 @@
+import type { TokenNormalized } from '@terrazzo/parser';
+import { type SupportedType } from '../constants.js';
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * Converter function signature.
+ */
+export type Converter = (value: unknown, context: ConverterContext) => ConverterResult;
+/**
+ * Check if a token type is supported by Figma.
+ */
+export declare function isSupportedType(type: string): type is SupportedType;
+/**
+ * Check if a value is an alias reference (curly brace syntax).
+ */
+export declare function isAlias(value: unknown): value is string;
+/**
+ * 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
+ */
+export declare function convertToken(token: TokenNormalized, value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/converters/line-height.d.ts

@@ -0,0 +1,55 @@
+import type { ConverterContext, ConverterResult, DTCGDimensionValue } from '../types.js';
+/**
+ * Context for lineHeight conversion, extending the base converter context
+ * with the fontSize value needed for calculating absolute lineHeight.
+ */
+export interface LineHeightConverterContext extends ConverterContext {
+    /**
+     * The resolved fontSize dimension value from the typography token.
+     * Required to calculate absolute lineHeight from the multiplier.
+     * Should already be converted to px units.
+     */
+    fontSize?: DTCGDimensionValue;
+}
+/**
+ * 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" } }
+ */
+export declare function convertLineHeight(value: unknown, context: LineHeightConverterContext): ConverterResult;
+//# sourceMappingURL=line-height.d.ts.map

package/dist/converters/line-height.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-height.d.ts","sourceRoot":"","sources":["../../src/converters/line-height.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEzF;;;GAGG;AACH,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAClE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,0BAA0B,GAAG,eAAe,CAoDtG"}

package/dist/converters/number.d.ts

@@ -0,0 +1,17 @@
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * 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 }
+ */
+export declare function convertNumber(value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=number.d.ts.map

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

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

package/dist/converters/typography.d.ts

@@ -0,0 +1,19 @@
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * 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: [...] }
+ */
+export declare function convertTypography(value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=typography.d.ts.map

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

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

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type { Plugin } from '@terrazzo/parser';
+import type { FigmaJsonPluginOptions } from './types.js';
+export * from './build.js';
+export * from './constants.js';
+export * from './transform.js';
+export * from './types.js';
+export * from './utils.js';
+/**
+ * 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
+ *   },
+ * });
+ *
+ */
+export default function figmaJsonPlugin(options?: FigmaJsonPluginOptions): Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAI/C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CA4ChF"}