@vertekum/ext-export-figma 0.3.15 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @vertekum/ext-export-figma
 
+## 0.5.0
+
+### Patch Changes
+
+- Updated dependencies [[`739344f`](https://github.com/moros-oxus/vertekum/commit/739344ffe4d80a9af1a6d503f2763714be62e8b8)]:
+  - @vertekum/core@0.5.0
+
+## 0.4.0
+
+### Minor Changes
+
+- [`2930833`](https://github.com/moros-oxus/vertekum/commit/29308335dafc9d2951722cba37b2c5bf264168ff) Thanks [@tschemmer](https://github.com/tschemmer)! - `figma.model.json` now carries a string contract version (`"version": "draft.01"`) instead of the integer `1`; readers pinned to `1` must accept `draft.01`.
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @vertekum/core@0.4.0
+
 ## 0.3.15
 
 ### Patch Changes

package/README.md

@@ -23,6 +23,16 @@ vocabulary:
   `source` — a consumer of the model loses nothing to any importer's dialect.
 - `scopes` and `codeSyntax` are reserved fields; nothing populates them yet.
 
+### Versioning
+
+The model's `version` names its **contract** — the shape `model.schema.json`
+accepts — not a package release and not the tokens it holds. While the shape is
+still settling, the version is a draft (`draft.01`, `draft.02`, …); once the shape
+is declared stable, it takes a calendar version (`YYYY.MM`). The schema is closed,
+so any change to the shape — an added optional field included — takes a new
+version, and many package releases can share one. Readers should refuse a version
+they don't know rather than guess at its shape.
+
 ## Configuration
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertekum/ext-export-figma",
-  "version": "0.3.15",
+  "version": "0.5.0",
   "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": [
@@ -35,13 +35,13 @@
     "./api": "./src/api.ts"
   },
   "peerDependencies": {
-    "@vertekum/core": "0.3.15"
+    "@vertekum/core": "0.5.0"
   },
   "dependencies": {
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "ajv": "^8.20.0",
-    "@vertekum/core": "0.3.15"
+    "@vertekum/core": "0.5.0"
   }
 }

package/src/model.schema.json

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "vertekum:figma-model",
+  "$id": "vertekum:figma-model/draft.01",
   "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.",
+  "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 draft.01 — the version names this contract shape, not the tokens a document holds.",
   "type": "object",
   "required": ["version", "source", "collections", "styles"],
   "additionalProperties": false,
   "properties": {
-    "version": { "const": 1 },
+    "version": { "const": "draft.01" },
     "source": {
       "type": "object",
       "required": ["generator", "notices"],

package/src/model.ts

@@ -13,7 +13,13 @@ import { dtcg, type ExporterInput, type Token } from '@vertekum/core';
  * (a Figma plugin, an agent) gets the lossless half.
  */
 
-export const MODEL_VERSION = 1;
+/**
+ * The contract version: names the model's SHAPE (what `model.schema.json` accepts), not a package
+ * release or token content. `draft.NN` while the shape is unstable; `YYYY.MM` once declared stable.
+ * The schema is closed, so ANY shape change — an added optional field included — takes a new
+ * version, spent when a package releases it.
+ */
+export const MODEL_VERSION = 'draft.01';
 
 export type FigmaType = 'COLOR' | 'FLOAT' | 'STRING' | 'BOOLEAN';