@vertekum/ext-export-figma 0.3.15

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @vertekum/ext-export-figma
+
+## 0.3.15
+
+### Patch Changes
+
+- [`b1819c0`](https://github.com/moros-oxus/vertekum/commit/b1819c0f31411bf73a4fe9854b90ee73f8e3e36d) Thanks [@tschemmer](https://github.com/tschemmer)! - New extension: the `figma` exporter resolves a composition into a Figma-shaped model — each resolver set a single-mode collection, each modifier a collection whose contexts are its modes; references as alias edges; typography and shadows as styles with member-variable bindings; every variable carrying both the Figma-typed value and the verbatim DTCG source. Emitted as a versioned `figma.model.json` (JSON Schema shipped), with pluggable dialect writers in target options (`FigmaDialect` — pure model-to-files functions contributed as packages, the terrazzo-plugin pattern). Custom types plug in via `options.types` contributors.
+- Updated dependencies []:
+  - @vertekum/core@0.3.15

package/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright 2026 Thomas Schemmer
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,83 @@
+# @vertekum/ext-export-figma
+
+Exports a resolved token composition as a **Figma-shaped model** — collections,
+modes, variables, aliases, and styles — plus pluggable **dialect writers** that
+reshape the model for specific Figma importers.
+
+## The model is the artifact
+
+The exporter's canonical output, `figma.model.json`, is a versioned document
+(schema shipped as `model.schema.json`) describing one composition in Figma's own
+vocabulary:
+
+- Each resolver **set** becomes a single-mode collection.
+- Each **modifier** becomes a collection whose contexts are its modes, with values
+  resolved per context. The composition *is* the topology — nothing to configure.
+- **References survive as alias edges** (per mode); a reference whose target has no
+  variable is materialized instead — never dropped.
+- **Figma is variables and styles**: typography tokens become text styles, shadows
+  become effect styles, each with resolved per-property values and bindings to
+  member variables where the member was authored as a reference.
+- Every variable carries the **Figma-typed value** (`COLOR` as `{r,g,b,a}` floats,
+  dimensions as unitless px `FLOAT`, `STRING`, `BOOLEAN`) *and* the verbatim DTCG
+  `source` — a consumer of the model loses nothing to any importer's dialect.
+- `scopes` and `codeSyntax` are reserved fields; nothing populates them yet.
+
+## Configuration
+
+```ts
+import { figmaExportExtension } from '@vertekum/ext-export-figma';
+import { microsoftManifest } from '@vertekum/figma-dialect-microsoft';
+
+export default defineConfig({
+  extensions: [figmaExportExtension],
+  targets: [
+    {
+      id: 'figma',
+      exporter: 'figma',
+      composition: 'default',
+      out: 'build/figma',
+      options: {
+        dialects: [microsoftManifest({ modes: 'native' })],
+        types: { /* custom-$type contributors, see below */ },
+      },
+    },
+  ],
+});
+```
+
+| Option | Value space | Meaning |
+| --- | --- | --- |
+| `dialects` | `FigmaDialect[]` | writers run over the model; their files land under `<out>/<dialect-id>/`. The model itself is always emitted. |
+| `types` | `Record<$type, TypeContributor>` | how a custom type becomes variables (below). A `$type` with no mapping is skipped with a notice in `figma.model.json`. |
+
+## Dialects
+
+A dialect is `{ id, write(model): OutputFile[] }` — a pure function from the model
+to one importer's file shape. Ship your own as a package; pass an instance in
+`options.dialects`.
+
+The first dialect ships as its own contribution package —
+`@vertekum/figma-dialect-microsoft` — targeting the `figma-variables-import`
+plugin lineage (sidecar manifest, one DTCG string-dialect file per
+collection-mode, with `native`/`split-collections`/`split-files` mode strategies
+for seats without multi-mode collections). The model never downgrades; a
+dialect's output does.
+
+## Custom types
+
+A contributor maps one mode-value of a token to variable atoms:
+
+```ts
+const spacial: TypeContributor = (value, token) =>
+  (value as Entry[]).map((entry, i) => ({
+    suffix: ['top', 'right', 'bottom', 'left'][i], // extends the token's path
+    type: 'FLOAT',
+    ...(typeof entry === 'string'
+      ? { alias: entry.slice(1, -1) }               // dotted token path
+      : { value: entry.value }),
+  }));
+```
+
+`suffix` unfolds a compound into sibling variables; `alias` becomes a real alias
+edge when the target exists in the model.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@vertekum/ext-export-figma",
+  "version": "0.3.15",
+  "description": "Vertekum extension: export a resolved, Figma-shaped model (collections, modes, variables, styles) with pluggable dialect writers for Figma importers",
+  "license": "Apache-2.0",
+  "keywords": [
+    "design-tokens",
+    "dtcg",
+    "figma",
+    "variables",
+    "export"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moros-oxus/vertekum.git",
+    "directory": "packages/extensions/export-figma"
+  },
+  "homepage": "https://github.com/moros-oxus/vertekum",
+  "bugs": "https://github.com/moros-oxus/vertekum/issues",
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "tsconfig.json",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./api": "./src/api.ts"
+  },
+  "peerDependencies": {
+    "@vertekum/core": "0.3.15"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0",
+    "@vertekum/core": "0.3.15"
+  }
+}

package/src/api.ts

@@ -0,0 +1,15 @@
+import {
+  type ActivateContext,
+  EXPORTER_SERVICE,
+  type ExporterService,
+} from '@vertekum/core';
+import { figmaExporter } from './figma';
+import type { figmaManifest } from './index';
+
+/**
+ * Headless activation: contributes one exporter. The kernel seeds the registry before any
+ * extension activates, so activation order never matters — get and register, nothing more.
+ */
+export function activate(ctx: ActivateContext<typeof figmaManifest>): void {
+  ctx.services.get<ExporterService>(EXPORTER_SERVICE)?.register(figmaExporter);
+}

package/src/dialect.ts

@@ -0,0 +1,20 @@
+import type { FigmaModel } from './model';
+
+/**
+ * The dialect seam: a writer is a pure function from the model to one importer's file shape,
+ * passed in a target's `options.dialects` (the terrazzo pattern — config is the vessel, no
+ * registry). Dialect packages peer on this package for the model types and export a factory
+ * (`somethingDialect(options)`), so third parties contribute importer support as plain npm
+ * packages the same way terrazzo plugins do.
+ */
+
+export interface OutputFile {
+  path: string;
+  content: string;
+}
+
+export interface FigmaDialect {
+  /** Namespaces the writer's files under `<out>/<id>/`. */
+  id: string;
+  write(model: FigmaModel): OutputFile[];
+}

package/src/figma.ts

@@ -0,0 +1,64 @@
+import type { Exporter } from '@vertekum/core';
+import { z } from 'zod';
+import type { FigmaDialect, OutputFile } from './dialect';
+import { buildModel, type TypeContributor } from './model';
+
+/**
+ * The `figma` exporter: builds the Figma-shaped model from the resolved composition and emits it
+ * as the canonical artifact (`figma.model.json` — the `vertekum` dialect, always on), then runs
+ * each configured dialect writer over the model. Writers and type contributors are config-passed
+ * plugs (the terrazzo pattern): no registry, third parties ship them as packages.
+ */
+
+export interface FigmaOptions {
+  /** Per-$type model contributors for custom types (e.g. a per-side unfolder). */
+  types?: Record<string, TypeContributor>;
+  /** Dialect writers; the canonical model is emitted regardless. */
+  dialects?: FigmaDialect[];
+}
+
+const OPTIONS = z
+  .object({
+    types: z
+      .record(z.custom<TypeContributor>((v) => typeof v === 'function'))
+      .optional(),
+    dialects: z
+      .array(
+        z.object({
+          id: z.string(),
+          write: z.custom<FigmaDialect['write']>(
+            (v) => typeof v === 'function',
+          ),
+        }),
+      )
+      .optional(),
+  })
+  .optional();
+
+export const figmaExporter: Exporter = {
+  id: 'figma',
+  name: 'Figma model',
+  optionsSchema: OPTIONS,
+  async transform(input) {
+    const options = (input.options ?? {}) as FigmaOptions;
+    const model = await buildModel(input, {
+      composition: input.resolver.name,
+      types: options.types,
+    });
+    const files: OutputFile[] = [
+      {
+        path: 'figma.model.json',
+        content: `${JSON.stringify(model, null, 2)}\n`,
+      },
+    ];
+    for (const dialect of options.dialects ?? []) {
+      for (const file of dialect.write(model)) {
+        files.push({
+          path: `${dialect.id}/${file.path}`,
+          content: file.content,
+        });
+      }
+    }
+    return files;
+  },
+};

package/src/index.ts

@@ -0,0 +1,33 @@
+import { defineExtension, type ExtensionManifest } from '@vertekum/core';
+import { activate } from './api';
+
+export type { FigmaDialect, OutputFile } from './dialect';
+export { type FigmaOptions, figmaExporter } from './figma';
+export {
+  type BuildModelOptions,
+  buildModel,
+  type FigmaCollection,
+  type FigmaModel,
+  type FigmaStyle,
+  type FigmaType,
+  type FigmaVariable,
+  MODEL_VERSION,
+  type TypeContributor,
+} from './model';
+
+export const figmaManifest = {
+  id: 'vtk.export.figma',
+  name: 'Figma Export',
+  description:
+    "Adds the 'figma' exporter, which resolves a composition into a Figma-shaped model — collections, modes, variables, aliases, styles — emitted as a versioned artifact, plus any configured dialect writers targeting specific Figma importers. A non-view extension: no route, no ribbon entry.",
+  activation: ['onStartup'],
+} satisfies ExtensionManifest;
+
+/**
+ * First-party NON-VIEW HostExtension: contributes an exporter and nothing else. The model artifact
+ * is the contract consumed by dialect writers here and by external tools (a Figma plugin, agents).
+ */
+export const figmaExportExtension = defineExtension<typeof figmaManifest>({
+  manifest: figmaManifest,
+  activate,
+});

package/src/model.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "vertekum:figma-model",
+  "title": "Figma-shaped model",
+  "description": "A resolved view of one composition in Figma's vocabulary: collections with modes, variables with per-mode values and alias edges, and styles. Version 1.",
+  "type": "object",
+  "required": ["version", "source", "collections", "styles"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 1 },
+    "source": {
+      "type": "object",
+      "required": ["generator", "notices"],
+      "additionalProperties": false,
+      "properties": {
+        "composition": { "type": "string" },
+        "generator": { "type": "string" },
+        "notices": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "collections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "modes", "variables"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "modes": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "minItems": 1
+          },
+          "variables": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/variable" }
+          }
+        }
+      }
+    },
+    "styles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "name", "properties", "source"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": { "enum": ["text", "effect"] },
+          "name": { "type": "string", "minLength": 1 },
+          "properties": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["property", "value"],
+              "additionalProperties": false,
+              "properties": {
+                "property": { "type": "string" },
+                "value": {},
+                "variable": { "type": "string" }
+              }
+            }
+          },
+          "source": { "$ref": "#/$defs/source" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "variable": {
+      "type": "object",
+      "required": ["name", "type", "valuesByMode", "scopes", "codeSyntax"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "type": { "enum": ["COLOR", "FLOAT", "STRING", "BOOLEAN"] },
+        "valuesByMode": {
+          "type": "object",
+          "additionalProperties": {
+            "anyOf": [
+              { "type": "number" },
+              { "type": "string" },
+              { "type": "boolean" },
+              {
+                "type": "object",
+                "required": ["r", "g", "b", "a"],
+                "additionalProperties": false,
+                "properties": {
+                  "r": { "type": "number" },
+                  "g": { "type": "number" },
+                  "b": { "type": "number" },
+                  "a": { "type": "number" }
+                }
+              }
+            ]
+          }
+        },
+        "alias": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "source": { "$ref": "#/$defs/source" },
+        "scopes": { "type": "array", "items": { "type": "string" } },
+        "codeSyntax": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "source": {
+      "type": "object",
+      "required": ["$type", "$value"],
+      "additionalProperties": false,
+      "properties": {
+        "$type": { "type": "string" },
+        "$value": {}
+      }
+    }
+  }
+}

package/src/model.ts

@@ -0,0 +1,435 @@
+import { dtcg, type ExporterInput, type Token } from '@vertekum/core';
+
+/**
+ * The Figma-shaped model — the artifact, and the contract.
+ *
+ * A resolved view of one composition in Figma's own vocabulary: collections with modes,
+ * variables with per-mode values and alias edges, and styles (Figma is variables AND styles).
+ * The topology mirrors the resolver: each SET becomes a single-mode collection; each MODIFIER
+ * becomes a collection whose contexts are its modes. The composition IS the topology.
+ *
+ * Every variable carries both the Figma-typed value (`valuesByMode`) and the verbatim DTCG
+ * `source` — dialect writers consume the lossy half; a consumer that understands the model
+ * (a Figma plugin, an agent) gets the lossless half.
+ */
+
+export const MODEL_VERSION = 1;
+
+export type FigmaType = 'COLOR' | 'FLOAT' | 'STRING' | 'BOOLEAN';
+
+export interface FigmaVariable {
+  /** Slash-joined token path — Figma's grouping separator. */
+  name: string;
+  type: FigmaType;
+  /** Figma-typed value per mode: COLOR `{r,g,b,a}` floats, FLOAT unitless px, string, boolean. */
+  valuesByMode: Record<string, unknown>;
+  /** Per-mode alias target (slash name). An alias wins over the value for that mode. */
+  alias?: Record<string, string>;
+  /** The authored DTCG notation, verbatim — the lossless half. */
+  source?: { $type: string; $value: unknown };
+  /** Reserved: nothing populates these yet; the schema keeps their seat. */
+  scopes: string[];
+  codeSyntax: Record<string, string>;
+}
+
+export interface FigmaCollection {
+  name: string;
+  /** Mode names, default first. Single-mode collections have `['default']`. */
+  modes: string[];
+  variables: FigmaVariable[];
+}
+
+export interface FigmaStyleProperty {
+  property: string;
+  /** Resolved value (CSS-ish primitive). */
+  value: unknown;
+  /** Bound member variable (slash name), when the member was authored as a reference. */
+  variable?: string;
+}
+
+export interface FigmaStyle {
+  kind: 'text' | 'effect';
+  name: string;
+  properties: FigmaStyleProperty[];
+  source: { $type: string; $value: unknown };
+}
+
+export interface FigmaModel {
+  version: typeof MODEL_VERSION;
+  source: { composition?: string; generator: string; notices: string[] };
+  collections: FigmaCollection[];
+  styles: FigmaStyle[];
+}
+
+/**
+ * A custom-type model contributor (config-passed via the exporter's `options.types`): maps ONE
+ * mode-value of a token to variable atoms. `suffix` extends the token's path (per-side unfolds);
+ * an atom may carry a concrete `value` or an `alias` (dotted token path).
+ */
+export type TypeContributor = (
+  value: unknown,
+  token: Token,
+) => Array<{
+  suffix?: string;
+  type: FigmaType;
+  value?: unknown;
+  alias?: string;
+}>;
+
+export interface BuildModelOptions {
+  composition?: string;
+  types?: Record<string, TypeContributor>;
+}
+
+const GENERATOR = '@vertekum/ext-export-figma';
+
+/** Types whose per-token handling is built in (beyond these, `options.types` or a notice). */
+const TEXT_TYPES = new Set([
+  'string',
+  'fontFamily',
+  'textCase',
+  'textDecoration',
+  'strokeStyle',
+]);
+
+const slash = (path: string[]): string => path.join('/');
+const dotToSlash = (dotted: string): string => dotted.replaceAll('.', '/');
+
+function isDimension(value: unknown): value is { value: number; unit: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { value?: unknown }).value === 'number' &&
+    typeof (value as { unit?: unknown }).unit === 'string'
+  );
+}
+
+function px(value: { value: number; unit: string }): number {
+  return value.unit === 'rem' || value.unit === 'em'
+    ? value.value * 16
+    : value.value;
+}
+
+async function figmaColor(value: unknown): Promise<unknown> {
+  const srgb = (await dtcg.values.convertColor(value, 'srgb')) as {
+    components?: number[];
+    alpha?: number;
+  };
+  if (!Array.isArray(srgb.components)) return undefined;
+  const [r, g, b] = srgb.components;
+  return { r, g, b, a: srgb.alpha ?? 1 };
+}
+
+/** One token's Figma type + converted value, or undefined when the type is not variable-shaped. */
+async function convert(
+  type: string,
+  value: unknown,
+): Promise<{ type: FigmaType; value: unknown } | undefined> {
+  if (type === 'color') {
+    return { type: 'COLOR', value: await figmaColor(value) };
+  }
+  if (type === 'dimension' && isDimension(value)) {
+    return { type: 'FLOAT', value: px(value) };
+  }
+  if (type === 'duration' && isDimension(value)) {
+    return { type: 'FLOAT', value: value.value };
+  }
+  if (
+    type === 'number' ||
+    (type === 'fontWeight' && typeof value === 'number')
+  ) {
+    return typeof value === 'number'
+      ? { type: 'FLOAT', value }
+      : { type: 'STRING', value: String(value) };
+  }
+  if (type === 'fontWeight') return { type: 'STRING', value: String(value) };
+  if (type === 'fontFamily') {
+    return {
+      type: 'STRING',
+      value: Array.isArray(value) ? String(value[0]) : String(value),
+    };
+  }
+  if (TEXT_TYPES.has(type) && typeof value === 'string') {
+    return { type: 'STRING', value };
+  }
+  if (typeof value === 'boolean') return { type: 'BOOLEAN', value };
+  return undefined;
+}
+
+/** Typography members → text-style properties; shadow layers → effect-style properties. */
+const TYPOGRAPHY_MEMBERS: Record<string, string> = {
+  fontFamily: 'font-family',
+  fontSize: 'font-size',
+  fontWeight: 'font-weight',
+  letterSpacing: 'letter-spacing',
+  lineHeight: 'line-height',
+  textCase: 'text-case',
+  textDecoration: 'text-decoration',
+};
+
+function styleValue(member: unknown): unknown {
+  if (isDimension(member)) return `${member.value}${member.unit}`;
+  if (Array.isArray(member)) return member.map(styleValue).join(', ');
+  return member;
+}
+
+/**
+ * Build the Figma-shaped model from a resolved composition.
+ *
+ * `input.base` is the default selection; `input.variants` are the fully-resolved non-default
+ * contexts. A token belongs to a MODIFIER's collection when its value differs from base in any of
+ * that modifier's contexts (or it exists only there); everything else lands in the collection of
+ * its resolver SET. Values are read per mode from the corresponding resolved bundle.
+ */
+export async function buildModel(
+  input: ExporterInput,
+  options: BuildModelOptions = {},
+): Promise<FigmaModel> {
+  const notices: string[] = [];
+  const model: FigmaModel = {
+    version: MODEL_VERSION,
+    source: { composition: options.composition, generator: GENERATOR, notices },
+    collections: [],
+    styles: [],
+  };
+
+  const basePaths = new Map(input.base.map((t) => [t.path.join('.'), t]));
+
+  // Modifier axes: context order as declared, default first; per-context resolved bundles.
+  const axes = Object.entries(input.resolver.modifiers).map(
+    ([modifier, mod]) => {
+      const contexts = Object.keys(mod.contexts);
+      const defaultContext = mod.default ?? contexts[0] ?? 'default';
+      const ordered = [
+        defaultContext,
+        ...contexts.filter((c) => c !== defaultContext),
+      ];
+      const bundles = new Map<string, Map<string, Token>>();
+      bundles.set(defaultContext, basePaths);
+      for (const variant of input.variants) {
+        if (variant.modifier !== modifier) continue;
+        bundles.set(
+          variant.context,
+          new Map(variant.tokens.map((t) => [t.path.join('.'), t])),
+        );
+      }
+      return { modifier, contexts: ordered, bundles };
+    },
+  );
+
+  // A token is claimed by the FIRST modifier (declaration order) under which it varies.
+  const claimed = new Map<string, string>();
+  for (const axis of axes) {
+    for (const [context, bundle] of axis.bundles) {
+      if (context === axis.contexts[0]) continue;
+      for (const [path, token] of bundle) {
+        const base = basePaths.get(path);
+        const varies =
+          !base || JSON.stringify(base.value) !== JSON.stringify(token.value);
+        if (!varies) continue;
+        const holder = claimed.get(path);
+        if (holder === undefined) claimed.set(path, axis.modifier);
+        else if (holder !== axis.modifier) {
+          notices.push(
+            `'${path}' varies under both '${holder}' and '${axis.modifier}' — modelled under '${holder}'`,
+          );
+        }
+      }
+    }
+  }
+
+  // First pass — every variable NAME that will exist, so alias edges can check their targets.
+  const variableNames = new Set<string>();
+  const atomsOf = async (
+    token: Token,
+    value: unknown,
+  ): Promise<
+    | Array<{
+        suffix?: string;
+        type: FigmaType;
+        value?: unknown;
+        alias?: string;
+      }>
+    | undefined
+  > => {
+    const contributor = options.types?.[token.type];
+    if (contributor) return contributor(value, token);
+    const converted = await convert(token.type, value);
+    return converted
+      ? [{ type: converted.type, value: converted.value }]
+      : undefined;
+  };
+  const nameOf = (token: Token, suffix?: string): string =>
+    suffix ? `${slash(token.path)}/${suffix}` : slash(token.path);
+
+  const allTokens = new Map<string, Token>(basePaths);
+  for (const variant of input.variants) {
+    for (const token of variant.tokens) {
+      const path = token.path.join('.');
+      if (!allTokens.has(path)) allTokens.set(path, token);
+    }
+  }
+  for (const token of allTokens.values()) {
+    if (token.type === 'typography' || token.type === 'shadow') continue;
+    const atoms = await atomsOf(token, token.value);
+    if (!atoms) continue;
+    for (const atom of atoms) variableNames.add(nameOf(token, atom.suffix));
+  }
+
+  // Variable construction for one token across a mode set.
+  const buildVariables = async (
+    token: Token,
+    modes: Array<{ mode: string; bundle: Map<string, Token> }>,
+  ): Promise<FigmaVariable[] | 'style' | undefined> => {
+    if (token.type === 'typography' || token.type === 'shadow') {
+      buildStyle(token);
+      return 'style';
+    }
+    const byName = new Map<string, FigmaVariable>();
+    for (const { mode, bundle } of modes) {
+      const held = bundle.get(token.path.join('.')) ?? token;
+      const raw = held.value;
+      // A whole-value curly reference: alias when the target is a variable, else materialize.
+      let aliasTarget: string | undefined;
+      let value = raw;
+      if (dtcg.tokens.isReference(raw)) {
+        const target = dotToSlash(dtcg.tokens.referenceToPath(raw));
+        if (variableNames.has(target)) aliasTarget = target;
+        value = dtcg.tokens.resolveValue(
+          held,
+          dtcg.tokens.indexByPath([...bundle.values()]),
+        );
+      }
+      const atoms = await atomsOf(held, value);
+      if (!atoms) {
+        if (mode === modes[0]?.mode) return undefined;
+        continue;
+      }
+      for (const atom of atoms) {
+        const name = nameOf(token, atom.suffix);
+        let variable = byName.get(name);
+        if (!variable) {
+          variable = {
+            name,
+            type: atom.type,
+            valuesByMode: {},
+            source: { $type: token.type, $value: token.value },
+            scopes: [],
+            codeSyntax: {},
+          };
+          byName.set(name, variable);
+        }
+        if (atom.value !== undefined) variable.valuesByMode[mode] = atom.value;
+        const atomAlias =
+          atom.alias !== undefined ? dotToSlash(atom.alias) : aliasTarget;
+        if (atomAlias !== undefined && variableNames.has(atomAlias)) {
+          variable.alias = { ...variable.alias, [mode]: atomAlias };
+        }
+      }
+    }
+    return [...byName.values()];
+  };
+
+  const buildStyle = (token: Token): void => {
+    const value = token.value;
+    if (token.type === 'typography' && value && typeof value === 'object') {
+      const raw = (token.sourceValue ?? value) as Record<string, unknown>;
+      const resolved = value as Record<string, unknown>;
+      const properties: FigmaStyleProperty[] = [];
+      for (const [member, property] of Object.entries(TYPOGRAPHY_MEMBERS)) {
+        if (!(member in resolved)) continue;
+        const authored = raw[member];
+        properties.push({
+          property,
+          value: styleValue(resolved[member]),
+          ...(dtcg.tokens.isReference(authored)
+            ? { variable: dotToSlash(dtcg.tokens.referenceToPath(authored)) }
+            : {}),
+        });
+      }
+      model.styles.push({
+        kind: 'text',
+        name: slash(token.path),
+        properties,
+        source: { $type: token.type, $value: token.value },
+      });
+      return;
+    }
+    if (token.type === 'shadow') {
+      const layers = Array.isArray(value) ? value : [value];
+      const properties: FigmaStyleProperty[] = layers.flatMap((layer, index) =>
+        layer && typeof layer === 'object'
+          ? Object.entries(layer as Record<string, unknown>).map(
+              ([member, held]) => ({
+                property: layers.length > 1 ? `${index}/${member}` : member,
+                value: styleValue(held),
+              }),
+            )
+          : [],
+      );
+      model.styles.push({
+        kind: 'effect',
+        name: slash(token.path),
+        properties,
+        source: { $type: token.type, $value: token.value },
+      });
+    }
+  };
+
+  // Set collections: resolver sets in order; tokens by source file, minus modifier-claimed ones.
+  const skipped = new Set<string>();
+  for (const [setName, set] of Object.entries(input.resolver.sets)) {
+    const files = new Set(
+      (set.sources ?? []).map((source) =>
+        String((source as { $ref?: string }).$ref ?? '').replace(/\.json$/, ''),
+      ),
+    );
+    const variables: FigmaVariable[] = [];
+    for (const token of input.base) {
+      const path = token.path.join('.');
+      if (claimed.has(path)) continue;
+      if (!files.has(token.set ?? '')) continue;
+      const built = await buildVariables(token, [
+        { mode: 'default', bundle: basePaths },
+      ]);
+      if (built === undefined) {
+        skipped.add(token.type);
+        continue;
+      }
+      if (built !== 'style') variables.push(...built);
+    }
+    model.collections.push({ name: setName, modes: ['default'], variables });
+  }
+
+  // Modifier collections: contexts as modes, values per resolved bundle.
+  for (const axis of axes) {
+    const modes = axis.contexts.map((context) => ({
+      mode: context,
+      bundle: axis.bundles.get(context) ?? basePaths,
+    }));
+    const variables: FigmaVariable[] = [];
+    for (const [path, modifier] of claimed) {
+      if (modifier !== axis.modifier) continue;
+      const token = allTokens.get(path);
+      if (!token) continue;
+      const built = await buildVariables(token, modes);
+      if (built === undefined) {
+        skipped.add(token.type);
+        continue;
+      }
+      if (built !== 'style') variables.push(...built);
+    }
+    model.collections.push({
+      name: axis.modifier,
+      modes: axis.contexts,
+      variables,
+    });
+  }
+
+  for (const type of skipped) {
+    notices.push(
+      `tokens of type '${type}' have no Figma mapping — provide one via options.types`,
+    );
+  }
+  return model;
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}