@marioschmidt/design-system-tokens 1.0.16 → 1.0.18

package/README.md

@@ -1,16 +1,17 @@
 # 🎨 BILD Design System - Token Pipeline
 
-A comprehensive token transformation pipeline based on **Style Dictionary v4** for the BILD Design System. This pipeline transforms Figma design tokens (exported via VariableVisualizer Plugin) into consumable formats across multiple platforms, brands, and modes.
+A comprehensive multi-platform token transformation pipeline based on **Style Dictionary v4** for the BILD Design System. This pipeline transforms design tokens from a custom Figma plugin export into consumable formats across 7 platforms, 3 brands, and multiple modes.
 
 ## 📋 Table of Contents
 
 - [Overview](#overview)
 - [Features](#features)
-- [Token Architecture](#token-architecture)
 - [Installation](#installation)
-- [Usage](#usage)
+- [Quick Start](#quick-start)
+- [Token Architecture](#token-architecture)
 - [Output Structure](#output-structure)
-- [Configuration](#configuration)
+- [Platform Usage](#platform-usage)
+- [Development](#development)
 - [CI/CD Integration](#cicd-integration)
 - [Troubleshooting](#troubleshooting)
 
@@ -18,25 +19,30 @@ A comprehensive token transformation pipeline based on **Style Dictionary v4** f
 
 ## 🎯 Overview
 
-This token pipeline processes the multi-layer, multi-brand architecture of the BILD Design System with full support for design token aliases, modes, and brand-specific variations.
+This token pipeline processes the multi-layer, multi-brand architecture of the BILD Design System with full support for:
+- **3 Brands**: BILD, SportBILD, Advertorial
+- **7 Platforms**: CSS, SCSS, JavaScript, JSON, iOS (Swift), Android (XML), Flutter (Dart)
+- **Multiple Modes**: Density (3), Breakpoints (4), Color Modes (2)
+- **Composite Tokens**: Typography, Effects
 
 ```
-Figma Tokens (JSON)
+Custom Figma Plugin Export (JSON)
          ↓
-   Preprocessing (scripts/preprocess-figma-tokens.js)
-   • Alias resolution with brand awareness
-   • Mode ID mapping
-   • Collection ID-based filtering
+Preprocessing (scripts/preprocess-plugin-tokens.js)
+• Complete alias resolution (no {Alias.Path} syntax)
+• Context-aware resolution: Brand × Breakpoint × ColorMode
+• Mode name matching (robust against ID changes)
+• FontWeight bug fixes ("700px" → 700)
          ↓
-   Style Dictionary v4 (scripts/build-tokens.js)
-   • Custom transforms
-   • Multi-platform output
-   • Brand-specific builds
+Style Dictionary v4 (scripts/build-tokens-v2.js)
+• Multi-platform output (7 formats)
+• Brand-specific builds
+• Composite token support (Typography, Effects)
          ↓
-  Output Files (CSS, SCSS, JS, JSON)
-  • Platform-first organization
-  • Brand-specific semantic tokens
-  • Zero warnings, fully resolved
+Output Files (dist/)
+• css/, scss/, js/, json/, ios/, android/, flutter/
+• shared/ (primitives) + brands/{brand}/ (brand-specific)
+• 52/52 successful builds
 ```
 
 ---
@@ -45,385 +51,275 @@ Figma Tokens (JSON)
 
 ### Pipeline Features
 
-✅ **Stable Collection IDs**: Uses Figma Collection IDs instead of names for robustness against renaming
-✅ **Zero Warnings**: All false positives eliminated - handles `0`, `false`, `""` values correctly
-✅ **Brand-Aware Alias Resolution**: Cross-collection references resolve correctly per brand
-✅ **Multi-Layer Support**: Base → Mapping → Density → Semantic
-✅ **Multi-Brand**: BILD, SportBILD, Advertorial
-✅ **Multi-Mode**: Light/Dark, Responsive Breakpoints, Density variations
-✅ **Multiple Output Formats**: CSS, SCSS, JavaScript, JSON
-✅ **Hot Reload**: Watch mode for development
+✅ **Complete Alias Resolution**: All `VARIABLE_ALIAS` references resolved to final values in preprocessing
+✅ **7 Platform Support**: CSS, SCSS, JavaScript, JSON, iOS Swift, Android XML, Flutter Dart
+✅ **Multi-Brand Architecture**: BILD, SportBILD, Advertorial with brand-specific token resolution
+✅ **Composite Tokens**: Typography (12 outputs: 3 brands × 4 breakpoints), Effects (6 outputs: 3 brands × 2 color modes)
+✅ **Context-Aware Resolution**: Brand × Breakpoint × ColorMode matrix processing
+✅ **Advertorial Special Handling**: No color/ folder (no BrandColorMapping)
+✅ **Size Class Mapping**: iOS/Android only generate compact (sm) and regular (lg) with sizeclass terminology
+✅ **Zero Reference Errors**: All aliases fully resolved before Style Dictionary
 
-### Architecture Features
+### Build Statistics
 
-✅ **Platform-First Organization**: `dist/css/`, `dist/scss/`, `dist/js/`, `dist/json/`
-✅ **Brand-Specific Semantic Layer**: Tokens organized by brand, then category
-✅ **Recursive Index Files**: Automatic index generation at each level
-✅ **Gitignored Dist**: Build artifacts excluded from version control
+- **52/52 builds successful** across all platforms
+- 4 Shared Primitives (Color, Font, Size, Space)
+- 30 Brand-specific Tokens (3 brands × 10 token sets)
+- 12 Typography Builds (3 brands × 4 breakpoints)
+- 6 Effect Builds (3 brands × 2 color modes)
 
 ---
 
 ## 📦 Installation
 
-### As NPM Package (Recommended)
-
-This package is published to **GitHub Packages** as `@uxwizard25/design-system-tokens`.
+### Prerequisites
 
-#### 1. Configure NPM Registry
+- Node.js >= 20.x
+- npm >= 10.x
 
-Create or edit `.npmrc` in your project root:
+### Setup
 
 ```bash
-@uxwizard25:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
-```
-
-#### 2. Authenticate with GitHub
-
-Create a Personal Access Token (PAT):
-
-1. Go to: https://github.com/settings/tokens
-2. Click **"Generate new token (classic)"**
-3. Name: `npm-packages-read`
-4. Scopes: Select `read:packages`
-5. Click **"Generate token"**
-6. Copy the token
+# Clone repository
+git clone https://github.com/UXWizard25/vv-token-test-v3.git
+cd vv-token-test-v3
 
-Add the token to your `.npmrc`:
+# Install dependencies
+npm install
 
-```bash
-//npm.pkg.github.com/:_authToken=ghp_YOUR_TOKEN_HERE
+# Build tokens
+npm run build
 ```
 
-Or use an environment variable:
+---
 
-```bash
-export GITHUB_TOKEN="ghp_YOUR_TOKEN_HERE"
-```
+## 🚀 Quick Start
 
-#### 3. Install Package
+### Build Tokens
 
 ```bash
-# Latest version
-npm install @uxwizard25/design-system-tokens
-
-# Specific version
-npm install @uxwizard25/design-system-tokens@1.2.3
-
-# As dev dependency
-npm install --save-dev @uxwizard25/design-system-tokens
-```
-
-#### 4. Use in Your Project
-
-**CSS:**
-```css
-/* Import in your main CSS file */
-@import '@uxwizard25/design-system-tokens/css/semantic/bild/color/color-bild-light.css';
-```
-
-**SCSS:**
-```scss
-// Import in your SCSS file
-@import '@uxwizard25/design-system-tokens/scss/semantic/bild/color/color-bild-light';
+# Full build (preprocessing + build)
+npm run build
 
-.my-button {
-  background-color: var(--color-brand-primary);
-}
+# Or run steps separately:
+npm run preprocess    # Custom Plugin JSON → Style Dictionary format
+npm run build:tokens  # Style Dictionary → Platform outputs
 ```
 
-**JavaScript/TypeScript:**
-```javascript
-// Import tokens as JS module
-import tokens from '@uxwizard25/design-system-tokens/json/semantic/bild/color/color-bild-light.json';
-
-console.log(tokens.color.brand.primary); // "#de0000"
-```
+### Watch Mode (Development)
 
-**Webpack/Vite:**
-```javascript
-// In your main.js or main.ts
-import '@uxwizard25/design-system-tokens/css/semantic/bild/color/color-bild-light.css';
+```bash
+npm run watch
 ```
 
-### Local Development
-
-If you want to develop the token pipeline itself:
+### Clean Generated Files
 
 ```bash
-# Clone repository
-git clone https://github.com/UXWizard25/vv-token-test-v3.git
-cd vv-token-test-v3
-
-# Install dependencies
-npm install
-
-# Build tokens
-npm run build
-
-# Watch mode (auto-rebuild on changes)
-npm run watch
+npm run clean
 ```
 
 ---
 
 ## 🏗️ Token Architecture
 
-### Layer Structure
+### Multi-Layer Structure
 
 The Design System is organized in four layers:
 
-#### 1️⃣ **Base Layer** - Primitive Tokens
-
-Foundation tokens without modes (only "Value" mode).
+#### 1️⃣ **Shared Primitives** - Foundation Tokens
 
-- **`_ColorPrimitive`**: Base color palette (includes opacity values)
-- **`_SpacePrimitive`**: Base spacing scale
-- **`_SizePrimitive`**: Base size scale
-- **`_FontPrimitive`**: Base typography
+Base tokens without brand context (single mode: "Value").
 
 **Collections:**
-- `VariableCollectionId:539:2238` → `_ColorPrimitive`
-- `VariableCollectionId:2726:12077` → `_SpacePrimitive`
-- `VariableCollectionId:4072:1817` → `_SizePrimitive`
-- `VariableCollectionId:470:1450` → `_FontPrimitive`
+- `_FontPrimitive` → Font families, weights, letter spacing
+- `_ColorPrimitive` → Base color palette
+- `_SizePrimitive` → Base size scale
+- `_SpacePrimitive` → Base spacing scale
 
 **Output:**
 ```
-dist/css/base/
-  ├── primitive-color-value.css
-  ├── primitive-space-value.css
-  ├── primitive-size-value.css
-  └── primitive-font-value.css
+dist/{platform}/shared/
+  ├── fontprimitive.*
+  ├── colorprimitive.*
+  ├── sizeprimitive.*
+  └── spaceprimitive.*
 ```
 
-#### 2️⃣ **Mapping Layer** - Brand-Specific Tokens
+#### 2️⃣ **Brand-Specific Tokens** - Density & Overrides
 
-Maps primitives to brand identities.
+Brand context tokens with multiple modes.
 
-- **`BrandTokenMapping`**: Modes: BILD, SportBILD, Advertorial
-- **`BrandColorMapping`**: Modes: BILD, SportBILD
+**Density Collection** (3 modes):
+- compact, default, spacious
 
-**Collections:**
-- `VariableCollectionId:18038:10593` → `BrandTokenMapping`
-- `VariableCollectionId:18212:14495` → `BrandColorMapping`
+**Brand Overrides** (3 brands):
+- BrandTokenMapping: BILD, SportBILD, Advertorial
+- BrandColorMapping: BILD, SportBILD (⚠️ Advertorial has no BrandColorMapping)
 
 **Output:**
 ```
-dist/css/mapping/
-  ├── brand-bild.css
-  ├── brand-sportbild.css
-  ├── brand-advertorial.css
-  ├── brand-color-bild.css
-  └── brand-color-sportbild.css
+dist/{platform}/brands/{brand}/
+  ├── density/
+  │   ├── density-compact.*
+  │   ├── density-default.*
+  │   └── density-spacious.*
+  └── overrides/
+      ├── brandtokenmapping.*
+      └── brandcolormapping.*  # Only BILD & SportBILD
 ```
 
-#### 3️⃣ **Density Layer** - Density Variations
+#### 3️⃣ **Semantic Tokens** - Brand × Mode Matrix
 
-Intermediate layer for UI density levels.
+Context-specific tokens with brand and mode variations.
 
-- **`Density`**: Modes: compact, default, spacious
+**BreakpointMode** (4 modes per brand):
+- xs (320px), sm (390px, compact), md (600px), lg (1024px, regular)
 
-**Collections:**
-- `VariableCollectionId:5695:5841` → `Density`
+**ColorMode** (2 modes per brand):
+- light, dark
 
 **Output:**
 ```
-dist/css/density/
-  ├── density-compact.css
-  ├── density-default.css
-  └── density-spacious.css
+dist/{platform}/brands/{brand}/semantic/
+  ├── breakpoints/
+  │   ├── breakpoint-xs-320px.*
+  │   ├── breakpoint-sm-390px-compact.*
+  │   ├── breakpoint-md-600px.*
+  │   └── breakpoint-lg-1024px-regular.*
+  └── color/
+      ├── colormode-light.*
+      └── colormode-dark.*
 ```
 
-#### 4️⃣ **Semantic Layer** - Context-Specific Tokens ⭐
+⚠️ **Note**: Advertorial has **no color/ folder** (no BrandColorMapping collection).
 
-**Brand-specific consumable layer** for applications. Each brand gets its own directory with resolved values.
+#### 4️⃣ **Composite Tokens** - Typography & Effects
 
-- **`ColorMode`**: Modes: Light, Dark (brand-specific)
-- **`BreakpointMode`**: Modes: XS, SM, MD, LG (brand-specific)
+Structured tokens with CSS classes for ready-to-use styles.
 
-**Collections:**
-- `VariableCollectionId:588:1979` → `ColorMode`
-- `VariableCollectionId:7017:25696` → `BreakpointMode`
+**Typography** (4 breakpoints per brand):
+- 3 brands × 4 breakpoints = **12 outputs**
+- CSS: Ready-to-use classes (`.headline1`, `.body1`, etc.)
+- iOS/Android: Only compact (sm) and regular (lg) with sizeclass terminology
 
-**Output:**
-```
-dist/css/semantic/
-  ├── bild/
-  │   ├── color/
-  │   │   ├── color-bild-light.css       # BILD brand with #de0000
-  │   │   └── color-bild-dark.css
-  │   └── breakpoints/
-  │       ├── breakpoint-bild-xs.css
-  │       ├── breakpoint-bild-sm.css
-  │       ├── breakpoint-bild-md.css
-  │       └── breakpoint-bild-lg.css
-  ├── sportbild/
-  │   ├── color/
-  │   │   ├── color-sportbild-light.css  # SportBILD brand with #0a264f
-  │   │   └── color-sportbild-dark.css
-  │   └── breakpoints/
-  │       └── ...
-  └── advertorial/
-      ├── color/
-      │   ├── color-advertorial-light.css
-      │   └── color-advertorial-dark.css
-      └── breakpoints/
-          └── ...
-```
-
-**Key Feature:** Each brand directory contains fully resolved token values specific to that brand. Cross-collection aliases (e.g., from `ColorMode` → `BrandColorMapping`) are resolved correctly per brand during preprocessing.
+**Effects** (2 color modes per brand):
+- 3 brands × 2 color modes = **6 outputs**
+- CSS: Shadow and blur effect classes
+- All platforms: Effect token objects
 
----
-
-## 📦 Installation
-
-### Prerequisites
-
-- Node.js >= 16.x
-- npm >= 8.x
-
-### Setup
-
-```bash
-# Install dependencies
-npm install
-
-# Or with pnpm/yarn
-pnpm install
-yarn install
+**Output:**
 ```
-
----
-
-## 🚀 Usage
-
-### Full Build
-
-```bash
-# 1. Preprocessing: Figma JSON → Intermediate tokens
-npm run preprocess
-
-# 2. Build: Tokens → Output files
-npm run build:tokens
-
-# Or both in one step:
-npm run build
+dist/{platform}/brands/{brand}/semantic/
+  ├── typography/
+  │   ├── typography-xs.*
+  │   ├── typography-sm.*
+  │   ├── typography-md.*
+  │   └── typography-lg.*
+  └── effects/
+      ├── effects-light.*
+      └── effects-dark.*
 ```
 
-**Build Results:**
-- ✅ 30/30 builds successful
-- ✅ 0 warnings
-- ✅ All aliases resolved correctly
-- ✅ Brand-specific values verified
-
-### Watch Mode (Development)
-
-```bash
-# Auto-rebuild on changes
-npm run watch
+**iOS/Android Size Classes:**
 ```
+dist/ios/brands/{brand}/
+  ├── sizeclass-compact/    # sm breakpoint
+  │   └── Typography.swift
+  └── sizeclass-regular/    # lg breakpoint
+      └── Typography.swift
 
-### Clean Build
-
-```bash
-# Remove all generated files
-npm run clean
+dist/android/brands/{brand}/
+  ├── sizeclass-compact/    # sm breakpoint
+  │   └── typography_styles.xml
+  └── sizeclass-regular/    # lg breakpoint
+      └── typography_styles.xml
 ```
 
 ---
 
 ## 📁 Output Structure
 
-### Platform-First Organization
+### Platform Overview
 
 ```
 dist/
-├── manifest.json                    # Manifest of all generated files
+├── manifest.json                    # Build metadata
 │
 ├── css/                            # CSS Custom Properties
-│   ├── base/
-│   │   ├── index.css               # Aggregates all base tokens
-│   │   ├── primitive-color-value.css
-│   │   ├── primitive-color-value-global.css
-│   │   └── ...
-│   ├── mapping/
-│   │   ├── index.css
-│   │   ├── brand-bild.css
-│   │   └── ...
-│   ├── density/
-│   │   ├── index.css
-│   │   └── ...
-│   └── semantic/
+│   ├── shared/                     # Primitives (no brand context)
+│   └── brands/
 │       ├── bild/
-│       │   ├── color/
-│       │   │   ├── index.css
-│       │   │   ├── color-bild-light.css
-│       │   │   ├── color-bild-light-global.css
-│       │   │   └── color-bild-dark.css
-│       │   └── breakpoints/
-│       │       ├── index.css
-│       │       ├── breakpoint-bild-xs.css
-│       │       └── ...
 │       ├── sportbild/
-│       │   └── ...
 │       └── advertorial/
-│           └── ...
 │
 ├── scss/                           # SCSS Variables (same structure)
 ├── js/                             # JavaScript ES6 Modules (same structure)
-└── json/                          # Structured JSON (same structure)
+├── json/                          # JSON Data (same structure)
+│
+├── ios/                            # Swift Classes
+│   ├── shared/
+│   └── brands/{brand}/
+│       ├── density/
+│       ├── overrides/
+│       ├── semantic/
+│       ├── sizeclass-compact/     # sm only
+│       └── sizeclass-regular/     # lg only
+│
+├── android/                        # Android XML Resources
+│   ├── res/values/shared/
+│   └── brands/{brand}/
+│       └── sizeclass-{compact|regular}/
+│
+└── flutter/                        # Flutter Dart Classes (same structure as CSS)
 ```
 
-### File Format Variants
+### Brand Directory Structure
+
+Each brand contains:
 
-Each token set generates multiple variants:
+```
+brands/{brand}/
+├── density/                        # 3 files (compact, default, spacious)
+├── overrides/                      # 1-2 files (brandtokenmapping, brandcolormapping*)
+└── semantic/
+    ├── breakpoints/                # 4 files (xs, sm, md, lg)
+    ├── color/                      # 2 files (light, dark) - BILD & SportBILD only
+    ├── effects/                    # 2 files (light, dark)
+    └── typography/                 # 4 files (xs, sm, md, lg)
+```
 
-| Format | Usage | Selector | Example |
-|--------|-------|----------|---------|
-| `.css` | Data attribute scoped | `[data-color="light"]` | Scoped contexts |
-| `-global.css` | Root scoped | `:root` | Global application |
-| `.scss` | SCSS variables | `$token-name` | Sass preprocessing |
-| `.js` | ES6 module | `import tokens` | JavaScript apps |
-| `.json` | Structured data | JSON | API/tooling |
+⚠️ **Advertorial Exception**: No `color/` folder (no BrandColorMapping)
 
 ---
 
-## 🎨 Usage in Projects
+## 🎨 Platform Usage
 
 ### CSS
 
 ```css
 /* Import brand-specific tokens */
-@import '@bild-ds/tokens/dist/css/semantic/bild/color/color-bild-light.css';
-@import '@bild-ds/tokens/dist/css/semantic/bild/breakpoints/breakpoint-bild-md.css';
-
-/* Or use index files */
-@import '@bild-ds/tokens/dist/css/semantic/bild/color/index.css';
-
-/* Usage with data attributes */
-[data-color="light"] {
-  background: var(--semantic-core-core-color-primary);  /* #de0000 for BILD */
-}
-
-/* Or with global variant */
-@import '@bild-ds/tokens/dist/css/semantic/bild/color/color-bild-light-global.css';
+@import '@marioschmidt/design-system-tokens/css/brands/bild/semantic/color/colormode-light.css';
+@import '@marioschmidt/design-system-tokens/css/brands/bild/semantic/typography/typography-md.css';
 
+/* Use CSS custom properties */
 .button {
-  background: var(--semantic-core-core-color-primary);
+  background-color: var(--bild-red-bild-red);  /* #DD0000 */
+  font-family: var(--font-family-bild-font-family-gotham-cond);
 }
+
+/* Use ready-made typography classes */
+<h1 class="headline1">Headline</h1>
 ```
 
 ### SCSS
 
 ```scss
 // Import brand-specific tokens
-@import '@bild-ds/tokens/dist/scss/semantic/bild/color/color-bild-light.scss';
+@import '@marioschmidt/design-system-tokens/scss/brands/bild/semantic/color/colormode-light';
 
-// Usage
 .button {
-  background-color: $semantic-core-core-color-primary;  // #de0000 for BILD
-  padding: $semantic-spacing-spacing-md;
+  background-color: $bild-red-bild-red;  // #DD0000
+  padding: $space-primitive-space2x;
 }
 ```
 
@@ -431,130 +327,75 @@ Each token set generates multiple variants:
 
 ```javascript
 // Import brand-specific tokens
-import bildColorLight from '@bild-ds/tokens/dist/js/semantic/bild/color/color-bild-light.js';
-import sportbildColorLight from '@bild-ds/tokens/dist/js/semantic/sportbild/color/color-sportbild-light.js';
+import tokens from '@marioschmidt/design-system-tokens/js/brands/bild/semantic/color/colormode-light.js';
 
-// BILD brand
-console.log(bildColorLight['semantic-core-core-color-primary']);  // "#de0000"
-
-// SportBILD brand
-console.log(sportbildColorLight['semantic-core-core-color-primary']);  // "#0a264f"
-```
-
-### React/Styled Components
-
-```jsx
-import bildTokens from '@bild-ds/tokens/dist/js/semantic/bild/color/color-bild-light.js';
+console.log(tokens.BildRedBildRed);  // "#dd0000"
 
+// React/Styled Components
 const Button = styled.button`
-  background-color: ${bildTokens['semantic-core-core-color-primary']};
-  color: ${bildTokens['semantic-core-core-fg-on-primary']};
+  background-color: ${tokens.BildRedBildRed};
 `;
 ```
 
----
-
-## ⚙️ Configuration
-
-### Collection Configuration
-
-Located in `scripts/build-tokens.js`:
+### JSON
 
 ```javascript
-const COLLECTION_CONFIG = {
-  'colormode': {
-    layer: 'semantic',
-    category: 'color',
-    modes: ['light', 'dark'],
-    outputPrefix: 'color',
-    figmaCollectionId: 'VariableCollectionId:588:1979',  // Stable ID
-    figmaCollectionName: 'ColorMode',  // For logging only
-    brandSpecific: true,
-    brands: ['bild', 'sportbild', 'advertorial']
-  },
-  // ... more collections
-};
-```
-
-**Key Points:**
-- Uses **stable Collection IDs** from Figma (robust against renaming)
-- `brandSpecific: true` generates separate files per brand
-- `modeMapping` can transform mode names (e.g., `xs-320px` → `xs`)
-
-### Brand-Specific Collections
-
-Located in `scripts/preprocess-figma-tokens.js`:
+// Import structured token data
+import tokens from '@marioschmidt/design-system-tokens/json/brands/bild/semantic/color/colormode-light.json';
 
-```javascript
-const BRAND_SPECIFIC_COLLECTIONS = {
-  'VariableCollectionId:588:1979': {  // ColorMode
-    collectionName: 'ColorMode',
-    brandSpecific: true,
-    brands: ['bild', 'sportbild', 'advertorial'],
-    brandCollectionIds: [
-      'VariableCollectionId:18038:10593',   // BrandTokenMapping
-      'VariableCollectionId:18212:14495'    // BrandColorMapping
-    ]
-  }
-};
+console.log(tokens);
+// {
+//   "BildRed": {
+//     "bildRed": {
+//       "$type": "color",
+//       "$value": "#DD0000",
+//       "type": "color",
+//       "value": "#DD0000"
+//     }
+//   }
+// }
 ```
 
-**How It Works:**
-1. During preprocessing, ColorMode tokens that reference BrandColorMapping
-2. Are resolved **per brand** using the correct mode ID
-3. Generate separate output files: `light-bild.json`, `light-sportbild.json`, etc.
+### iOS (Swift)
 
-### Style Dictionary Transforms
+```swift
+// Import brand-specific tokens
+import DesignTokens
 
-Custom transforms in `build-config/style-dictionary.config.js`:
+// Use color tokens
+let primaryColor = Colorprimitive.bildRedBildRed  // UIColor
 
-```javascript
-StyleDictionary.registerTransform({
-  name: 'attribute/cti',
-  type: 'attribute',
-  transformer: (token) => {
-    // Custom transformation logic
-  }
-});
+// Use typography (size class aware)
+let typography = Typography.headline1  // Typography struct
 ```
 
----
+### Android (XML)
 
-## 🔄 CI/CD Integration
-
-### GitHub Actions Workflow
+```xml
+<!-- Import brand-specific colors -->
+<resources>
+    <color name="bild_red_bild_red">#DD0000</color>
+    <dimen name="space_2x">16dp</dimen>
 
-Located in `.github/workflows/build-tokens.yml`
-
-**Triggers:**
-- Push to `main`, `develop`, or `claude/**` branches
-- Changes in `src/design-tokens/`
-- Changes in `scripts/` or `build-config/`
-- Manual workflow dispatch
-
-**Build Steps:**
-1. Checkout repository
-2. Setup Node.js
-3. Install dependencies
-4. Run preprocessing
-5. Run build
-6. Upload artifacts
+    <!-- Typography styles (size class aware) -->
+    <style name="Headline1" parent="TextAppearance.AppCompat">
+        <item name="android:fontFamily">@font/gotham_condensed</item>
+        <item name="android:textSize">48sp</item>
+    </style>
+</resources>
+```
 
-**Artifacts:**
-- Name: `design-tokens-{commit-sha}`
-- Retention: 30 days
-- Contains: All generated files
+### Flutter (Dart)
 
-### Manual Workflow Dispatch
+```dart
+// Import brand-specific tokens
+import 'package:design_tokens/brands/bild/semantic/color/colormode_light.dart';
 
-**Via GitHub UI:**
-1. Go to **Actions** tab
-2. Select **"Build Design Tokens"**
-3. Click **"Run workflow"**
+// Use color tokens
+final primaryColor = Colorprimitive.bildRedBildRed;  // Color
 
-**Via GitHub CLI:**
-```bash
-gh workflow run build-tokens.yml
+// Use typography tokens
+final headline1 = Typography.headline1;  // TypographyToken
 ```
 
 ---
@@ -567,43 +408,82 @@ gh workflow run build-tokens.yml
 .
 ├── src/
 │   └── design-tokens/
-│       └── BILD Design System-variables-full.json    # Figma export
+│       └── bild-design-system-raw-data.json    # Custom Figma Plugin export
 │
 ├── scripts/
-│   ├── preprocess-figma-tokens.js                    # Preprocessing
-│   │   • Alias resolution with brand awareness
-│   │   • Collection ID mapping
-│   │   • Mode ID mapping
-│   │   • Zero false positives (handles 0, false, "")
-│   └── build-tokens.js                               # Build orchestration
-│       • Collection configuration
+│   ├── preprocess-plugin-tokens.js             # Preprocessing (965 lines)
+│   │   • Alias resolution to final values
+│   │   • Context-aware resolution (Brand × Breakpoint × ColorMode)
+│   │   • Mode name matching (not ID-based)
+│   │   • FontWeight bug fix ("700px" → 700)
+│   │   • Advertorial special handling (no BrandColorMapping)
+│   │
+│   └── build-tokens-v2.js                      # Build orchestration (551 lines)
+│       • Multi-platform configuration (7 formats)
 │       • Brand-specific builds
-│       • Index file generation
+│       • Composite token support (Typography, Effects)
+│       • Size class mapping for iOS/Android
 │
 ├── build-config/
-│   └── style-dictionary.config.js                    # Custom transforms & formats
+│   └── style-dictionary.config.js              # Custom transforms & formats
+│       • CSS typography classes format
+│       • CSS effect classes format
+│       • iOS Swift typography format
+│       • Android typography XML format
 │
-├── tokens/                                           # Generated (gitignored)
-│   ├── colormode/
-│   │   ├── light-bild.json                          # Brand-specific
-│   │   ├── light-sportbild.json
-│   │   └── ...
-│   └── ...
+├── tokens/                                     # Generated (gitignored)
+│   ├── shared/                                 # Primitives (4 files)
+│   └── brands/                                 # Brand-specific (3 brands)
+│       ├── bild/
+│       ├── sportbild/
+│       └── advertorial/
 │
-├── dist/                                             # Generated (gitignored)
-│   ├── css/
-│   ├── scss/
-│   ├── js/
-│   └── json/
+├── dist/                                       # Generated (gitignored)
+│   ├── css/, scss/, js/, json/                 # Web platforms
+│   ├── ios/, android/, flutter/                # Native platforms
+│   └── manifest.json                           # Build metadata
 │
 └── README.md
 ```
 
+### Custom Figma Plugin Export
+
+The pipeline expects a JSON export from a custom Figma plugin with the following structure:
+
+```json
+{
+  "variableCollections": [
+    {
+      "id": "VariableCollectionId:...",
+      "name": "CollectionName",
+      "modes": [
+        { "modeId": "mode-id", "name": "mode-name" }
+      ],
+      "variableIds": ["VariableID:..."]
+    }
+  ],
+  "variables": [
+    {
+      "id": "VariableID:...",
+      "name": "token/path/name",
+      "resolvedType": "COLOR|FLOAT|STRING",
+      "valuesByMode": {
+        "mode-id": "#DD0000"  // Direct value
+        // OR
+        "mode-id": { "type": "VARIABLE_ALIAS", "id": "VariableID:..." }
+      }
+    }
+  ]
+}
+```
+
+**Export Location**: `src/design-tokens/bild-design-system-raw-data.json`
+
 ### Development Workflow
 
 1. **Export from Figma**
-   - Use VariableVisualizer Plugin
-   - Export as `BILD Design System-variables-full.json`
+   - Use custom Figma plugin
+   - Export as `bild-design-system-raw-data.json`
 
 2. **Place JSON**
    - Save to `src/design-tokens/`
@@ -612,30 +492,99 @@ gh workflow run build-tokens.yml
    ```bash
    npm run preprocess
    ```
-   - Resolves aliases per brand
-   - Creates intermediate token files
-   - **0 warnings expected**
+   - Resolves all aliases to final values
+   - Creates intermediate token files in `tokens/`
+   - Output: 68 JSON files (4 shared + 64 brand-specific)
 
 4. **Build**
    ```bash
    npm run build:tokens
    ```
-   - Transforms to all formats
-   - **30/30 builds expected**
+   - Transforms to all 7 platforms
+   - **52/52 builds successful**
+   - ⚠️ Warnings about token collisions (LetterSpacing) are expected but non-critical
 
 5. **Verify**
    ```bash
    # Check brand-specific values
-   grep "core-color-primary" dist/css/semantic/*/color/*-light.css
+   grep "bild-red" dist/css/brands/bild/semantic/color/colormode-light.css
+   grep "bild-red" dist/css/brands/sportbild/semantic/color/colormode-light.css
 
-   # Expected:
-   # bild: #de0000 (BILD red)
-   # sportbild: #0a264f (SportBILD dark blue)
+   # Check Advertorial has no color folder
+   ls dist/css/brands/advertorial/semantic/
+   # Expected: breakpoints/, effects/, typography/ (NO color/)
+
+   # Check all platforms exist
+   ls dist/
+   # Expected: css/, scss/, js/, json/, ios/, android/, flutter/, manifest.json
    ```
 
 ---
 
-## 🧪 Testing
+## 🔄 CI/CD Integration
+
+### GitHub Actions Workflows
+
+#### 1. Build Tokens (`.github/workflows/build-tokens.yml`)
+
+**Triggers:**
+- Push to `main`, `develop`, `claude/**`, `figma-tokens` branches
+- Changes in `src/design-tokens/`, `scripts/`, `build-config/`
+- Manual workflow dispatch
+
+**Steps:**
+1. Checkout repository
+2. Setup Node.js 20
+3. Install dependencies
+4. Run `npm run build`
+5. Commit dist/ folder to feature branches
+6. Upload build artifacts (30 days retention)
+
+**Outputs:**
+- Validates build success: 52/52 builds
+- Commits dist/ to branch (for PR workflows)
+- Creates artifacts: `design-tokens-{sha}.zip`
+
+#### 2. Auto PR from Figma (`.github/workflows/auto-pr-from-figma.yml`)
+
+**Trigger:**
+- Push to `figma-tokens` branch (from Figma plugin)
+
+**Workflow:**
+```
+Figma Plugin Push → figma-tokens branch
+         ↓
+Build Tokens (52/52)
+         ↓
+Commit dist/ to branch
+         ↓
+Create/Update Pull Request
+         ↓
+Merge to main
+         ↓
+Publish to NPM (automatic)
+```
+
+**PR Format:**
+- Title: "chore: update design tokens from Figma"
+- Body: Build statistics, changed files, diff summary
+- Auto-assigns reviewers
+
+### Manual Workflow Dispatch
+
+**Via GitHub UI:**
+1. Go to **Actions** tab
+2. Select **"Build Design Tokens"**
+3. Click **"Run workflow"**
+
+**Via GitHub CLI:**
+```bash
+gh workflow run build-tokens.yml
+```
+
+---
+
+## 🧪 Testing & Verification
 
 ### Build Verification
 
@@ -643,124 +592,231 @@ gh workflow run build-tokens.yml
 # Run full build
 npm run build
 
-# Check build statistics
-# Expected: 30/30 builds successful, 0 warnings
+# Expected output:
+# 📦 Baue Shared Primitives:
+#   ✅ fontprimitive
+#   ✅ colorprimitive
+#   ✅ sizeprimitive
+#   ✅ spaceprimitive
+#
+# 🏷️  Baue Brand-spezifische Tokens:
+#   📦 bild: ✅ density (3 modes) ✅ breakpoints (4 modes) ✅ color (2 modes) ✅ overrides (2 collections)
+#   📦 sportbild: ✅ density (3 modes) ✅ breakpoints (4 modes) ✅ color (2 modes) ✅ overrides (2 collections)
+#   📦 advertorial: ✅ density (3 modes) ✅ breakpoints (4 modes) ✅ overrides (1 collection)
+#
+# ✍️  Baue Typography Tokens:
+#   🏷️  bild: ✅ bild-xs (css, scss, js, json, flutter) ✅ bild-sm (+ ios, android) ...
+#
+# 🎨 Baue Effect Tokens:
+#   🏷️  Brand: bild ✅ bild-light (css, scss, js, json, ios, android, flutter) ...
+#
+# 📊 Statistiken:
+#    - Shared Primitives: 4/4
+#    - Brand-spezifische Tokens: 30/30
+#    - Typography Builds: 12/12
+#    - Effect Builds: 6/6
+#    - Builds erfolgreich: 52/52
+```
+
+### Brand-Specific Values
+
+```bash
+# BILD should use Gotham Condensed
+grep "font-family-gotham-cond" dist/css/brands/bild/semantic/typography/typography-md.css
+
+# SportBILD should use AntennaExtraCond
+grep "font-family-antenna-extra-cond" dist/css/brands/sportbild/semantic/typography/typography-md.css
 
-# Verify output structure
-ls -R dist/css/semantic/
+# BILD red: #DD0000
+grep "bild-red-bild-red" dist/css/shared/colorprimitive.css
+# Expected: --bild-red-bild-red: #DD0000;
+
+# SportBILD has different brand colors
+grep "sport-bild-dark-blue" dist/css/shared/colorprimitive.css
+```
+
+### Advertorial Special Case
+
+```bash
+# Advertorial should NOT have color/ folder
+ls dist/css/brands/advertorial/semantic/
+# Expected: breakpoints/ effects/ typography/ (NO color/)
 
-# Check brand-specific values
-cat dist/css/semantic/bild/color/color-bild-light.css | grep "core-color-primary"
-cat dist/css/semantic/sportbild/color/color-sportbild-light.css | grep "core-color-primary"
+ls dist/css/brands/bild/semantic/
+# Expected: breakpoints/ color/ effects/ typography/
 ```
 
-### Alias Resolution Check
+### Breakpoint Scaling
 
 ```bash
-# Check for unresolved aliases
-grep -r "UNRESOLVED" tokens/
+# Typography scales across breakpoints
+# headline1 should scale from 48px (xs) to 100px (lg) for BILD
 
-# Expected: No results (all aliases should be resolved)
+grep "headline1" dist/json/brands/bild/semantic/typography/typography-xs.json | grep fontSize
+# Expected: 48px
+
+grep "headline1" dist/json/brands/bild/semantic/typography/typography-lg.json | grep fontSize
+# Expected: 100px
 ```
 
 ---
 
 ## 🆘 Troubleshooting
 
-### Build Warnings
+### ⚠️ Variable nicht gefunden: VariableID:16104:163534
+
+**Problem:** Preprocessing warns about missing variable
+
+**Cause:** Variable `Component/Kicker/Partner/kickerStylebookBgColor` references a deleted/renamed variable in Figma
+
+**Impact:** Non-critical - Token gets `UNRESOLVED_` value, build continues
+
+**Solution:** In Figma, check and re-link the `kickerStylebookBgColor` variable
+
+### ⚠️ Token Collisions in fontprimitive/sizeprimitive/spaceprimitive
+
+**Problem:** Style Dictionary warns about token name collisions for some platforms
 
-**Problem:** Warnings about missing values or circular references
+**Cause:** LetterSpacing tokens have positive/negative values with similar names:
+- `letterSpace-0_25` (negative) → `LetterSpace025` (JS/iOS/Flutter)
+- `letterSpace0_25` (positive) → `LetterSpace025` (same!)
 
-**Solution:** This has been fixed! The pipeline now:
-- Uses `value === undefined || value === null` checks (handles `0`, `false`, `""` correctly)
-- Uses Variable IDs for circular reference detection (not names)
-- Resolves cross-collection aliases correctly per brand
+**Impact:** Non-critical - Last value wins, usually works fine
 
-**Expected:** 0 warnings in both preprocessing and build
+**Platforms Affected:**
+- ❌ JavaScript, iOS, Android, Flutter, JSON (name collision)
+- ✅ CSS, SCSS (no collision - hyphens preserved)
 
-### Brand Values Incorrect
+**Solution (Figma-side):**
+Rename tokens in Figma:
+```
+letterSpace-0_25 → letterSpaceNeg0_25  (or letterSpaceMinus0_25)
+letterSpace0_25  → letterSpacePos0_25  (or letterSpacePlus0_25)
+```
 
-**Problem:** All brands have the same color values
+### Build Failures
 
-**Solution:** This has been fixed! The pipeline now:
-- Maps brand names to Mode IDs in brand collections
-- Resolves aliases using the correct brand-specific mode
-- Generates separate token files per brand
+**Problem:** Build fails with "ENOENT: no such file or directory"
 
-**Verify:**
+**Solution:**
 ```bash
-# BILD should have #de0000
-grep "core-color-primary" dist/css/semantic/bild/color/color-bild-light.css
+# Make sure preprocessing ran first
+npm run preprocess
+
+# Then build
+npm run build:tokens
+
+# Or use the combined command
+npm run build
+```
+
+**Problem:** "Cannot find module 'style-dictionary'"
 
-# SportBILD should have #0a264f
-grep "core-color-primary" dist/css/semantic/sportbild/color/color-sportbild-light.css
+**Solution:**
+```bash
+npm install
 ```
 
-### Merge Conflicts with dist/
+### Missing dist/ Folder
 
-**Problem:** Git conflicts in `dist/` folder
+**Problem:** dist/ folder not visible after build
+
+**Solution:** dist/ is gitignored. It's generated locally or in CI/CD:
+```bash
+npm run build
+ls dist/  # Should show css/, scss/, js/, json/, ios/, android/, flutter/
+```
 
-**Solution:** This has been fixed! `dist/` is now:
-- Fully gitignored
-- Generated locally or in CI/CD
-- Never committed to the repository
+### Wrong Platform Outputs
 
-### Collection Renamed in Figma
+**Problem:** Some platforms missing files
 
-**Problem:** Pipeline breaks after renaming collections in Figma
+**Solution:** Check build output for errors:
+```bash
+npm run build 2>&1 | grep "❌"
+```
 
-**Solution:** This has been fixed! The pipeline now uses:
-- **Stable Collection IDs** instead of names
-- IDs never change even if you rename collections
-- Names are kept only for logging purposes
+All platforms should build successfully: 52/52
 
 ---
 
-## 📊 Build Statistics
+## 📊 Technical Details
 
-**Current Performance:**
-- ✅ 30/30 builds successful
-- ✅ 0 warnings
-- ✅ 0 errors
-- ✅ ~3s preprocessing
-- ✅ ~5s build
-- ✅ 178 token files generated
-- ✅ All cross-collection aliases resolved
-- ✅ Brand-specific values verified
+### Key Design Decisions
 
----
+1. **Complete Alias Resolution in Preprocessing**
+   - No `{Alias.Path}` syntax in Style Dictionary
+   - All aliases resolved to final Hex/px/numeric values
+   - Prevents reference errors in Style Dictionary
 
-## 🔗 Resources
+2. **Context-Aware Alias Resolution**
+   - Brand × Breakpoint × ColorMode matrix
+   - Each context combination gets unique resolution
+   - Example: `colormode-light` for BILD resolves brand-specific aliases using BILD's mode ID
 
-- [Style Dictionary v4 Documentation](https://styledictionary.com/)
-- [Figma Variables API](https://www.figma.com/plugin-docs/api/properties/figma-variables/)
-- [Design Tokens Community Group](https://design-tokens.github.io/community-group/)
-- [VariableVisualizer Plugin](https://www.figma.com/community/plugin/1245712093276493432)
+3. **Mode Name Matching**
+   - Collections have different mode IDs
+   - Match by `mode.name` instead of `mode.modeId`
+   - Robust against Figma re-creating modes
+
+4. **Brand-Specific Processing**
+   - Separate token files per brand and mode
+   - Prevents collisions during Style Dictionary build
+   - Enables brand-specific value verification
+
+5. **Size Class Terminology**
+   - iOS/Android use "sizeclass" terminology
+   - Only compact (sm) and regular (lg) generated
+   - xs and md breakpoints skipped for native platforms
+
+### Performance
+
+- **Preprocessing**: ~2-3 seconds
+- **Build**: ~8-10 seconds (all 52 builds)
+- **Total**: ~11 seconds
+- **Output Size**: ~15 MB (all platforms)
 
 ---
 
 ## 📝 Changelog
 
-### Latest (Current)
+### v2.0.0 (Current) - Custom Plugin Migration
 
 **✨ Features:**
-- Brand-specific semantic layer structure (`dist/css/semantic/{brand}/{category}/`)
-- Stable Collection ID usage (robust against Figma renaming)
-- Zero false positive warnings (correct handling of falsy values)
-- Cross-collection brand-aware alias resolution
-- Recursive index file generation
+- Custom Figma Plugin integration (replaces Variable Visualizer)
+- 7 platform support: CSS, SCSS, JS, JSON, iOS, Android, Flutter
+- Complete alias resolution in preprocessing (no Style Dictionary references)
+- Composite token support: Typography (12 builds), Effects (6 builds)
+- Brand-specific output structure: `dist/{platform}/brands/{brand}/`
+- Advertorial special handling (no color/ folder)
+- Size class mapping for iOS/Android (compact/regular only)
+- Context-aware alias resolution: Brand × Breakpoint × ColorMode
 
 **🐛 Bug Fixes:**
-- Fixed falsy value detection (`0`, `false`, `""` now handled correctly)
-- Fixed false positive circular reference warnings
-- Fixed cross-collection alias resolution for brand-specific tokens
-- Removed `dist/` from git tracking (now fully gitignored)
+- FontWeight bug fix: "700px" → 700
+- Mode name matching instead of ID-based (robust against Figma changes)
+- YAML syntax fix in GitHub Actions (multi-line commit messages)
+- Exit code 0 for successful builds
+- dist/ folder commits to feature branches
 
 **⚡ Performance:**
-- 30/30 builds successful
-- 0 warnings in preprocessing
-- 0 warnings in build
-- All aliases fully resolved
+- 52/52 builds successful (up from 30/30)
+- All 7 platforms generate complete token sets
+- ~11 seconds total build time
+
+**📦 Migration:**
+- New scripts: `preprocess-plugin-tokens.js`, `build-tokens-v2.js`
+- New token source: `bild-design-system-raw-data.json`
+- Removed: Old Variable Visualizer scripts and token files
+
+---
+
+## 🔗 Resources
+
+- [Style Dictionary v4 Documentation](https://styledictionary.com/)
+- [Figma Variables API](https://www.figma.com/plugin-docs/api/properties/figma-variables/)
+- [Design Tokens Community Group](https://design-tokens.github.io/community-group/)
+- [Repository Issues](https://github.com/UXWizard25/vv-token-test-v3/issues)
 
 ---