@hirobius/design-system 0.8.1

package/protocol/figma-snapshot.schema.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "figma-snapshot.schema.json",
+  "title": "FigmaSnapshot",
+  "description": "10f-1: Read-only normalized snapshot of a Figma document. Same field shapes as the p6-1 selection serializer, extended to cover the full document: all pages, variable collections/modes, all local components/styles.",
+  "type": "object",
+  "required": ["snapshotAt", "pages", "variables", "styles"],
+  "additionalProperties": false,
+  "properties": {
+    "snapshotAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp (UTC) when the snapshot was taken by the plugin."
+    },
+    "documentName": {
+      "type": "string",
+      "description": "Figma document name (figma.root.name)."
+    },
+    "pages": {
+      "type": "array",
+      "description": "One entry per page in the document.",
+      "items": { "$ref": "#/definitions/PageSummary" }
+    },
+    "variables": {
+      "type": "object",
+      "description": "Variable collections keyed by HDS collection name (HDS Primitive | HDS Semantic | HDS Component). Non-HDS collections are omitted.",
+      "additionalProperties": { "$ref": "#/definitions/VariableCollection" }
+    },
+    "styles": {
+      "type": "object",
+      "description": "Local Figma styles grouped by kind.",
+      "required": ["paint", "text", "effect", "grid"],
+      "additionalProperties": false,
+      "properties": {
+        "paint":  { "type": "array", "items": { "$ref": "#/definitions/StyleSummary" } },
+        "text":   { "type": "array", "items": { "$ref": "#/definitions/StyleSummary" } },
+        "effect": { "type": "array", "items": { "$ref": "#/definitions/StyleSummary" } },
+        "grid":   { "type": "array", "items": { "$ref": "#/definitions/StyleSummary" } }
+      }
+    },
+    "components": {
+      "type": "array",
+      "description": "All local COMPONENT and COMPONENT_SET nodes in the document (flattened list, not scoped per-page).",
+      "items": { "$ref": "#/definitions/ComponentSummary" }
+    }
+  },
+  "definitions": {
+    "PageSummary": {
+      "type": "object",
+      "required": ["id", "name", "type"],
+      "additionalProperties": false,
+      "properties": {
+        "id":    { "type": "string" },
+        "name":  { "type": "string" },
+        "type":  { "type": "string", "const": "PAGE" },
+        "frames": {
+          "type": "array",
+          "description": "Top-level FRAME and COMPONENT_SET children of this page, serialized with the p6-1 extractNodeTree shape (max depth 4).",
+          "items": { "$ref": "#/definitions/SerializedNode" }
+        }
+      }
+    },
+    "VariableCollection": {
+      "type": "object",
+      "required": ["id", "name", "modes", "variables"],
+      "additionalProperties": false,
+      "properties": {
+        "id":   { "type": "string" },
+        "name": { "type": "string" },
+        "modes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["modeId", "name"],
+            "additionalProperties": false,
+            "properties": {
+              "modeId": { "type": "string" },
+              "name":   { "type": "string" }
+            }
+          }
+        },
+        "variables": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/VariableSummary" }
+        }
+      }
+    },
+    "VariableSummary": {
+      "type": "object",
+      "required": ["id", "name", "resolvedType", "tokenPath"],
+      "additionalProperties": false,
+      "properties": {
+        "id":           { "type": "string" },
+        "name":         { "type": "string", "description": "Raw Figma variable name (slash/dash separated)." },
+        "tokenPath":    { "type": "string", "description": "Dot-notation canonical path, e.g. 'semantic.color.surface.raised'." },
+        "resolvedType": { "type": "string", "enum": ["COLOR", "FLOAT", "STRING", "BOOLEAN"] },
+        "valuesByMode": {
+          "type": "object",
+          "description": "Map of modeId → resolved value. COLOR values are serialized as hex strings (#rrggbb or #rrggbbaa). FLOAT/STRING/BOOLEAN are primitives.",
+          "additionalProperties": {}
+        },
+        "scopes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Figma scopes (e.g. FILL_COLOR, CORNER_RADIUS). Omitted when empty."
+        }
+      }
+    },
+    "StyleSummary": {
+      "type": "object",
+      "required": ["id", "name", "type"],
+      "additionalProperties": false,
+      "properties": {
+        "id":          { "type": "string" },
+        "name":        { "type": "string" },
+        "type":        { "type": "string" },
+        "description": { "type": "string" }
+      }
+    },
+    "ComponentSummary": {
+      "type": "object",
+      "required": ["id", "name", "type"],
+      "additionalProperties": false,
+      "properties": {
+        "id":           { "type": "string" },
+        "name":         { "type": "string" },
+        "type":         { "type": "string", "enum": ["COMPONENT", "COMPONENT_SET"] },
+        "componentName": {
+          "type": "string",
+          "description": "Resolved manifest spec key (from p6-1 resolveComponentName), if matched."
+        },
+        "variants": {
+          "type": "array",
+          "description": "Variant names for COMPONENT_SET nodes.",
+          "items": { "type": "string" }
+        },
+        "properties": {
+          "type": "object",
+          "description": "Component property descriptors (Figma ComponentPropertyDefinitions).",
+          "additionalProperties": {}
+        },
+        "pageId": { "type": "string", "description": "ID of the page that owns this component." },
+        "a11y": { "$ref": "#/definitions/A11yMeta" }
+      }
+    },
+    "SerializedNode": {
+      "description": "p6-1 extractNodeTree shape, extended with slot bindings. Mirrors the selection serializer output exactly so downstream validators receive the same contract whether the input came from a selection or a full-page walk.",
+      "type": "object",
+      "required": ["id", "name", "type"],
+      "additionalProperties": true,
+      "properties": {
+        "id":            { "type": "string" },
+        "name":          { "type": "string" },
+        "type":          { "type": "string" },
+        "width":         { "type": "number" },
+        "height":        { "type": "number" },
+        "x":             { "type": "number" },
+        "y":             { "type": "number" },
+        "fills":         {},
+        "boundVariables": {},
+        "componentName": { "type": "string" },
+        "tokenPaths":    { "type": "object", "additionalProperties": {} },
+        "a11y":          { "$ref": "#/definitions/A11yMeta" },
+        "slotBindings":  { "$ref": "#/definitions/SlotBindings" },
+        "children":      {
+          "type": "array",
+          "items": { "$ref": "#/definitions/SerializedNode" }
+        }
+      }
+    },
+    "A11yMeta": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name":        { "type": "string" },
+        "role":        { "type": "string" },
+        "description": { "type": "string" }
+      }
+    },
+    "SlotBindings": {
+      "type": "object",
+      "description": "Asset/portfolio slot assignments stored as plugin data on the node (hdsSlot key).",
+      "additionalProperties": false,
+      "properties": {
+        "slot":    { "type": "string", "description": "Slot identifier, e.g. 'hero-01'." },
+        "assetId": { "type": "string" }
+      }
+    }
+  }
+}