@sxl-studio/token-transformer 1.0.0 → 2.0.0

package/README.en.md

@@ -1,638 +1,107 @@
-# SXL Studio — Token Transformer
+# SXL 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`)
+YAML-first token transformer for generating:
+- CSS custom properties
+- Swift (SwiftUI-ready constants)
+- Kotlin (Compose-ready constants)
+- Android XML resources (`colors.xml`, `dimens.xml`, `strings.xml`, `bools.xml`, `integers.xml`)
 
----
-
-## Quick Start
+## Install
 
 ```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 |
+## Commands
 
-#### `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;
-```
-
----
+```bash
+# transform in smart incremental mode (default)
+npx tsx src/cli.ts sync --config ./config/sxl-transform.config.yaml
 
-## codeSyntax (Figma)
+# force full rebuild
+npx tsx src/cli.ts sync --config ./config/sxl-transform.config.yaml --force
 
-If a token has `$extensions.figma.codeSyntax`, the transformer uses the specified variable names:
+# validate config
+npx tsx src/cli.ts validate-config --config ./config/sxl-transform.config.yaml
 
-```json
-{
-  "primary": {
-    "$value": "#0066FF",
-    "$extensions": {
-      "figma.codeSyntax": {
-        "Web": "var(--color-primary)",
-        "iOS": "Color.primary",
-        "Android": "@color/primary"
-      }
-    }
-  }
-}
+# create starter config
+npx tsx src/cli.ts init --path ./sxl-transform.config.yaml
 ```
 
----
-
-## Math Expressions
-
-Tokens support mathematical expressions that are evaluated during transformation:
+### Smart vs force
 
-```json
-{
-  "spacing": {
-    "sm": { "$value": "{spacing.base} * 2" },
-    "md": { "$value": "{spacing.base} * 4" }
-  }
-}
-```
+- `smart` (default): rebuilds only affected outputs based on changed/removed source files and previous run state.
+- `force`: rebuilds all configured outputs unconditionally.
 
-Supported operations: `+`, `-`, `*`, `/`, `round()`.
+Optional flags:
 
-Expressions are evaluated recursively, including sub-properties of composite tokens.
+- `--mode smart|force`
+- `--force` (shortcut for `--mode force`)
+- `--state-file <path>` (override default state path `<config-name>.state.json`)
 
----
+## Config format
 
-## Usage Examples
+Only YAML is supported.
+JSON config is intentionally unsupported.
 
-### Transform All Projects
+Minimal shape:
 
-```bash
-# Test tokens (example)
-npx tsx src/cli.ts --config=config.example.json
+```yaml
+version: 1
+source:
+  tokenDir: ../../Plugin/test/tokens_project_new
+  configFile: config.json
+  include: ["**/*.json"]
+  exclude: ["config.json", "**/diff-id*.json"]
 
-# Production projects
-npx tsx src/cli.ts --config=config.admin-ui.json
-npx tsx src/cli.ts --config=config.site-ui.json
-```
+options:
+  remBase: 16
+  collisionStrategy: error # error | suffix | namespace-by-file | namespace-by-mode
+  unsupportedTypes:
+    default: warn
+    types:
+      template: skip
+      composition: skip
 
-### Example Config for a New Project
+tokenSets:
+  - id: root
+    selectors:
+      - collection: Core
+        mode: Default
+      - collection: Themes
+        mode: Dark
+        refModeMap:
+          Projects: AUI
+          Core: Default
+      - files: ["projects/aui/*.json"]
 
-```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
-  }
-}
+outputs:
+  - id: css-root
+    platform: css # css | swift | kotlin | xml
+    outputDir: ./project-style/css/adminui
+    resolveAliases: false
+    splitEffects: true
+    showDescriptions: true
+    files:
+      - tokenSet: root
+        output: root.css
 ```
 
----
-
-## Composition → Vue 3 (SFC)
-
-The transformer supports converting composition tokens from JSON into ready-to-use Vue 3 Single File Components (`.vue`).
-
-### Usage
+## Quality gates
 
 ```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
+npm run eslint
+npm run typecheck
+npm run test
+npm run build
+npm run check
 ```
-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`.
+## Notes
 
-### Descriptions ($description) not showing
-Make sure `"showDescriptions": true` is set for the desired platform. Default is `true`.
+- `template` and `composition` token types are skipped by default.
+- `figma.modify` is supported, including chained modifiers and alias-based modifier values.
+- Math expressions are supported with safe parser (`+ - * / %`, `round`, `floor`, `ceil`, `clamp`, etc.).
+- For `collection/mode` selectors you can control dependencies:
+  - `includeRefs: true|false` toggles using token-project `ref` chains in resolver scope.
+  - `refModeMap` forces specific modes for referenced collections (for example `Projects: AUI`).