@sxl-studio/token-transformer 1.0.0

package/README.en.md

@@ -0,0 +1,638 @@
+# SXL Studio — Token Transformer
+
+A tool for transforming design tokens from JSON (DTCG format) into valid code for three platforms:
+- **Web** — CSS Custom Properties
+- **iOS** — SwiftUI
+- **Android** — Kotlin Compose
+- **Vue 3** — Composition JSON → Vue 3 SFC (`.vue`)
+
+---
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Run with default config
+npx tsx src/cli.ts
+
+# Run with specific config
+npx tsx src/cli.ts --config=config.example.json
+
+# Generate a default config
+npx tsx src/cli.ts --init
+
+# Transform composition → Vue 3
+npx tsx src/cli.ts --composition=path/to/composition.json --output=./output/dir
+```
+
+---
+
+## Project Structure
+
+```
+Transformer/
+├── src/
+│   ├── cli.ts                    # CLI entry point
+│   ├── core/
+│   │   ├── types.ts              # Types and interfaces
+│   │   ├── parser.ts             # JSON parsing, alias resolution, math expressions
+│   │   ├── loader.ts             # Token loading from files
+│   │   └── writer.ts             # Transformation and file writing
+│   ├── transformers/
+│   │   ├── css.ts                # CSS Custom Properties generator
+│   │   ├── swiftui.ts            # SwiftUI code generator
+│   │   ├── kotlin.ts             # Kotlin Compose code generator
+│   │   └── vue3.ts               # Composition JSON → Vue 3 SFC
+│   └── utils/
+│       ├── naming.ts             # Naming utilities (kebab, camel, pascal)
+│       ├── color.ts              # Color parsing and formatting
+│       └── dimension.ts          # Dimension parsing and formatting
+├── config.example.json           # Config for test tokens
+├── config.admin-ui.json          # Config for admin-ui project
+├── config.site-ui.json           # Config for site-ui project
+├── project-style/                # Output files (generated)
+└── package.json
+```
+
+---
+
+## Configuration
+
+The config is a JSON file with the following structure:
+
+### Full Schema
+
+```json
+{
+  "source": {
+    "tokenDir": "../Plugin/tokens",
+    "configFile": "config.json",
+    "include": ["example/*.json", "core/*.json"],
+    "exclude": ["config.json", "**/diff-id*.json", "**/composition*"]
+  },
+  "platforms": {
+    "css": {
+      "outputDir": "./project-style/example",
+      "prefix": "ds",
+      "resolveAliases": false,
+      "splitEffects": true,
+      "showDescriptions": true,
+      "codeSyntax": {
+        "colorFormat": "hex",
+        "prefix": "ds"
+      },
+      "fileMapping": [
+        {
+          "sources": ["example/*.json"],
+          "output": "all-tokens.css",
+          "filter": {
+            "types": ["color", "dimension"],
+            "paths": ["color.", "spacing."],
+            "excludePaths": ["color.internal."]
+          }
+        }
+      ]
+    },
+    "swiftui": {
+      "outputDir": "./project-style/example",
+      "prefix": "DS",
+      "resolveAliases": true,
+      "showDescriptions": true,
+      "fileMapping": [
+        {
+          "sources": ["example/*.json"],
+          "output": "AllTokens.swift"
+        }
+      ]
+    },
+    "kotlin": {
+      "outputDir": "./project-style/example",
+      "prefix": "DS",
+      "resolveAliases": true,
+      "showDescriptions": true,
+      "fileMapping": [
+        {
+          "sources": ["example/*.json"],
+          "output": "AllTokens.kt"
+        }
+      ]
+    }
+  },
+  "settings": {
+    "remBase": 16,
+    "verbose": false
+  }
+}
+```
+
+---
+
+### Field Descriptions
+
+#### `source` — Token Source
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `tokenDir` | `string` | required | Path to the JSON token directory |
+| `configFile` | `string` | `"config.json"` | Path to plugin config.json (inside tokenDir) |
+| `include` | `string[]` | all `**/*.json` | Glob patterns for files to include |
+| `exclude` | `string[]` | `["config.json"]` | Glob patterns for files to exclude |
+
+#### `platforms` — Platform Settings
+
+Each platform (`css`, `swiftui`, `kotlin`) is configured independently:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `outputDir` | `string` | required | Output directory for generated files |
+| `prefix` | `string` | `""` | Prefix for variable names |
+| `resolveAliases` | `boolean` | CSS: `false`, Swift/Kotlin: `true` | Whether to resolve aliases to final values |
+| `splitEffects` | `boolean` | `true` | Split effects into separate variables (CSS only) |
+| `showDescriptions` | `boolean` | `true` | Include `$description` as comments in output |
+| `codeSyntax` | `object` | — | Code format settings |
+| `fileMapping` | `array` | — | Rules for merging tokens into files |
+
+#### `resolveAliases` — Alias Control
+
+The key setting that determines how alias references (`{token.path}`) are handled in composite tokens.
+
+**CSS (`resolveAliases: false` — default):**
+```css
+/* Aliases preserved as var() */
+--typography-heading-xl: var(--font-weight-bold) var(--font-size-3xl)/var(--line-height-relaxed) var(--font-family-sans);
+--shadow-sm: var(--number-fx-offset-xs) var(--number-fx-offset-none) var(--number-fx-blur-xs) var(--number-fx-offset-none) var(--color-hex-alpha);
+```
+
+**CSS (`resolveAliases: true`):**
+```css
+/* All values fully resolved */
+--ds-typography-heading-xl: 700 30px/24px Inter;
+--ds-shadow-sm: 2px 0px 8px 0px rgba(255, 85, 0, 0.502);
+```
+
+**SwiftUI/Kotlin (`resolveAliases: false`):**
+- Pure aliases (entire token = reference) → same-scope constant reference
+- Composite tokens with aliased fields → `/// @ref` / `/** @ref */` comments with paths
+
+```swift
+/// @ref {color.hex-full}
+static let primary = hexFull                    // ← direct reference
+
+/// @ref {fontFamily.sans}, {fontWeight.bold}, {fontSize.3xl}, {lineHeight.relaxed}
+static let headingXl: Font = .system(size: 30, weight: .bold)  // ← values + ref comment
+```
+
+**SwiftUI/Kotlin (`resolveAliases: true` — default):**
+```swift
+static let primary = Color(red: 1, green: 0.3333, blue: 0, opacity: 1)  // ← fully resolved
+```
+
+#### `splitEffects` — Effects Splitting (CSS only)
+
+Controls how mixed effects (shadow + blur + backdrop-blur) are handled.
+
+**`splitEffects: true` (default):**
+
+Mixed effects are split into separate variables with suffixes. Each variable maps to a specific CSS property:
+
+```css
+/* box-shadow */
+--effects-full-mix: 0 2px 8px rgba(0,0,0,0.08), inset 0 1px 2px rgba(255,255,255,0.5);
+/* filter */
+--effects-full-mix-blur: blur(2px);
+/* backdrop-filter */
+--effects-full-mix-backdrop-blur: blur(20px);
+```
+
+Usage:
+```css
+.card {
+  box-shadow: var(--effects-full-mix);
+  filter: var(--effects-full-mix-blur);
+  backdrop-filter: var(--effects-full-mix-backdrop-blur);
+}
+```
+
+**`splitEffects: false`:**
+
+All effects are output as a single variable, shadow part only:
+
+```css
+--effects-full-mix: 0 2px 8px rgba(0,0,0,0.08), inset 0 1px 2px rgba(255,255,255,0.5);
+```
+
+#### `showDescriptions` — Token Descriptions
+
+Controls whether `$description` from JSON is included as comments. Works on all platforms.
+
+**`showDescriptions: true` (default):**
+```css
+/* Heading XL — all values raw */
+--typography-heading-xl: 700 30px/24px Inter;
+```
+
+```swift
+/// Heading XL — all values raw
+static let headingXl: Font = .system(size: 30, weight: .bold)
+```
+
+```kotlin
+/** Heading XL — all values raw */
+val HeadingXl = TextStyle(...)
+```
+
+**`showDescriptions: false`:**
+```css
+--typography-heading-xl: 700 30px/24px Inter;
+```
+
+```swift
+static let headingXl: Font = .system(size: 30, weight: .bold)
+```
+
+```kotlin
+val HeadingXl = TextStyle(...)
+```
+
+#### `fileMapping` — File Merging Rules
+
+Allows combining tokens from multiple JSON files into a single output file.
+
+```json
+{
+  "sources": ["core/palette.json", "projects/aui/colors.json", "projects/modes/themes/light.json"],
+  "output": "core.css",
+  "filter": {
+    "types": ["color", "dimension"],
+    "paths": ["color.primary"],
+    "excludePaths": ["color.internal"]
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `sources` | Array of JSON file paths (supports `*` wildcards) |
+| `output` | Output file name (relative to `outputDir`) |
+| `filter.types` | Filter by token type |
+| `filter.paths` | Include only paths starting with specified prefixes |
+| `filter.excludePaths` | Exclude paths starting with specified prefixes |
+
+#### `settings` — Global Settings
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `remBase` | `number` | `16` | Base value for rem calculations |
+| `verbose` | `boolean` | `false` | Verbose logging output |
+
+---
+
+## Supported Token Types
+
+### Simple Types
+
+| Type | CSS | SwiftUI | Kotlin |
+|------|-----|---------|--------|
+| `color` | `#hex` / `rgba()` | `Color(red:green:blue:opacity:)` | `Color(0xAARRGGBB)` |
+| `dimension` | `16px` / `1rem` | `CGFloat` | `Dp` |
+| `spacing`, `sizing` | `16px` | `CGFloat` | `Dp` |
+| `borderRadius`, `borderWidth` | `4px` | `CGFloat` | `Dp` |
+| `opacity` | `0.5` | `Double` | `Float` |
+| `number` | `42` | numeric | numeric |
+| `fontFamily` | `"Inter"` | `String` | `String` |
+| `fontWeight` | `700` | `Font.Weight` | `FontWeight` |
+| `fontSize`, `lineHeight` | `16px` | `CGFloat` | `TextUnit (sp)` |
+| `letterSpacing` | `0.5px` | `CGFloat` | `TextUnit (sp)` |
+| `duration` | `200ms` | `String` | `String` |
+| `cubicBezier` | `cubic-bezier(...)` | `String` | `String` |
+| `boolean` | `true` | `Bool` | `Boolean` |
+| `text`, `string` | `"value"` | `String` | `String` |
+| `textCase` | `uppercase` | `String` | `String` |
+| `textDecoration` | `underline` | `String` | `String` |
+| `strokeStyle` | `dashed /* ... */` | `String` | `String` |
+
+### Composite Types
+
+| Type | CSS | SwiftUI | Kotlin |
+|------|-----|---------|--------|
+| `typography` | `700 16px/24px Inter` | `Font.system(size:weight:)` | `TextStyle(...)` |
+| `shadow` | `0 4px 8px rgba(...)` | `.shadow(color:radius:x:y:)` | `elevation (Dp)` |
+| `border` | `1px solid #000` | `(color:width:style:)` | `BorderStroke(...)` |
+| `fill` | `#hex` / `gradient(...)` | `Color(...)` / `Gradient(...)` | `Color(...)` / `Brush(...)` |
+| `gradient` | `linear-gradient(...)` | `LinearGradient(...)` | `Brush.linearGradient(...)` |
+| `effects` | see below | `.shadow(...)` | `elevation (Dp)` |
+| `blur` | `blur(4px)` | `.blur(radius:)` | `Modifier.blur(...)` |
+| `backdrop-blur` | `blur(16px)` | `.blur(radius:)` | `Modifier.blur(...)` |
+| `transition` | `all 200ms ease` | `String` | `String` |
+| `grid` | `repeat(12, 1fr)` | `String` | `String` |
+
+---
+
+## Effects Handling (CSS)
+
+In CSS, different effect types map to different CSS properties. The transformer automatically creates separate variables for each type:
+
+### Single Effect Type
+
+```css
+/* box-shadow */
+--effects-card: 0 4px 8px rgba(0,0,0,0.1);
+
+/* filter */
+--blur-sm: blur(4px);
+
+/* backdrop-filter */
+--backdrop-blur-md: blur(12px);
+```
+
+### Mixed Effects (shadow + blur + backdrop-blur)
+
+When a token contains multiple effect types, they are split into separate variables with suffixes:
+
+```css
+/* box-shadow */
+--effects-full-mix: 0 2px 8px rgba(0,0,0,0.08), inset 0 1px 2px rgba(255,255,255,0.5);
+/* filter */
+--effects-full-mix-blur: blur(2px);
+/* backdrop-filter */
+--effects-full-mix-backdrop-blur: blur(20px);
+```
+
+Usage in CSS:
+```css
+.card {
+  box-shadow: var(--effects-full-mix);
+  filter: var(--effects-full-mix-blur);
+  backdrop-filter: var(--effects-full-mix-backdrop-blur);
+}
+```
+
+---
+
+## Aliases in Composite Tokens
+
+All composite token types (typography, shadow, border, fill, gradient, effects) support alias references `{token.path}` in any sub-property.
+
+### JSON Example
+
+```json
+{
+  "heading": {
+    "xl": {
+      "$type": "typography",
+      "$value": {
+        "fontFamily": "{fontFamily.sans}",
+        "fontWeight": "{fontWeight.bold}",
+        "fontSize": "{fontSize.3xl}",
+        "lineHeight": "{lineHeight.relaxed}"
+      }
+    }
+  }
+}
+```
+
+### CSS Output (resolveAliases: false)
+
+```css
+--typography-heading-xl: var(--font-weight-bold) var(--font-size-3xl)/var(--line-height-relaxed) var(--font-family-sans);
+```
+
+### CSS Output (resolveAliases: true)
+
+```css
+--typography-heading-xl: 700 30px/24px Inter;
+```
+
+---
+
+## codeSyntax (Figma)
+
+If a token has `$extensions.figma.codeSyntax`, the transformer uses the specified variable names:
+
+```json
+{
+  "primary": {
+    "$value": "#0066FF",
+    "$extensions": {
+      "figma.codeSyntax": {
+        "Web": "var(--color-primary)",
+        "iOS": "Color.primary",
+        "Android": "@color/primary"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Math Expressions
+
+Tokens support mathematical expressions that are evaluated during transformation:
+
+```json
+{
+  "spacing": {
+    "sm": { "$value": "{spacing.base} * 2" },
+    "md": { "$value": "{spacing.base} * 4" }
+  }
+}
+```
+
+Supported operations: `+`, `-`, `*`, `/`, `round()`.
+
+Expressions are evaluated recursively, including sub-properties of composite tokens.
+
+---
+
+## Usage Examples
+
+### Transform All Projects
+
+```bash
+# Test tokens (example)
+npx tsx src/cli.ts --config=config.example.json
+
+# Production projects
+npx tsx src/cli.ts --config=config.admin-ui.json
+npx tsx src/cli.ts --config=config.site-ui.json
+```
+
+### Example Config for a New Project
+
+```json
+{
+  "source": {
+    "tokenDir": "./path/to/tokens",
+    "exclude": ["config.json"]
+  },
+  "platforms": {
+    "css": {
+      "outputDir": "./dist/css",
+      "prefix": "my",
+      "resolveAliases": false,
+      "splitEffects": true,
+      "showDescriptions": true,
+      "fileMapping": [
+        {
+          "sources": ["core/*.json", "themes/light.json"],
+          "output": "core.css"
+        },
+        {
+          "sources": ["themes/dark.json"],
+          "output": "themes/dark.css"
+        }
+      ]
+    },
+    "swiftui": {
+      "outputDir": "./dist/ios",
+      "prefix": "My",
+      "resolveAliases": false,
+      "showDescriptions": true,
+      "fileMapping": [
+        {
+          "sources": ["core/*.json", "themes/light.json"],
+          "output": "MyTokens.swift"
+        }
+      ]
+    },
+    "kotlin": {
+      "outputDir": "./dist/android",
+      "prefix": "My",
+      "resolveAliases": true,
+      "showDescriptions": false,
+      "fileMapping": [
+        {
+          "sources": ["core/*.json", "themes/light.json"],
+          "output": "MyTokens.kt"
+        }
+      ]
+    }
+  },
+  "settings": {
+    "remBase": 16
+  }
+}
+```
+
+---
+
+## Composition → Vue 3 (SFC)
+
+The transformer supports converting composition tokens from JSON into ready-to-use Vue 3 Single File Components (`.vue`).
+
+### Usage
+
+```bash
+npx tsx src/cli.ts --composition=path/to/composition.json --output=./output/dir
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `--composition` | Path to the composition JSON file |
+| `--output` | Output directory for the `.vue` file (defaults to source directory) |
+
+### Input JSON Format
+
+```json
+{
+  "$type": "composition",
+  "name": "WButton",
+  "props": {
+    "state": ["default", "hover", "active", "disabled"],
+    "style": ["accent", "secondary", "tertiary"],
+    "size": ["sm", "md", "lg"]
+  },
+  "structure": { "tag": "FRAME", "class": "btn", "children": [...] },
+  "componentProperties": { "label": { "type": "TEXT", "layer": "btn-label", "defaultValue": "Button" } },
+  "styles": { "btn": { "layoutMode": "HORIZONTAL", "fills": ["{accent.medium}"], ... } },
+  "adapters": { "style=accent": { "btn": { "fills": ["{info.medium}"] } } }
+}
+```
+
+### What Gets Generated
+
+A complete Vue 3 SFC with three sections:
+
+**`<template>`** — HTML structure from `structure`:
+- `FRAME` → `<div>` / `<button>` (inferred from component name)
+- `TEXT` → `<span>` with prop or slot binding
+- `INSTANCE` → component tag (`<WIcon>`, etc.)
+- `BOOLEAN` properties → `v-if` directives
+- `INSTANCE_SWAP` → dynamic `:name` prop
+
+**`<script setup lang="ts">`** — logic:
+- `defineProps<Props>()` with types from `props` and `componentProperties`
+- `withDefaults()` with default values
+- `useCssModule()` for CSS Modules
+- `computed()` for variant/size classes with exhaustive `Record<>` mapping
+- `style` prop auto-renamed to `variant` (Vue reserved word conflict)
+- `state=disabled` → separate `disabled` boolean prop
+
+**`<style module>`** — CSS:
+- Base styles from `styles` with Figma → CSS property mapping
+- Modifier classes from `adapters` (`.btn--accent`, `.btn--sm`, etc.)
+- `state=hover/active/focus` → CSS pseudo-classes (`:hover`, `:active`, `:focus`)
+- `state=disabled` → `.btn--disabled` + `:disabled`
+- Token references `{accent.medium}` → `var(--accent-medium)`
+- TEXT/INSTANCE layers: `fills` → `color` (not `background-color`)
+
+### Figma → CSS Property Mapping
+
+| Figma | CSS |
+|-------|-----|
+| `layoutMode: "HORIZONTAL"` | `display: flex` |
+| `layoutMode: "VERTICAL"` | `display: flex; flex-direction: column` |
+| `primaryAxisAlignItems` | `justify-content` |
+| `counterAxisAlignItems` | `align-items` |
+| `layoutSizingHorizontal: "HUG"` | `width: fit-content` |
+| `layoutSizingHorizontal: "FILL"` | `flex: 1` |
+| `itemSpacing` | `gap` |
+| `padding*` | `padding` (shorthand) |
+| `cornerRadius` | `border-radius` |
+| `fills: ["{token}"]` | `background-color: var(--token)` / `color: var(--token)` |
+| `strokeWeight` + `strokes` | `border` |
+| `opacity` | `opacity` |
+| `fontSize` | `font-size` |
+| `fontWeight` | `font-weight` (name → number mapping) |
+
+---
+
+## Prefix Reference
+
+| Platform | Prefix | Naming Result |
+|----------|--------|---------------|
+| CSS | `""` | `--color-primary` |
+| CSS | `"ds"` | `--ds-color-primary` |
+| SwiftUI | `""` | `Color.colorPrimary`, `enum Spacing` |
+| SwiftUI | `"DS"` | `Color.dsColorPrimary`, `enum DSSpacing` |
+| Kotlin | `""` | `DSColors.ColorPrimary`, `DSSpacing.SpacingXs` |
+| Kotlin | `"App"` | `AppColors.ColorPrimary`, `AppSpacing.SpacingXs` |
+
+---
+
+## Troubleshooting
+
+### Config file not found
+```
+Config file not found: ...
+Run with --init to generate a default config.
+```
+Use `--config=path/to/file.json` or `--init` to generate one.
+
+### Tokens missing from output
+Check `fileMapping.sources` — paths are **relative to tokenDir**.
+
+### `var()` not appearing in CSS
+Make sure `"resolveAliases": false` is set for the `css` platform.
+
+### Aliases not resolving
+Ensure the source token exists in the included files (`include` / `sources`).
+
+### Effects not splitting into separate variables
+Make sure `"splitEffects": true` is set for the `css` platform. Default is `true`.
+
+### Descriptions ($description) not showing
+Make sure `"showDescriptions": true` is set for the desired platform. Default is `true`.