feat(cli): accept FIGMA_SYNTAX_* token profiles (ADR 051)

packages/cli/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Platform code-syntax token profiles (ADR-051, DirectedEdges/specs#103)** — `format.tokens` now accepts `FIGMA_SYNTAX_WEB`, `FIGMA_SYNTAX_IOS`, and `FIGMA_SYNTAX_ANDROID` in config loading and templates, surfacing the platform code-syntax profiles to CLI users. The transformer (specs-from-figma) emits each variable's Figma `codeSyntax` for the selected platform, falling back to the standard token output when a platform has no code syntax defined.
+
 ### Changed
 
 ### Removed

packages/cli/src/Config/ConfigLoader.ts

@@ -193,7 +193,7 @@ export class ConfigLoader {
     const validKeys = ['SAFE', 'CAMEL', 'SNAKE', 'KEBAB', 'PASCAL', 'TRAIN'];
     const validOutputs = ['JSON', 'YAML'];
     const validLayouts = ['LAYOUT', 'PARENT_CHILDREN', 'BOTH'];
-    const validTokens = ['TOKEN', 'TOKEN_NAME', 'TOKEN_FIGMA_EXTENSIONS', 'FIGMA_NAME', 'CUSTOM'];
+    const validTokens = ['TOKEN', 'TOKEN_NAME', 'TOKEN_FIGMA_EXTENSIONS', 'FIGMA_NAME', 'CUSTOM', 'FIGMA_SYNTAX_WEB', 'FIGMA_SYNTAX_IOS', 'FIGMA_SYNTAX_ANDROID'];
     const validColors = ['HEX', 'HEXA', 'RGB', 'RGBA', 'HSLA', 'HSB', 'OKLCH', 'OKLAB', 'OBJECT'];
 
     // Normalize format values to uppercase before validation

packages/cli/src/Config/ConfigTemplates.ts

@@ -66,7 +66,8 @@ config:
     # See: https://directededges.github.io/specs/config/layout/
     layout: LAYOUT
 
-    # Token reference format: TOKEN, TOKEN_NAME, TOKEN_FIGMA_EXTENSIONS, FIGMA_NAME, or CUSTOM
+    # Token reference format: TOKEN, TOKEN_NAME, TOKEN_FIGMA_EXTENSIONS, FIGMA_NAME, CUSTOM,
+    # FIGMA_SYNTAX_WEB, FIGMA_SYNTAX_IOS, or FIGMA_SYNTAX_ANDROID
     # See: https://directededges.github.io/specs/config/tokens/
     # Requires a license key to resolve token references in output.
     tokens: TOKEN

packages/cli/tests/unit/config/ConfigLoader.test.ts

@@ -216,6 +216,26 @@ sources:
       expect(config.config.format.tokens).toBe('TOKEN'); // Default
     });
 
+    it('should accept all valid format.tokens values', () => {
+      const validValues = ['TOKEN', 'TOKEN_NAME', 'TOKEN_FIGMA_EXTENSIONS', 'FIGMA_NAME', 'CUSTOM', 'FIGMA_SYNTAX_WEB', 'FIGMA_SYNTAX_IOS', 'FIGMA_SYNTAX_ANDROID'];
+
+      validValues.forEach(value => {
+        const configPath = path.join(testDir, 'specs.config.yaml');
+        fs.writeFileSync(configPath, `config:\n  format:\n    tokens: ${value}`);
+
+        const config = configLoader.load();
+        expect(config.config.format.tokens).toBe(value);
+      });
+    });
+
+    it('should normalize lowercase format.tokens to uppercase', () => {
+      const configPath = path.join(testDir, 'specs.config.yaml');
+      fs.writeFileSync(configPath, 'config:\n  format:\n    tokens: figma_syntax_ios');
+
+      const config = configLoader.load();
+      expect(config.config.format.tokens).toBe('FIGMA_SYNTAX_IOS');
+    });
+
     it('should validate format.color and use default for invalid values', () => {
       const configPath = path.join(testDir, 'specs.config.yaml');
       fs.writeFileSync(configPath, 'config:\n  format:\n    color: INVALID');

site/src/content/docs/guides/token-format.md

@@ -90,6 +90,18 @@ borderColor:
       collectionName: DS Color
 ```
 
+#### `FIGMA_SYNTAX_WEB` / `FIGMA_SYNTAX_IOS` / `FIGMA_SYNTAX_ANDROID`
+
+The developer-facing token name a designer assigned for a specific platform via Figma's [code syntax](https://developers.figma.com/docs/plugins/api/CodeSyntaxPlatform/) — `WEB`, `iOS`, or `ANDROID`. Each profile emits that platform's code syntax string:
+
+```yaml
+backgroundColor: --ds-color-text-primary    # FIGMA_SYNTAX_WEB
+backgroundColor: DSColor.textPrimary        # FIGMA_SYNTAX_IOS
+backgroundColor: R.color.ds_text_primary    # FIGMA_SYNTAX_ANDROID
+```
+
+When a token has no code syntax defined for the chosen platform, the profile **falls back to the `TOKEN` output** for that reference, so these profiles are always safe to select. Use them to match the token naming your platform code already expects.
+
 ### Profile Comparison
 
 | Profile | Output shape | Includes type | Includes Figma IDs | Custom mapping |
@@ -99,6 +111,9 @@ borderColor:
 | `TOKEN_FIGMA_EXTENSIONS` | `{ $token, $type, $extensions }` | Yes | Yes | No |
 | `FIGMA_NAME` | `"Collection/Path"` | No | No | No |
 | `CUSTOM` | User-defined or fallback | Varies | Fallback only | Yes |
+| `FIGMA_SYNTAX_WEB` | Platform code syntax string, or `TOKEN` fallback | Fallback only | No | No |
+| `FIGMA_SYNTAX_IOS` | Platform code syntax string, or `TOKEN` fallback | Fallback only | No | No |
+| `FIGMA_SYNTAX_ANDROID` | Platform code syntax string, or `TOKEN` fallback | Fallback only | No | No |
 
 ## When to Use Each Profile
 
@@ -107,6 +122,7 @@ borderColor:
 - **`TOKEN_FIGMA_EXTENSIONS`** — Use when consumers need to trace tokens back to their Figma source — variable IDs, raw resolved values, collection names. Useful for debugging, Figma plugin integrations, or migration tooling.
 - **`FIGMA_NAME`** — Use when consumers expect Figma-native naming with slash delimiters. Good for teams whose token systems mirror the Figma variable structure directly.
 - **`CUSTOM`** — Use when your team has a bespoke token format (e.g., Style Dictionary references, custom JSON shapes). Requires running `specs applyCustomTokens` first to inject `$custom` objects into your fetched data files.
+- **`FIGMA_SYNTAX_WEB` / `FIGMA_SYNTAX_IOS` / `FIGMA_SYNTAX_ANDROID`** — Use when consumers want the platform-specific token name designers set in Figma's code syntax for Web, iOS, or Android. Tokens lacking code syntax for the chosen platform fall back to `TOKEN` output.
 
 ## Configuration