terrazzo-plugin-figma-json 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,14 @@
 # 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.
+A [Terrazzo](https://terrazzo.app) plugin that converts W3C DTCG design tokens into Figma-compatible JSON format for [import into Figma Variables](https://help.figma.com/hc/en-us/articles/15343816063383-Modes-for-variables#h_01KAGYPSFC984XDB4YWBCNRZJ7).
+
+## Requirements
+
+This plugin requires Terrazzo 2.0.0-beta.0 or later:
+
+```bash
+npm install @terrazzo/cli@2.0.0-beta.0 @terrazzo/parser@2.0.0-beta.0
+```
 
 ## Installation
 
@@ -49,7 +57,7 @@ npx tz build
 
 ## Output Structure
 
-When using a resolver file (recommended), the plugin automatically splits output by resolver sets and modifier contexts:
+With a resolver file, the plugin splits output by resolver sets and modifier contexts:
 
 ```
 dist/
@@ -60,7 +68,7 @@ dist/
 └── breakpoint-small.figma.json
 ```
 
-Without a resolver, all tokens are output to a single file.
+Without a resolver, all tokens are output to a single file (`tokens.figma.json` by default).
 
 ## Supported Token Types
 
@@ -73,6 +81,9 @@ Without a resolver, all tokens are output to a single file.
 | `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
 
@@ -113,11 +124,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
 
@@ -158,13 +271,7 @@ For cross-collection aliases (referencing tokens in a different output file):
 
 ## 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.
+Figma only supports sRGB and HSL color spaces. All other color spaces defined in the DTCG spec are converted to sRGB. Colors outside the sRGB gamut are clipped with a warning.
 
 ## Boolean Tokens
 
@@ -250,4 +357,4 @@ Token `c` will resolve to `b.x`, not `a.x`. This is a limitation of how the Terr
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/dist/build.d.ts.map

@@ -1 +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"}
+{"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,CA6OpC"}

package/dist/constants.d.ts

@@ -15,12 +15,12 @@ export declare const INTERNAL_KEYS: {
 /**
  * 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;;;GAGG;AACH,eAAO,MAAM,aAAa;IACxB,2CAA2C;;IAE3C,8DAA8D;;IAE9D,oCAAoC;;CAE5B,CAAC;AAEX;;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,8 @@
+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.
+ */
+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;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAqExF"}

package/dist/converters/gradient.d.ts

@@ -0,0 +1,8 @@
+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.
+ */
+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;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CA2D1F"}

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;;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/shadow.d.ts

@@ -0,0 +1,11 @@
+import type { ConverterContext, ConverterResult } from '../types.js';
+/**
+ * Convert a DTCG shadow value to Figma-compatible format.
+ * Shadow tokens are split into individual sub-tokens since Figma
+ * doesn't support the composite shadow type.
+ *
+ * Single shadows produce: color, offsetX, offsetY, blur, spread
+ * Multiple shadow layers produce indexed sub-tokens: 0.color, 0.offsetX, ..., 1.color, etc.
+ */
+export declare function convertShadow(value: unknown, context: ConverterContext): ConverterResult;
+//# sourceMappingURL=shadow.d.ts.map

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

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

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

@@ -1 +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"}
+{"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;AAO/E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAiI5F"}