docs(adapters): expand Figma export guidance

Author: marklearst

docs/examples/figma-export.json assets/schema/figma-export.jsondocs/examples/figma-export.json renamed to assets/schema/figma-export.json

@@ -4,11 +4,20 @@ title: Figma Adapter
 
 # Figma Adapter
 
-Figma Variables exports include tool-specific metadata and reference syntax. This adapter normalizes Figma exports into Variable Contract format.
+Figma Variables exports include tool-specific metadata and reference syntax. This adapter normalizes Figma exports into Variable Design Standard (VDS) format.
 
-## Input format
+## Supported export formats
 
-Figma exports include:
+This adapter handles two export formats:
+
+1. **Plugin export format**: Generated by Figma plugins (available on all plans). Uses `@` collection prefixes, `$` group prefixes, and `$variable_metadata`.
+2. **REST API format**: From the [Local Variables endpoint](https://developers.figma.com/docs/rest-api/variables-endpoints/) (**Enterprise plan only**). Uses `valuesByMode` with internal IDs.
+
+The normalization steps below focus on the plugin export format, which is more commonly used.
+
+## Plugin export input format
+
+Plugin exports include:
 
 - `$collection_metadata` at collection level
 - `$variable_metadata` on each variable
@@ -82,11 +91,13 @@ After:
 
 ### Step 2: Normalize collection names
 
-Remove `@` prefix from collection names. Figma uses `@collection` but Variable Contract uses `collection`.
+Remove `@` prefix from collection names. The `@` prefix is added by the export plugin to distinguish collections from groups. In Figma UI, you name the collection "Primitives" (without `@`).
+
+Before: `"@primitives"` (from export)
 
-Before: `"@primitives"`
+After: `"primitives"` (normalized)
 
-After: `"primitives"`
+Similarly, group names have `$` prefixes in exports (e.g., `$color`, `$green`). These are added by the plugin because Figma uses `/` as path separators in variable names (e.g., `color/green/200`), and the export converts these to nested JSON objects with `$` prefixes to avoid conflicts with DTCG reserved properties like `$type` and `$value`.
 
 ### Step 3: Extract variable metadata
 
@@ -134,7 +145,7 @@ Convert Figma reference syntax to canonical format.
 
 Figma uses: `{@collection.token}`
 
-Variable Contract uses: `{collection.token}`
+Variable Design Standard (VDS) uses: `{collection.token}`
 
 Before:
 
@@ -212,7 +223,7 @@ After:
 
 ### Step 6: Validate naming
 
-Check that normalized names follow Variable Contract naming convention (see [Naming](/contract/naming)).
+Check that normalized names follow Variable Design Standard (VDS) naming convention (see [Naming](/contract/naming)).
 
 - Names MUST use dot-separated paths
 - Names MUST be lowercase
@@ -261,7 +272,7 @@ Figma export:
 }
 ```
 
-Normalized Variable Contract:
+Normalized Variable Design Standard (VDS):
 
 ```json
 {
@@ -336,7 +347,7 @@ After normalization, verify:
 - All `@` prefixes removed from collection names
 - All references use canonical format (`{path}`)
 - Mode values moved to `$value` object
-- Names follow Variable Contract naming convention
+- Names follow Variable Design Standard (VDS) naming convention
 
 ## Workflow
 
@@ -377,11 +388,53 @@ Before exporting from Figma:
 ### Artifacts that change
 
 - Figma export JSON (input, not committed)
-- Normalized Variable Contract JSON (committed, reviewed)
+- Normalized Variable Design Standard (VDS) JSON (committed, reviewed)
 - Generated CSS/TypeScript files (output, not committed)
 
+## REST API format handling
+
+For Enterprise plan users with REST API access, the input format differs:
+
+```json
+{
+  "variables": {
+    "VariableID:502:227": {
+      "id": "VariableID:502:227",
+      "name": "color/green/200",
+      "resolvedType": "COLOR",
+      "valuesByMode": {
+        "502:0": {
+          "r": 0.216,
+          "g": 1,
+          "b": 0.341,
+          "a": 1
+        }
+      },
+      "variableCollectionId": "VariableCollectionId:502:189"
+    }
+  },
+  "variableCollections": {
+    "VariableCollectionId:502:189": {
+      "id": "VariableCollectionId:502:189",
+      "name": "Primitives",
+      "modes": [
+        { "modeId": "502:0", "name": "Light" }
+      ]
+    }
+  }
+}
+```
+
+REST API normalization requires:
+
+1. Convert `valuesByMode` to `$value` object with mode names
+2. Convert RGBA objects to color format (hex or colorSpace object)
+3. Build variable hierarchy from `/`-separated names
+4. Resolve variable aliases (which use `VariableAlias` type)
+5. Map collection/mode IDs to names
+
 ## Out of scope
 
-- Figma API integration (use Figma REST API or plugins)
-- Real-time sync (handle via version control)
+- Real-time sync with Figma (handle via version control)
 - Conflict resolution (handle via PR review)
+- Figma plugin development (see [Plugin API](https://developers.figma.com/docs/plugins/api/figma-variables/))

docs/adapters/figma.md

@@ -4,20 +4,20 @@ title: Adapters
 
 # Adapters
 
-Adapters normalize tool outputs into Variable Contract format and transform Variable Contract format into tool inputs.
+Adapters normalize tool outputs into Variable Design Standard (VDS) format and transform Variable Design Standard (VDS) format into tool inputs.
 
 ## Why adapters exist
 
-Design tools export variables in formats that include tool-specific metadata and syntax. Variable Contract defines a canonical format for version control. Adapters bridge the gap between tool formats and the contract.
+Design tools export variables in formats that include tool-specific metadata and syntax. Variable Design Standard (VDS) defines a canonical format for version control. Adapters bridge the gap between tool formats and the contract.
 
 ## Adapter responsibilities
 
 Adapters MUST:
 
-1. Normalize naming to match Variable Contract naming convention
+1. Normalize naming to match Variable Design Standard (VDS) naming convention
 2. Convert reference syntax to canonical format (`{path.to.token}`)
 3. Move tool metadata to `$extensions`
-4. Validate that output conforms to Variable Contract rules
+4. Validate that output conforms to Variable Design Standard (VDS) rules
 
 Adapters MAY:
 
@@ -29,22 +29,22 @@ Adapters MAY:
 
 ### Input adapters
 
-Input adapters convert tool exports into Variable Contract format.
+Input adapters convert tool exports into Variable Design Standard (VDS) format.
 
 Examples:
 
-- Figma Variables export → Variable Contract
-- Tokens Studio export → Variable Contract
+- Figma Variables export → Variable Design Standard (VDS)
+- Tokens Studio export → Variable Design Standard (VDS)
 
 ### Output adapters
 
-Output adapters convert Variable Contract format into tool or platform formats.
+Output adapters convert Variable Design Standard (VDS) format into tool or platform formats.
 
 Examples:
 
-- Variable Contract → Style Dictionary → CSS variables
-- Variable Contract → TypeScript types
-- Variable Contract → Tailwind CSS v4 (`@theme` directive)
+- Variable Design Standard (VDS) → Style Dictionary → CSS variables
+- Variable Design Standard (VDS) → TypeScript types
+- Variable Design Standard (VDS) → Tailwind CSS v4 (`@theme` directive)
 
 ## Adapter pattern
 
@@ -55,7 +55,7 @@ A typical adapter workflow:
 3. Normalize naming (if needed)
 4. Convert references to canonical format
 5. Move metadata to `$extensions`
-6. Validate output against Variable Contract
+6. Validate output against Variable Design Standard (VDS)
 7. Write normalized JSON
 
 ## Failure modes
@@ -71,7 +71,7 @@ If adapters fail:
 
 - [Figma Adapter](figma) - Figma Variables export normalization
 - [Tokens Studio Adapter](tokens-studio) - Tokens Studio export normalization
-- [Style Dictionary Adapter](style-dictionary) - Variable Contract to CSS/TypeScript/etc.
+- [Style Dictionary Adapter](style-dictionary) - Variable Design Standard (VDS) to CSS/TypeScript/etc.
 - [Tailwind Adapter](tailwind) - Tailwind theme configuration generation
 
 ## Out of scope

docs/adapters/index.md

@@ -4,15 +4,15 @@ title: Style Dictionary Adapter
 
 # Style Dictionary Adapter
 
-Style Dictionary consumes Variable Contract (DTCG) format and generates platform outputs like CSS variables, TypeScript types, and Tailwind CSS v4 custom properties.
+Style Dictionary consumes Variable Design Standard (VDS) (DTCG) format and generates platform outputs like CSS variables, TypeScript types, and Tailwind CSS v4 custom properties.
 
 ## Role
 
-Style Dictionary is an output adapter. It reads Variable Contract JSON and produces files for consumption in code.
+Style Dictionary is an output adapter. It reads Variable Design Standard (VDS) JSON and produces files for consumption in code.
 
 ## DTCG format support
 
-Style Dictionary supports DTCG format natively. Use Variable Contract JSON files directly as Style Dictionary source files.
+Style Dictionary supports DTCG format natively. Use Variable Design Standard (VDS) JSON files directly as Style Dictionary source files.
 
 ## Configuration
 
@@ -77,7 +77,7 @@ Legacy Style Dictionary format:
 }
 ```
 
-DTCG format (Variable Contract):
+DTCG format (Variable Design Standard (VDS)):
 
 ```json
 {
@@ -90,7 +90,7 @@ DTCG format (Variable Contract):
 }
 ```
 
-Style Dictionary handles both formats. Use DTCG format for Variable Contract compliance.
+Style Dictionary handles both formats. Use DTCG format for Variable Design Standard (VDS) compliance.
 
 ## Transform groups
 
@@ -196,7 +196,7 @@ CSS output (separate files):
 
 Typical workflow:
 
-1. Store Variable Contract JSON in `tokens/` directory
+1. Store Variable Design Standard (VDS) JSON in `tokens/` directory
 2. Configure Style Dictionary to read from `tokens/`
 3. Run Style Dictionary build
 4. Generated files appear in `dist/`
@@ -219,7 +219,7 @@ Style Dictionary validates:
 - Reference resolution
 - Type correctness (for transforms that check types)
 
-Variable Contract validation should happen before Style Dictionary build (in CI or pre-commit hooks).
+Variable Design Standard (VDS) validation should happen before Style Dictionary build (in CI or pre-commit hooks).
 
 ## Examples
 

docs/adapters/style-dictionary.md

@@ -4,15 +4,15 @@ title: Tailwind Adapter
 
 # Tailwind Adapter
 
-Tailwind CSS v4 integration patterns for Variable Contract. Generate CSS custom properties from Variable Contract JSON using Tailwind CSS v4's CSS-first approach.
+Tailwind CSS v4 integration patterns for Variable Design Standard (VDS). Generate CSS custom properties from Variable Design Standard (VDS) JSON using Tailwind CSS v4's CSS-first approach.
 
 ## Role
 
-Tailwind adapter generates CSS custom properties from Variable Contract JSON. Variables map to Tailwind CSS v4's `@theme` directive. No JavaScript config files. Pure CSS.
+Tailwind adapter generates CSS custom properties from Variable Design Standard (VDS) JSON. Variables map to Tailwind CSS v4's `@theme` directive. No JavaScript config files. Pure CSS.
 
 ## Why Tailwind CSS v4
 
-Tailwind CSS v4 is pure CSS. No JavaScript config. Design Engineers MUST master Tailwind CSS v4. Variable Contract variables map directly to CSS custom properties that Tailwind CSS v4 consumes.
+Tailwind CSS v4 is pure CSS. No JavaScript config. Design Engineers MUST master Tailwind CSS v4. Variable Design Standard (VDS) variables map directly to CSS custom properties that Tailwind CSS v4 consumes.
 
 ## Tailwind CSS v4 approach
 
@@ -32,7 +32,7 @@ See [Tailwind CSS v4 documentation](https://tailwindcss.com/docs) for complete d
 
 ### Pattern 1: CSS custom properties
 
-Generate CSS custom properties from Variable Contract JSON. Tailwind CSS v4 reads CSS variables directly.
+Generate CSS custom properties from Variable Design Standard (VDS) JSON. Tailwind CSS v4 reads CSS variables directly.
 
 **Style Dictionary config:**
 
@@ -92,9 +92,9 @@ Generate CSS custom properties from Variable Contract JSON. Tailwind CSS v4 read
 
 ### Pattern 2: Direct CSS generation
 
-Transform Variable Contract JSON directly to CSS custom properties.
+Transform Variable Design Standard (VDS) JSON directly to CSS custom properties.
 
-**Variable Contract:**
+**Variable Design Standard (VDS):**
 
 ```json
 {
@@ -137,29 +137,29 @@ Transform Variable Contract JSON directly to CSS custom properties.
 
 ### Colors
 
-Variable Contract: `color.primary.500`
+Variable Design Standard (VDS): `color.primary.500`
 CSS: `--color-primary-500: #0066cc`
 Tailwind: `bg-primary-500` or `text-primary-500`
 
 ### Spacing
 
-Variable Contract: `spacing.md`
+Variable Design Standard (VDS): `spacing.md`
 CSS: `--spacing-md: 1rem`
 Tailwind: `p-md` or `m-md`
 
 Tailwind CSS v4 uses a dynamic spacing scale. The `--spacing` variable defines the base unit, and utilities like `px-8`, `mt-17`, `w-29` are generated dynamically using `calc(var(--spacing) * N)`.
 
 ### Typography
 
-Variable Contract: `typography.fontFamily.sans`
+Variable Design Standard (VDS): `typography.fontFamily.sans`
 CSS: `--font-family-sans: "Inter", sans-serif`
 Tailwind: `font-sans`
 
 ## Modes support
 
 Tailwind CSS v4 handles modes via CSS custom properties. Generate mode-specific CSS or use CSS variable overrides.
 
-**Variable Contract with modes:**
+**Variable Design Standard (VDS) with modes:**
 
 ```json
 {
@@ -197,7 +197,7 @@ Design Engineer MUST:
 
 - Master Tailwind CSS v4 CSS-first approach
 - Understand CSS custom properties and `@theme` directive
-- Map Variable Contract structure to CSS custom properties
+- Map Variable Design Standard (VDS) structure to CSS custom properties
 - Test variables in Tailwind components before approval
 - Maintain CSS generation pipeline (no JavaScript config)
 
@@ -206,14 +206,14 @@ Design Engineer MUST:
 1. Designer creates variables in Figma
 2. Export from Figma
 3. Design Engineer normalizes with adapter
-4. Design Engineer generates CSS custom properties from Variable Contract JSON
+4. Design Engineer generates CSS custom properties from Variable Design Standard (VDS) JSON
 5. Design Engineer tests variables in Tailwind CSS v4 components
-6. Commit Variable Contract JSON and generated CSS
+6. Commit Variable Design Standard (VDS) JSON and generated CSS
 7. Frontend Developer consumes Tailwind utilities in components
 
 ## Example component
 
-**Variable Contract:**
+**Variable Design Standard (VDS):**
 
 ```json
 {
@@ -254,7 +254,7 @@ Tailwind CSS v4 generates: `background-color: var(--color-surface-brand)`
 Tailwind adapter MUST:
 
 - Generate valid CSS custom properties syntax
-- Map all Variable Contract variables to CSS custom properties
+- Map all Variable Design Standard (VDS) variables to CSS custom properties
 - Preserve variable references (use CSS `var()` syntax)
 - Handle modes (generate mode-specific CSS or CSS variable overrides)
 - Follow Tailwind CSS v4 naming conventions (`--color-*`, `--spacing-*`, `--font-*`)