@marioschmidt/design-system-tokens 1.0.41 → 1.0.43

package/README.md

@@ -1,1193 +1,1247 @@
-# 🎨 BILD Design System - Token Pipeline
+# 🎨 BILD Design System - Token Pipeline v3
 
-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.
+A production-ready multi-platform design token transformation pipeline powered by **Style Dictionary v4** with **Figma-scoped semantic type detection**. Transforms design tokens from Figma Variables export into consumable formats across 7 platforms, 3 brands, and multiple modes.
+
+[![Build Status](https://github.com/UXWizard25/vv-token-test-v3/workflows/Build%20Design%20Tokens/badge.svg)](https://github.com/UXWizard25/vv-token-test-v3/actions)
+[![npm version](https://img.shields.io/npm/v/@marioschmidt/design-system-tokens.svg)](https://www.npmjs.com/package/@marioschmidt/design-system-tokens)
 
 ## 📋 Table of Contents
 
 - [🎯 Overview](#-overview)
-- [✨ Features](#-features)
+- [✨ Key Features](#-key-features)
+- [🏗️ Architecture](#️-architecture)
+- [📊 Token Transform Reference](#-token-transform-reference)
+- [🔗 Figma Integration & Dependencies](#-figma-integration--dependencies)
 - [📦 Installation](#-installation)
 - [🚀 Quick Start](#-quick-start)
-- [🏗️ Token Architecture](#️-token-architecture)
+- [🎨 Platform Usage Examples](#-platform-usage-examples)
 - [📁 Output Structure](#-output-structure)
-- [🎨 Platform Usage](#-platform-usage)
 - [🔧 Development](#-development)
 - [🔄 CI/CD Integration](#-cicd-integration)
-- [🧪 Testing & Verification](#-testing--verification)
 - [🆘 Troubleshooting](#-troubleshooting)
-- [📊 Technical Details](#-technical-details)
 - [📝 Changelog](#-changelog)
-- [🔗 Resources](#-resources)
 
 ---
 
 ## 🎯 Overview
 
-This token pipeline processes the multi-layer, multi-brand architecture of the BILD Design System with full support for:
+This pipeline processes the multi-layer, multi-brand BILD Design System architecture with **production-ready outputs** 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
+- **Token Types**: Primitives, Semantic Tokens, Component Tokens (~917 files)
+- **Composite Tokens**: Typography, Effects/Shadows (semantic + component-specific)
+
+### Pipeline Flow
 
 ```
 ┌─────────────────────────────────────────────┐
-│ Figma Plugin Export (src/design-tokens/)   │
+│ Figma Variables (Design Source)            │
+│ • BILD Design System file                   │
+│ • Variables with Scopes & Aliases           │
+│ • TokenSync plugin export                   │
+└─────────────────────────────────────────────┘
+                  ↓
+┌─────────────────────────────────────────────┐
+│ Raw Export (src/design-tokens/)            │
 │ • bild-design-system-raw-data.json          │
-│ • Contains aliases and Figma structure      │
+│ • Figma structure with scopes & aliases    │
+│ • FLOAT values as pure numbers (no units)  │
 └─────────────────────────────────────────────┘
                   ↓
 ┌─────────────────────────────────────────────┐
 │ Preprocessing (scripts/preprocess-*.js)    │
-│ • Complete alias resolution                 │
-│ • Context-aware: Brand × Breakpoint × Mode  │
-│ • FontWeight bug fixes ("700px" → 700)      │
+│ • Scope-based type determination            │
+│ • Alias resolution                          │
+│ • Component token detection & organization  │
+│ • Opacity conversion (Figma % → 0-1)       │
+│ • Floating-point rounding                   │
 └─────────────────────────────────────────────┘
                   ↓
 ┌─────────────────────────────────────────────┐
-│ Intermediate Format (tokens/)              │
-│ • 68 JSON files (Style Dictionary format)   │
-│ • Tracked in Git (preprocessed source)      │
+│ Intermediate (tokens/)                     │
+│ • Style Dictionary format                   │
+│ • ~920 JSON files (tracked in Git)         │
+│ • Ready for multi-platform transformation  │
 └─────────────────────────────────────────────┘
                   ↓
 ┌─────────────────────────────────────────────┐
-│ Style Dictionary v4 (scripts/build-*.js)   │
-│ • Multi-platform output (7 formats)         │
-│ • Brand-specific builds (3 brands)          │
-│ • Composite tokens (Typography, Effects)    │
+│ Style Dictionary Build                     │
+│ • Platform-specific transforms              │
+│ • iOS: CGFloat Points (not px strings)     │
+│ • iOS: UIColor objects (not strings)       │
+│ • Typography: px units for web/Flutter     │
+│ • Value rounding & precision cleanup       │
 └─────────────────────────────────────────────┘
                   ↓
 ┌─────────────────────────────────────────────┐
-│ Build Artifacts (dist/)                    │
-│ • NOT tracked in Git                        │
-│ • Generated locally or in CI                │
-│ • Available as GitHub Actions artifacts     │
-│ • 52/52 successful builds (353 files)       │
+│ Build Output (dist/)                       │
+│ • 969 successful builds                     │
+│ • Production-ready for all platforms        │
+│ • NOT tracked in Git (CI artifacts)         │
 └─────────────────────────────────────────────┘
 ```
 
 ---
 
-## ✨ Features
+## ✨ Key Features
 
-### Pipeline Features
+### 🎯 Production-Ready Outputs
 
-✅ **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
+✅ **Platform-Native Formats**
+- CSS: `var(--token-name)` with proper units
+- iOS Swift: `UIColor` objects, `CGFloat` points, `UIFont` instances
+- Flutter: `Color(0xFF...)`, `BoxShadow` arrays
+- Android: XML resources with proper types (`<color>`, `<dimen>`)
 
-### Build Statistics
+✅ **Scope-Based Type Detection**
+- Figma scopes determine token types (Priority 1)
+- Name-based fallback for missing scopes (Priority 2)
+- Automatic unit assignment (px, opacity, fontWeight)
 
-- **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)
+✅ **Precision & Rounding**
+- Floating-point errors eliminated (`0.699999988` → `0.7`)
+- Consistent rounding across all platforms
+- Safe decimal precision (2 places standard, 3 for UIColor)
 
----
-
-## 📦 Installation
-
-### Prerequisites
+✅ **Cross-Platform Compatibility**
+- Naming conventions follow platform best practices
+- Type-safe outputs (no string px values on iOS)
+- Composite tokens (Typography, Effects) fully supported
 
-- Node.js >= 20.x
-- npm >= 10.x
+### 🏗️ Pipeline Features
 
-### Setup
+✅ **Figma Integration**
+- Direct Figma Variables export support
+- Scope-aware token processing
+- Alias resolution with circular reference detection
+- Opacity conversion (Figma % → CSS decimal)
 
-```bash
-# Clone repository
-git clone https://github.com/UXWizard25/vv-token-test-v3.git
-cd vv-token-test-v3
+✅ **Multi-Platform Builds**
+- 969 successful builds across 7 platforms
+- 3 brands × multiple modes
+- Composite tokens (Typography: 12 outputs, Effects: 6 outputs)
 
-# Install dependencies
-npm install
-
-# Build tokens
-npm run build
-```
+✅ **CI/CD Ready**
+- GitHub Actions integration
+- Automatic PR creation from Figma exports
+- Build artifacts with 30-day retention
+- NPM publishing on merge
 
 ---
 
-## 🚀 Quick Start
+## 🏗️ Architecture
 
-### Build Tokens
+### Token Processing Stages
 
-```bash
-# Full build (preprocessing + build)
-npm run build
+#### 1️⃣ **Figma Export** (`src/design-tokens/`)
 
-# Or run steps separately:
-npm run preprocess    # Custom Plugin JSON → Style Dictionary format
-npm run build:tokens  # Style Dictionary → Platform outputs
-```
-
-### Watch Mode (Development)
+Raw Figma Variables export containing:
+- **Variables** with `scopes` array (semantic type info)
+- **Aliases** (references to other variables)
+- **FLOAT values** as pure numbers (units assigned later)
+- **Collections & Modes** structure
 
-```bash
-npm run watch
-```
-
-### Clean Generated Files
-
-```bash
-npm run clean
+**Key Properties:**
+```json
+{
+  "variables": [
+    {
+      "name": "Semantic/LayerOpacity/layerOpacity05",
+      "resolvedType": "FLOAT",
+      "scopes": ["OPACITY"],
+      "valuesByMode": {
+        "539:2": 5  // Figma opacity as percentage
+      }
+    },
+    {
+      "name": "Component/Button/buttonPrimaryBgColor",
+      "resolvedType": "COLOR",
+      "scopes": ["ALL_SCOPES"],
+      "valuesByMode": {
+        "588:0": { "type": "VARIABLE_ALIAS", "id": "..." }  // Alias to semantic token
+      }
+    }
+  ]
+}
 ```
 
----
-
-## 🏗️ Token Architecture
-
-### Multi-Layer Structure
-
-The Design System is organized in four layers:
-
-#### 1️⃣ **Shared Primitives** - Foundation Tokens
+#### 2️⃣ **Preprocessing** (`tokens/`)
 
-Base tokens without brand context (single mode: "Value").
+Transforms raw Figma data into Style Dictionary format:
 
-**Collections:**
-- `_FontPrimitive` → Font families, weights, letter spacing
-- `_ColorPrimitive` → Base color palette
-- `_SizePrimitive` → Base size scale
-- `_SpacePrimitive` → Base spacing scale
-
-**Output:**
+**Component Token Detection:**
+```javascript
+// Automatic detection based on path prefix
+"Component/Button/buttonPrimaryBgColor" → Component Token (organized in components/Button/)
+"Component/Alert/alertBorderWidth" → Component Token (organized in components/Alert/)
+"Semantic/TextColor/textColorPrimary" → Semantic Token (organized in semantic/)
+"ColorPrimitive/red500" → Primitive Token (organized in shared/)
 ```
-dist/{platform}/shared/
-  ├── fontprimitive.*
-  ├── colorprimitive.*
-  ├── sizeprimitive.*
-  └── spaceprimitive.*
+
+**Scope-Based Type Determination:**
+```javascript
+// Priority 1: Figma Scopes (semantic meaning)
+scopes: ["OPACITY"] → $type: "opacity"
+scopes: ["WIDTH_HEIGHT", "GAP"] → $type: "dimension"
+scopes: ["FONT_SIZE"] → $type: "fontSize"
+scopes: ["FONT_WEIGHT"] → $type: "fontWeight"
+
+// Priority 2: Name-based fallback (if no scopes)
+"border-width-hairline" → $type: "dimension"
+"layer-opacity50" → $type: "opacity"
+"font-weight-700" → $type: "fontWeight"
 ```
 
-#### 2️⃣ **Brand-Specific Tokens** - Density & Overrides
+**Value Processing:**
+- Opacity: `5` (Figma %) stays as `5` (converted to `0.05` in transforms)
+- Dimensions: `0.33` → `0.33` (gets `px` in CSS, stays number for iOS)
+- Colors: `#DD0000` → `#DD0000` (converted to UIColor for iOS)
+- FontWeight: `700` → `700` (unitless)
 
-Brand context tokens with multiple modes.
+**Floating-Point Rounding:**
+```javascript
+0.33000001311302185 → 0.33
+rgba(0, 0, 0, 0.699999988079071) → rgba(0, 0, 0, 0.7)
+```
 
-**Density Collection** (3 modes):
-- compact, default, spacious
+#### 3️⃣ **Style Dictionary Transforms** (`dist/`)
 
-**Brand Overrides** (3 brands):
-- BrandTokenMapping: BILD, SportBILD, Advertorial
-- BrandColorMapping: BILD, SportBILD (⚠️ Advertorial has no BrandColorMapping)
+Platform-specific transformations:
 
-**Output:**
-```
-dist/{platform}/brands/{brand}/
-  ├── density/
-  │   ├── density-compact.*
-  │   ├── density-default.*
-  │   └── density-spacious.*
-  └── overrides/
-      ├── brandtokenmapping.*
-      └── brandcolormapping.*  # Only BILD & SportBILD
+**CSS/SCSS/JS:**
+```javascript
+dimension → "8px"
+opacity → 0.05 (from 5)
+color → "#DD0000"
 ```
 
-#### 3️⃣ **Semantic Tokens** - Brand × Mode Matrix
+**iOS Swift:**
+```swift
+dimension → 8 (CGFloat Points)
+opacity → 0.05 (CGFloat)
+color → UIColor(red: 0.867, green: 0, blue: 0, alpha: 1)
+```
 
-Context-specific tokens with brand and mode variations.
+**Flutter:**
+```dart
+dimension → "8px"
+opacity → 0.05
+color → Color(0xFFdd0000)
+```
 
-**BreakpointMode** (4 modes per brand):
-- xs (320px), sm (390px, compact), md (600px), lg (1024px, regular)
+---
 
-**ColorMode** (2 modes per brand):
-- light, dark
+## 📊 Token Transform Reference
+
+### Naming Conventions
+
+| Platform | Convention | Example | Status |
+|----------|-----------|---------|---------|
+| **CSS** | `kebab-case` with `--` | `--text-color-primary` | ✅ |
+| **SCSS** | `kebab-case` with `$` | `$text-color-primary` | ✅ |
+| **JavaScript** | `camelCase` | `textColorPrimary` | ✅ |
+| **iOS Swift** | `PascalCase` | `TextColorPrimary` | ✅ |
+| **Android** | `kebab-case` | `text-color-primary` | ✅ |
+| **Flutter** | `camelCase` | `textColorPrimary` | ✅ |
+
+### Normal Tokens
+
+#### Colors
+
+| Platform | Format | Example | Usage | Ready |
+|----------|--------|---------|-------|-------|
+| **CSS** | `#HEX` / `rgba()` | `#DD0000` | `var(--text-color-primary)` | ✅ |
+| **JavaScript** | `"#HEX"` string | `"#DD0000"` | `backgroundColor: textColorPrimary` | ✅ |
+| **iOS Swift** | `UIColor()` object | `UIColor(red: 0.137, ...)` | `view.backgroundColor = TextColorPrimary` | ✅ |
+| **Flutter** | `Color(0xFF...)` | `Color(0xFF232629)` | `color: textColorPrimary` | ✅ |
+| **Android** | `#hex` resource | `#dd0000` | `@color/text-color-primary` | ✅ |
+
+**Notes:**
+- iOS outputs **UIColor objects**, not strings
+- Flutter uses ARGB format with `0xFF` prefix
+- Transparency values are properly rounded
+
+#### Dimensions (spacing, sizing, borders)
+
+| Platform | Format | Example | Usage | Ready |
+|----------|--------|---------|-------|-------|
+| **CSS** | `Xpx` | `16px`, `0.33px` | `var(--space2x)` | ✅ |
+| **JavaScript** | `"Xpx"` string | `"16px"` | Parsing needed for calculations | ✅⚠️ |
+| **iOS Swift** | `CGFloat` number | `16`, `0.33` | `let padding: CGFloat = Space2x` | ✅ |
+| **Android** | `Xpx` dimen | `16px` | `@dimen/space2x` | ✅ |
+| **Flutter** | `"Xpx"` string | `"16px"` | Parsing: `.replaceAll('px', '')` | ✅⚠️ |
+
+**Notes:**
+- iOS uses **Points** (not pixels), outputs pure `CGFloat` numbers
+- JavaScript/Flutter get strings with "px" - developers parse for calculations
+- Border hairline: `0.33px` properly rounded
+
+#### Opacity
+
+| Platform | Format | Example | Usage | Ready |
+|----------|--------|---------|-------|-------|
+| **CSS** | `0-1` number | `0.5`, `0.05` | `opacity: var(--layer-opacity50)` | ✅ |
+| **JavaScript** | `"0-1"` string | `"0.5"` | `opacity: layerOpacity50` | ✅ |
+| **iOS Swift** | `CGFloat` | `0.5` | `view.alpha = LayerOpacity50` | ✅ |
+| **Flutter** | `double` | `0.05` | `opacity: layerOpacity05` | ✅ |
+| **Android** | `"0-1"` string | `"0.5"` | `android:alpha="@string/layer-opacity50"` | ✅ |
+
+**Notes:**
+- Figma exports opacity as percentage (5, 10, 70)
+- Transform converts to decimal: `5` → `0.05`, `70` → `0.7`
+- All platforms receive proper 0-1 range
+
+#### Font Weight
+
+| Platform | Format | Example | Usage | Ready |
+|----------|--------|---------|-------|-------|
+| **CSS** | unitless integer | `700`, `400` | `font-weight: var(--font-weight-700)` | ✅ |
+| **JavaScript** | number | `700` | `fontWeight: fontWeight700` | ✅ |
+| **iOS Swift** | UIFont.Weight | `.bold`, `.regular` | Mapped from numeric value | ✅ |
+| **Android** | `bold` / `normal` | text style | `android:textStyle="bold"` | ✅ |
+| **Flutter** | FontWeight | `FontWeight.w700` | `fontWeight: FontWeight.w700` | ✅ |
+
+**Notes:**
+- All platforms receive unitless integers
+- iOS maps to UIFont.Weight enums
+- No "px" suffix bug (fixed in preprocessing)
+
+### Composite Tokens
+
+#### Typography
+
+| Platform | Format | Usage | Ready |
+|----------|--------|-------|-------|
+| **CSS** | CSS Classes with data-attributes | `<h1 class="display1" data-brand="bild" data-breakpoint="lg">` | ✅ |
+| **SCSS** | Maps | `$display1: (fontSize: 120px, lineHeight: 120px, ...)` | ✅ |
+| **JavaScript** | Objects | `{fontSize: "120px", lineHeight: "120px", fontWeight: 800}` | ✅ |
+| **iOS Swift** | UIFont instances | `UIFont.TypographyBildregular.display1` | ✅ |
+| **Flutter** | Maps | `{'fontSize': '120px', 'fontWeight': 800, ...}` | ✅ |
+| **Android** | XML styles | `<style name="Display1">...</style>` (sp units) | ✅ |
+
+**Example Outputs:**
 
-**Output:**
+```css
+/* CSS */
+[data-brand="bild"][data-breakpoint="lg"] .display1 {
+  font-family: Gotham;
+  font-weight: 800;
+  font-size: 120px;
+  line-height: 120px;
+  letter-spacing: -2px;
+}
 ```
-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.*
+
+```javascript
+// JavaScript
+export const display1 = {
+  fontFamily: "Gotham",
+  fontWeight: 800,
+  fontSize: "120px",
+  lineHeight: "120px",
+  letterSpacing: "-2px"
+};
 ```
 
-⚠️ **Note**: Advertorial has **no color/ folder** (no BrandColorMapping collection).
+```swift
+// iOS Swift
+UIFont.TypographyBildregular.display1
+// → UIFont(name: "Gotham", size: 120)?.withWeight(.heavy)
+```
 
-#### 4️⃣ **Composite Tokens** - Typography & Effects
+**Notes:**
+- All numeric typography values have `px` units (CSS, JS, Flutter)
+- iOS uses Points (native UIFont size)
+- Android uses `sp` for text sizing
 
-Structured tokens with CSS classes for ready-to-use styles.
+#### Effects / Shadows
 
-**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
+| Platform | Format | Usage | Ready |
+|----------|--------|-------|-------|
+| **CSS** | `box-shadow` | Ready-to-use shadow classes | ✅ |
+| **JavaScript** | Array of objects | `[{offsetX, offsetY, radius, spread, color}]` | ✅ |
+| **iOS Swift** | `[NSShadow]` array | `Effects.Shadowsoftmd` (multiple layers) | ✅ |
+| **Flutter** | `[BoxShadow]` array | Native BoxShadow objects | ✅ |
+| **Android** | Programmatic | Not exported (Android shadows typically in code) | N/A |
 
-**Effects** (2 color modes per brand):
-- 3 brands × 2 color modes = **6 outputs**
-- CSS: Shadow and blur effect classes
-- All platforms: Effect token objects
+**Example Outputs:**
 
-**Output:**
-```
-dist/{platform}/brands/{brand}/semantic/
-  ├── typography/
-  │   ├── typography-xs.*
-  │   ├── typography-sm.*
-  │   ├── typography-md.*
-  │   └── typography-lg.*
-  └── effects/
-      ├── effects-light.*
-      └── effects-dark.*
+```css
+/* CSS */
+.shadowsoftmd {
+  box-shadow: 0px 2px 16px 0px rgba(0, 0, 0, 0.03),
+              0px 4px 12px 0px rgba(0, 0, 0, 0.07);
+}
 ```
 
-**iOS/Android Size Classes:**
+```javascript
+// JavaScript
+export const shadowsoftmd = [
+  { offsetX: 0, offsetY: 2, radius: 16, spread: 0, color: "rgba(0, 0, 0, 0.03)" },
+  { offsetX: 0, offsetY: 4, radius: 12, spread: 0, color: "rgba(0, 0, 0, 0.07)" }
+];
 ```
-dist/ios/brands/{brand}/
-  ├── sizeclass-compact/    # sm breakpoint
-  │   └── Typography.swift
-  └── sizeclass-regular/    # lg breakpoint
-      └── Typography.swift
 
-dist/android/brands/{brand}/
-  ├── sizeclass-compact/    # sm breakpoint
-  │   └── typography_styles.xml
-  └── sizeclass-regular/    # lg breakpoint
-      └── typography_styles.xml
+```swift
+// iOS Swift
+public static let Shadowsoftmd: [NSShadow] = [
+  NSShadow(offset: CGSize(width: 0, height: 2), blurRadius: 16,
+           color: UIColor(red: 0, green: 0, blue: 0, alpha: 0.03))
+  // ...
+]
 ```
 
 ---
 
-## 📁 Output Structure
+## 🔗 Figma Integration & Dependencies
 
-### Platform Overview
+### Figma Variables Requirements
 
-```
-dist/
-├── manifest.json                    # Build metadata
-│
-├── css/                            # CSS Custom Properties
-│   ├── shared/                     # Primitives (no brand context)
-│   └── brands/
-│       ├── bild/
-│       ├── sportbild/
-│       └── advertorial/
-│
-├── scss/                           # SCSS Variables (same structure)
-├── js/                             # JavaScript ES6 Modules (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)
-```
-
-### Brand Directory Structure
-
-Each brand contains:
+The pipeline expects Figma Variables with the following structure:
 
 ```
-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)
+Variables:
+├── Collections (e.g., "ColorMode", "BreakpointMode", "Density")
+│   └── Modes (e.g., "light", "dark", "xs", "sm", "md", "lg")
+└── Variables
+    ├── name: "Semantic/LayerOpacity/layerOpacity05" OR "Component/Button/buttonPrimaryBgColor"
+    ├── resolvedType: "FLOAT" | "COLOR" | "STRING" | "BOOLEAN"
+    ├── scopes: ["OPACITY"] | ["WIDTH_HEIGHT"] | ["FONT_SIZE"] | etc.
+    └── valuesByMode: { "mode-id": value | alias }
 ```
 
-⚠️ **Advertorial Exception**: No `color/` folder (no BrandColorMapping)
+**Token Path Patterns:**
+- **Semantic Tokens**: `Semantic/Category/tokenName` → Organized in `semantic/` folders
+- **Component Tokens**: `Component/ComponentName/tokenName` → Organized in `components/ComponentName/` folders
+- **Primitive Tokens**: `ColorPrimitive/colorName` → Organized in `shared/` folder
 
----
+### Supported Figma Scopes
 
-## 🎨 Platform Usage
+The pipeline uses Figma scopes to determine token types semantically:
 
-### CSS
+| Scope | Assigned Type | Output Format | Example |
+|-------|---------------|---------------|---------|
+| `OPACITY` | `opacity` | 0-1 decimal (÷100) | `5` → `0.05` |
+| `WIDTH_HEIGHT` | `dimension` | px (CSS/Android), CGFloat (iOS) | `16` → `16px` / `16` |
+| `GAP` | `dimension` | Same as WIDTH_HEIGHT | `8` → `8px` / `8` |
+| `STROKE_FLOAT` | `dimension` | Same as WIDTH_HEIGHT | `0.33` → `0.33px` / `0.33` |
+| `CORNER_RADIUS` | `dimension` | Same as WIDTH_HEIGHT | `4` → `4px` / `4` |
+| `FONT_SIZE` | `fontSize` | px with transform | `40` → `40px` |
+| `LINE_HEIGHT` | `dimension` | Always px (per requirement) | `48` → `48px` |
+| `LETTER_SPACING` | `dimension` | px with transform | `-0.5` → `-0.5px` |
+| `FONT_WEIGHT` | `fontWeight` | Unitless integer | `700` → `700` |
 
-```css
-/* Import brand-specific tokens */
-@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';
+### Component Tokens Organization
 
-/* Use CSS custom properties */
-.button {
-  background-color: var(--bild-red-bild-red);  /* #DD0000 */
-  font-family: var(--font-family-bild-font-family-gotham-cond);
-}
+Component tokens are automatically detected and organized by the preprocessing pipeline:
 
-/* Use ready-made typography classes */
-<h1 class="headline1">Headline</h1>
+**Detection Logic:**
+```javascript
+// Any token starting with "Component/" is a component token
+Component/Button/Primary/buttonPrimaryBgColor  → Component Token
+Component/Inputfield/inputBorderWidth           → Component Token
+Semantic/TextColor/textColorPrimary             → Semantic Token
 ```
 
-### SCSS
-
-```scss
-// Import brand-specific tokens
-@import '@marioschmidt/design-system-tokens/scss/brands/bild/semantic/color/colormode-light';
-
-.button {
-  background-color: $bild-red-bild-red;  // #DD0000
-  padding: $space-primitive-space2x;
-}
+**Automatic Organization:**
 ```
-
-### JavaScript/TypeScript
-
-```javascript
-// Import brand-specific tokens
-import tokens from '@marioschmidt/design-system-tokens/js/brands/bild/semantic/color/colormode-light.js';
-
-console.log(tokens.BildRedBildRed);  // "#dd0000"
-
-// React/Styled Components
-const Button = styled.button`
-  background-color: ${tokens.BildRedBildRed};
-`;
+Component Tokens in Figma:
+├── Component/Button/buttonPrimaryBgColor
+├── Component/Button/buttonPrimaryTextColor
+├── Component/Alert/alertBorderWidth
+└── Component/Alert/alertShadow
+
+Generated Output Structure:
+dist/css/brands/bild/components/
+├── Button/
+│   ├── colormode-light.css    (color tokens for Button)
+│   ├── density-default.css    (density tokens for Button)
+│   └── breakpoints.css        (breakpoint tokens for Button)
+└── Alert/
+    ├── colormode-light.css
+    └── effects-light.css      (shadow/effect tokens for Alert)
 ```
 
-### JSON
+**Collection-Based Routing:**
+- **ColorMode collection** → `components/{ComponentName}/colormode-{mode}.css`
+- **Density collection** → `components/{ComponentName}/density-{mode}.css`
+- **BreakpointMode collection** → `components/{ComponentName}/breakpoints.css`
+- **BrandTokenMapping/BrandColorMapping** → `components/{ComponentName}/overrides/`
 
-```javascript
-// Import structured token data
-import tokens from '@marioschmidt/design-system-tokens/json/brands/bild/semantic/color/colormode-light.json';
-
-console.log(tokens);
-// {
-//   "BildRed": {
-//     "bildRed": {
-//       "$type": "color",
-//       "$value": "#DD0000",
-//       "type": "color",
-//       "value": "#DD0000"
-//     }
-//   }
-// }
+**Composite Component Tokens:**
 ```
+Typography:
+  Component/Button/buttonLabelStyle → dist/.../components/Button/typography-{breakpoint}.css
 
-### iOS (Swift)
-
-```swift
-// Import brand-specific tokens
-import DesignTokens
-
-// Use color tokens
-let primaryColor = Colorprimitive.bildRedBildRed  // UIColor
-
-// Use typography (size class aware)
-let typography = Typography.headline1  // Typography struct
+Effects:
+  Component/Alert/alertShadowDown → dist/.../components/Alert/effects-{colormode}.css
 ```
 
-### Android (XML)
+**Key Benefits:**
+- ✅ Automatic component isolation (Button tokens separate from Alert tokens)
+- ✅ Brand × Mode matrix applied to component tokens
+- ✅ ~917 component token files across all platforms
+- ✅ Clear separation: `semantic/` vs `components/` folders
 
-```xml
-<!-- Import brand-specific colors -->
-<resources>
-    <color name="bild_red_bild_red">#DD0000</color>
-    <dimen name="space_2x">16dp</dimen>
+### What is Stable (✅ Safe Changes)
 
-    <!-- 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>
+#### ✅ Creating New Tokens
+```
+Action: Add new variable in Figma
+Result: Automatically included in next export
+Pipeline: Preprocesses and builds for all platforms
+Risk: None
 ```
 
-### Flutter (Dart)
+#### ✅ Editing Token Values
+```
+Action: Change color from #DD0000 to #FF0000
+Result: Value updated in next export
+Pipeline: All platforms get new value
+Risk: None
+```
 
-```dart
-// Import brand-specific tokens
-import 'package:design_tokens/brands/bild/semantic/color/colormode_light.dart';
+#### ✅ Creating/Editing Aliases
+```
+Action: Reference another variable
+Export: { "type": "VARIABLE_ALIAS", "id": "VariableID:123" }
+Pipeline: Alias resolved to final value in preprocessing
+Risk: None (circular references detected and warned)
+```
 
-// Use color tokens
-final primaryColor = Colorprimitive.bildRedBildRed;  // Color
+#### ✅ Adding Scopes to Tokens
+```
+Action: Assign "OPACITY" scope in Figma
+Result: Pipeline uses scope for type determination
+Pipeline: Automatic unit assignment based on scope
+Risk: None (improves type detection)
+```
 
-// Use typography tokens
-final headline1 = Typography.headline1;  // TypographyToken
+#### ✅ Changing Token Names
+```
+Action: Rename "oldName" → "newName"
+Result: New name used in all platforms
+Pipeline: Name transforms applied per platform
+Risk: Breaking change for consumers (semantic versioning bump)
 ```
 
----
+#### ✅ Adding New Modes
+```
+Action: Add new breakpoint "xl"
+Result: New mode exports with variables
+Pipeline: Builds new token files for mode
+Risk: None (additive change)
+```
 
-## 🔧 Development
+#### ✅ Creating Component Tokens
+```
+Action: Add "Component/Button/buttonPrimaryBgColor" in Figma
+Result: Automatically detected as component token
+Pipeline: Organized in dist/.../components/Button/ folder
+Risk: None
+Note: Component name extracted from path (2nd segment: "Button")
+```
 
-### Project Structure
+#### ✅ Creating New Components
+```
+Action: Add first token "Component/Card/cardBgColor"
+Result: New component folder created automatically
+Pipeline: dist/.../components/Card/ folder generated
+Risk: None (additive change)
+Note: ~917 component token files currently in pipeline
+```
 
+#### ✅ Adding Component Typography/Effects
 ```
-.
-├── src/
-│   └── design-tokens/
-│       └── bild-design-system-raw-data.json    # Custom Figma Plugin export (raw data)
-│
-├── scripts/
-│   ├── 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
-│       • Composite token support (Typography, Effects)
-│       • Size class mapping for iOS/Android
-│
-├── build-config/
-│   └── style-dictionary.config.js              # Custom transforms & formats
-│       • CSS typography classes format
-│       • CSS effect classes format
-│       • iOS Swift typography format
-│       • Android typography XML format
-│
-├── tokens/                                     # Intermediate files (tracked in Git)
-│   ├── shared/                                 # Primitives (4 files)
-│   └── brands/                                 # Brand-specific (64 files)
-│       ├── bild/
-│       ├── sportbild/
-│       └── advertorial/
-│   📝 Purpose: Preprocessed Style Dictionary format
-│   ✅ Aliases resolved, bugs fixed, ready for SD build
-│
-├── dist/                                       # Build artifacts (NOT in Git)
-│   ├── css/, scss/, js/, json/                 # Web platforms
-│   ├── ios/, android/, flutter/                # Native platforms
-│   └── manifest.json                           # Build metadata
-│   📝 Generated locally or in CI/CD
-│   ⬇️ Available as GitHub Actions artifacts (30 days)
-│
-└── README.md
+Action: Add textStyle "Component/Button/buttonLabelStyle"
+Result: Treated as composite component token
+Pipeline: Generated in components/Button/typography-{breakpoint}.css
+Risk: None
+Note: Component typography/effects separated from semantic styles
 ```
 
-### Token Processing Pipeline
-
-The token transformation happens in three stages:
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ 1️⃣ Figma Export (Raw Data)                                      │
-│    src/design-tokens/bild-design-system-raw-data.json           │
-│    • Figma Variable Visualizer plugin export                    │
-│    • Contains aliases: {type: "VARIABLE_ALIAS", id: "..."}      │
-│    • FontWeight bugs: "700px" instead of 700                    │
-│    • Complex Collections & Modes structure                      │
-└─────────────────────────────────────────────────────────────────┘
-                              ↓
-┌─────────────────────────────────────────────────────────────────┐
-│ 2️⃣ Preprocessing (Intermediate Format)                          │
-│    tokens/                                                       │
-│    • All aliases resolved to final values                       │
-│    • FontWeight bugs fixed                                      │
-│    • Organized by Brand × Mode × Collection                     │
-│    • Style Dictionary format: {"$value": "...", "$type": "..."} │
-│    • 68 JSON files (4 shared + 64 brand-specific)               │
-└─────────────────────────────────────────────────────────────────┘
-                              ↓
-┌─────────────────────────────────────────────────────────────────┐
-│ 3️⃣ Style Dictionary Build (Platform Outputs)                    │
-│    dist/                                                         │
-│    • 7 platforms: CSS, SCSS, JS, JSON, iOS, Android, Flutter    │
-│    • 52 total builds (4 shared + 30 brand + 12 typo + 6 fx)     │
-│    • Ready-to-use platform-specific formats                     │
-│    • NOT tracked in Git (available as CI artifacts)             │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Why the `tokens/` Intermediate Step?
-
-**Problem:** Figma export format is not directly usable by Style Dictionary:
-- ❌ Aliases like `{type: "VARIABLE_ALIAS", id: "VariableID:123"}`
-- ❌ Complex Collections & Modes structure
-- ❌ Bugs like `"700px"` for FontWeight
-
-**Solution:** Preprocessing creates clean Style Dictionary input:
-- ✅ All aliases resolved: `{"$value": "#DD0000", "$type": "color"}`
-- ✅ Bugs fixed: `700` (not `"700px"`)
-- ✅ Organized structure ready for multi-platform build
-
-**Example:**
+### What is NOT Stable (⚠️ Pipeline Breaks)
 
-```javascript
-// BEFORE (Figma raw data - src/design-tokens/)
-{
-  "variables": [{
-    "name": "Component/Background",
-    "valuesByMode": {
-      "mode123": { "type": "VARIABLE_ALIAS", "id": "VariableID:456" }
-    }
-  }]
-}
+#### ⚠️ Deleting Collections
+```
+Action: Delete "ColorMode" collection in Figma
+Result: All variables in collection missing
+Pipeline: ❌ Preprocessing fails (missing collection)
+Risk: HIGH - Pipeline breaks
+Fix: Restore collection or update preprocessing code
+```
 
-// AFTER (Preprocessed - tokens/)
-{
-  "Component": {
-    "Background": {
-      "$value": "#DD0000",
-      "$type": "color"
-    }
-  }
-}
+#### ⚠️ Renaming Collections
+```
+Action: Rename "ColorMode" → "ThemeMode"
+Result: Preprocessing looks for old name
+Pipeline: ⚠️ Collection not found, tokens skipped
+Risk: MEDIUM - Tokens not built
+Fix: Update collection name in preprocess-plugin-tokens.js
+```
 
-// FINAL (Build output - dist/)
-// CSS: --component-background: #DD0000;
-// SCSS: $component-background: #DD0000;
-// JS: export const ComponentBackground = "#DD0000";
+#### ⚠️ Deleting Modes (Used by Tokens)
+```
+Action: Delete "dark" mode from ColorMode
+Result: Variables with dark values orphaned
+Pipeline: ⚠️ Mode not found for affected tokens
+Risk: MEDIUM - Some tokens missing
+Fix: Ensure modes exist or remove unused mode references
 ```
 
-### Custom Figma Plugin Export
+#### ⚠️ Changing Mode Names
+```
+Action: Rename mode "light" → "bright"
+Result: Preprocessing matches by name
+Pipeline: ⚠️ May not find renamed mode
+Risk: LOW-MEDIUM - Context-dependent
+Fix: Preprocessing uses name matching (usually handles this)
+Note: Mode IDs can change, names are matched
+```
 
-The pipeline expects a JSON export from a custom Figma plugin with the following structure:
+#### ⚠️ Removing Scopes from Critical Tokens
+```
+Action: Remove "OPACITY" scope from opacity tokens
+Result: Falls back to name-based detection
+Pipeline: ⚠️ May misdetect type if name unclear
+Risk: LOW - Fallback usually works
+Fix: Either restore scope or ensure clear token name
+```
 
-```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:..." }
-      }
-    }
-  ]
-}
+#### ❌ Circular Alias References
+```
+Action: TokenA → TokenB → TokenA
+Result: Infinite loop in alias resolution
+Pipeline: ⚠️ Detected and logged, token marked "UNRESOLVED"
+Risk: LOW - Detected but token unusable
+Fix: Break circular reference in Figma
 ```
 
-**Export Location**: `src/design-tokens/bild-design-system-raw-data.json`
+#### ⚠️ Renaming Component in Token Path
+```
+Action: Rename "Component/Button/..." → "Component/Btn/..."
+Result: Component name extracted from path changes
+Pipeline: ✅ Builds successfully but in different folder
+Risk: MEDIUM - Breaking change for consumers
+Impact: Old path: components/Button/, New path: components/Btn/
+Fix: Consumer code must update import paths
+Note: Semantic versioning major bump required
+```
 
-### Development Workflow
+#### ⚠️ Moving Token Between Component/Semantic
+```
+Action: "Component/Button/bgColor" → "Semantic/Button/bgColor"
+Result: Token moves from components/ to semantic/ folder
+Pipeline: ✅ Builds successfully in new location
+Risk: MEDIUM - Breaking change for consumers
+Impact: Import path changes from components/ to semantic/
+Fix: Consumer code must update import paths
+Note: Pipeline detects by "Component/" prefix
+```
 
-#### Local Development
+#### ⚠️ Invalid Component Token Paths
+```
+Action: Create token "Component/buttonBgColor" (only 2 segments)
+Result: Missing component name in path
+Pipeline: ⚠️ Token skipped or misprocessed
+Risk: LOW - Validation catches most cases
+Fix: Use proper path: "Component/{ComponentName}/{tokenName}"
+Note: Minimum 3 path segments required for component tokens
+```
 
-1. **Export from Figma**
-   - Use custom Figma plugin (Variable Visualizer)
-   - Configure target branch: `figma-tokens` (recommended)
-   - Export as `bild-design-system-raw-data.json`
-
-2. **Figma Plugin Push**
-   - Plugin automatically pushes to configured branch
-   - ✅ **Recommended**: Push to `figma-tokens` branch
-   - Creates automatic Pull Request with build artifacts
-
-3. **Local Build (Optional)**
-   ```bash
-   # Full build (preprocessing + build)
-   npm run build
-
-   # Or run steps separately:
-   npm run preprocess    # Step 1: Resolve aliases, fix bugs
-   npm run build:tokens  # Step 2: Generate platform outputs
-   ```
-   - Resolves all aliases to final values
-   - Creates intermediate files in `tokens/` (68 files)
-   - Transforms to all 7 platforms in `dist/` (353 files)
-   - **52/52 builds successful**
-
-4. **Verify Locally**
-   ```bash
-   # Check brand-specific values
-   grep "bild-red" dist/css/brands/bild/semantic/color/colormode-light.css
-   grep "bild-red" dist/css/brands/sportbild/semantic/color/colormode-light.css
-
-   # 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
-   ```
-
-#### Figma Export Target Branches
-
-| Target Branch | Build Runs | PR Created | NPM Publish | Use Case |
-|---------------|------------|------------|-------------|----------|
-| **figma-tokens** | ✅ Yes | ✅ Automatic | ✅ After merge | **Recommended** - Full workflow with review |
-| **main** | ✅ Yes | ❌ No | ✅ **Immediate** | ⚠️ Direct publish without review |
-| **claude/*** | ✅ Yes | ❌ Manual | ❌ No | Development/Testing |
-| **other** | ❌ No | ❌ No | ❌ No | Not configured |
-
-**Best Practice:** Always export to `figma-tokens` branch for automatic PR creation and review before publishing.
+### Pipeline Stability Matrix
+
+| Change Type | Detection | Impact | Auto-Recovery | Fix Required |
+|-------------|-----------|--------|---------------|--------------|
+| New token | ✅ Auto | ➕ Added | ✅ Yes | ❌ No |
+| Edit value | ✅ Auto | 🔄 Updated | ✅ Yes | ❌ No |
+| Edit alias | ✅ Auto | 🔄 Resolved | ✅ Yes | ❌ No |
+| Add scope | ✅ Auto | ✨ Better typing | ✅ Yes | ❌ No |
+| Rename token | ✅ Auto | 🔄 Name updated | ✅ Yes | ⚠️ Consumer breaking |
+| Add mode | ✅ Auto | ➕ New outputs | ✅ Yes | ❌ No |
+| Delete collection | ❌ Error | ❌ Build fails | ❌ No | ✅ Code update |
+| Rename collection | ⚠️ Warning | ⚠️ Tokens skipped | ❌ No | ✅ Code update |
+| Delete mode | ⚠️ Warning | ⚠️ Some tokens skip | ⚠️ Partial | ⚠️ Check references |
+| Rename mode | ⚠️ Warning | ⚠️ May not match | ⚠️ Usually | ⚠️ Check matching |
+| Remove scope | ⚠️ Warning | ⚠️ Fallback to name | ⚠️ Usually | ⚠️ Check type |
+| Circular alias | ⚠️ Warning | ⚠️ Token unresolved | ❌ No | ✅ Fix in Figma |
+| **New component token** | ✅ Auto | ➕ Component folder | ✅ Yes | ❌ No |
+| **New component** | ✅ Auto | ➕ Folder created | ✅ Yes | ❌ No |
+| **Component typography/effects** | ✅ Auto | ➕ Composite output | ✅ Yes | ❌ No |
+| **Rename component in path** | ✅ Auto | 🔄 Folder renamed | ✅ Yes | ⚠️ Consumer breaking |
+| **Move Component↔Semantic** | ✅ Auto | 🔄 Folder changed | ✅ Yes | ⚠️ Consumer breaking |
+| **Invalid component path** | ⚠️ Warning | ⚠️ Token skipped | ❌ No | ✅ Fix path in Figma |
+
+### Best Practices
+
+**DO:**
+- ✅ Use Figma scopes for all tokens (better type detection)
+- ✅ Use clear, semantic token names
+- ✅ Test exports in `figma-tokens` branch before merging
+- ✅ Review CI build artifacts before publishing
+- ✅ Use aliases for design tokens (single source of truth)
+- ✅ Use proper component paths: `Component/{ComponentName}/{tokenName}` (min 3 segments)
+- ✅ Organize by component in Figma (Button, Alert, Card, etc.)
+- ✅ Use consistent component naming (PascalCase recommended)
+
+**DON'T:**
+- ❌ Delete collections without updating preprocessing code
+- ❌ Create circular alias references
+- ❌ Use ambiguous token names without scopes
+- ❌ Push directly to `main` without review
+- ❌ Manually edit generated files in `dist/`
+- ❌ Use invalid component paths like `Component/tokenName` (too few segments)
+- ❌ Rename component folders in Figma without coordinating with consumers
+- ❌ Mix component and semantic tokens in same path structure
 
 ---
 
-## 🔄 CI/CD Integration
-
-### Overview
+## 📦 Installation
 
-The CI/CD pipeline uses **GitHub Actions Artifacts** for distributing build outputs. The `dist/` folder is **NOT tracked in Git** - instead, it's generated in CI and made available for download.
+### Prerequisites
 
-**Key Benefits:**
-- ✅ No merge conflicts on generated files
-- ✅ Clean Git history (only source files)
-- ✅ PR review via downloadable artifacts
-- ✅ 30-day artifact retention
+- Node.js >= 20.x
+- npm >= 10.x
 
----
+### Setup
 
-### GitHub Actions Workflows
+```bash
+# Clone repository
+git clone https://github.com/UXWizard25/vv-token-test-v3.git
+cd vv-token-test-v3
 
-#### 1. 🔨 Build Tokens (`.github/workflows/build-tokens.yml`)
+# Install dependencies
+npm install
 
-**Purpose:** Validates token builds and creates downloadable artifacts for PR review.
+# Build tokens
+npm run build
+```
 
-**Triggers:**
-- Push to `main`, `develop`, `claude/**`, `figma-tokens` branches
-- Pull requests to `main` branch
-- Changes in `src/design-tokens/`, `scripts/`, `build-config/`
-- Manual workflow dispatch
+### NPM Package Installation
 
-**Workflow Steps:**
-```
-1. Checkout repository
-   ↓
-2. Setup Node.js 20 + Install dependencies
-   ↓
-3. Run npm run build (preprocessing + build)
-   ↓
-4. Upload artifacts (dist/, tokens/, logs)
-   ↓
-5. Comment on PR with download link (if PR)
-   ↓
-6. Create build summary
+```bash
+npm install @marioschmidt/design-system-tokens
 ```
 
-**Outputs:**
-- ✅ Validates build success: 52/52 builds
-- 📦 Creates artifact: `design-tokens-{sha}.zip` (30 days)
-- 💬 PR comment with download link (on pull requests)
-- 📊 Build summary in Actions UI
+---
 
-**Artifact Contents:**
-```
-design-tokens-{sha}.zip
-├── dist/                    # All platform outputs (353 files)
-│   ├── css/, scss/, js/, json/
-│   ├── ios/, android/, flutter/
-│   └── manifest.json
-├── tokens/                  # Intermediate files (68 files)
-└── build-output.log         # Build logs
-```
+## 🚀 Quick Start
 
-**PR Comment Example:**
-```markdown
-## 🎨 Design Tokens Build erfolgreich!
+### Build Commands
 
-**Build Statistiken:**
-- ✅ Successful Builds: 52/52
-- 📦 Commit: `abc123`
-- 🌲 Branch: `feature-branch`
+```bash
+# Full build (preprocessing + platform builds)
+npm run build
 
-### 📥 Review der generierten Files:
+# Or run steps separately:
+npm run preprocess     # Figma JSON → Style Dictionary format
+npm run build:tokens   # Style Dictionary → 7 platforms
+npm run build:bundles  # Generate CSS bundle files
 
-[⬇️ **Download Build Artifacts**](https://github.com/.../actions/runs/123456)
+# Development watch mode
+npm run watch
 
-**Enthalten:**
-- `dist/css/` - CSS Custom Properties
-- `dist/scss/` - SCSS Variables
-- `dist/js/` - JavaScript ES6
-- `dist/json/` - JSON Data
-- `dist/ios/` - Swift Classes
-- `dist/android/` - Android XML
-- `dist/flutter/` - Flutter Dart
+# Clean generated files
+npm run clean
+```
 
-📊 Datei-Statistiken
-- Total Files: 353
-- CSS Files: 88
-- SCSS Files: 88
-...
+### Build Output
 
-💡 **Tipp:** Die Artifacts sind 30 Tage verfügbar.
+```
+✨ Build completed!
+
+📊 Statistics:
+   - Shared Primitives: 4/4
+   - Brand-specific Tokens: 30/30
+   - Component Tokens: 917/917
+   - Typography Builds: 12/12
+   - Effect Builds: 6/6
+   - Builds successful: 969/969
 ```
 
 ---
 
-#### 2. 🤖 Auto PR from Figma (`.github/workflows/auto-pr-from-figma.yml`)
+## 🎨 Platform Usage Examples
 
-**Purpose:** Automatically creates/updates a Pull Request when Figma exports tokens.
+### CSS
 
-**Trigger:**
-- Push to `figma-tokens` branch (from Figma plugin)
+```css
+/* Import tokens */
+@import '@marioschmidt/design-system-tokens/css/brands/bild/semantic/color/colormode-light.css';
 
-**Recommended Figma Plugin Configuration:**
-```javascript
-{
-  "targetBranch": "figma-tokens",
-  "repository": "UXWizard25/vv-token-test-v3",
-  "filePath": "src/design-tokens/bild-design-system-raw-data.json"
+/* Use variables */
+.button {
+  background-color: var(--text-color-accent-constant);  /* #DD0000 */
+  padding: var(--space2x);  /* 16px */
+  opacity: var(--layer-opacity50);  /* 0.5 */
+  border-width: var(--border-width-hairline);  /* 0.33px */
 }
-```
 
-**Complete Workflow:**
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 1. Figma Plugin Export                                      │
-│    • Designer clicks "Export" in Figma                      │
-│    • Plugin pushes JSON to figma-tokens branch              │
-└─────────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────────┐
-│ 2. Workflow Triggers                                        │
-│    • auto-pr-from-figma.yml starts                          │
-│    • Runs npm run build (52/52 builds)                      │
-│    • Uploads artifacts (design-tokens-{sha}.zip)            │
-└─────────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────────┐
-│ 3. Pull Request Created                                     │
-│    • Title: "🎨 Update design tokens from Figma"            │
-│    • Body: Build stats + artifact download link            │
-│    • Compares figma-tokens → main                           │
-└─────────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────────┐
-│ 4. Review Process                                           │
-│    • Team reviews source changes (JSON diff)                │
-│    • Downloads artifacts to verify outputs                  │
-│    • Checks CSS, SCSS, platform-specific files              │
-└─────────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────────┐
-│ 5. Merge to main                                            │
-│    • PR approved and merged                                 │
-│    • publish-on-merge.yml triggers                          │
-└─────────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────────┐
-│ 6. NPM Package Published                                    │
-│    • Fresh dist/ build                                      │
-│    • Version bump (patch)                                   │
-│    • Published to npm registry                              │
-│    • GitHub Release created                                 │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**PR Body Format:**
-```markdown
-## 🎨 Design Token Update
-
-This PR contains updated design tokens from Figma Variable Visualizer.
-
-### ✅ Build Results
-- **Build Status:** Success
-- **Successful Builds:** 52/52
-- **Warnings:** 0
-
-### 📥 Review Generated Files
-[⬇️ **Download Build Artifacts**](https://github.com/.../actions/runs/123)
-
-The generated `dist/` files are available as build artifacts (30 days retention).
-
-### 📝 Changed Files
-**Files Changed:** 1
-- src/design-tokens/bild-design-system-raw-data.json
-
-### 🚀 What Happens After Merge?
-1. ✅ Tokens will be rebuilt
-2. ✅ Package version will be bumped (patch)
-3. ✅ Package will be published to npm
-4. ✅ GitHub Release will be created
-```
+/* Use typography classes */
+<h1 class="display1" data-brand="bild" data-breakpoint="lg">Headline</h1>
 
----
+/* Use shadow classes */
+<div class="shadowsoftmd" data-brand="bild" data-theme="light">Card</div>
+```
 
-#### 3. 📦 Publish on Merge (`.github/workflows/publish-on-merge.yml`)
+### JavaScript / React
 
-**Purpose:** Automatically publishes package to npm when PR is merged to main.
+```javascript
+import {
+  textColorPrimary,
+  space2x,
+  layerOpacity50
+} from '@marioschmidt/design-system-tokens/js/brands/bild/semantic/color/colormode-light';
 
-**Trigger:**
-- Push to `main` branch
-- Changes in `src/design-tokens/`, `scripts/`, `build-config/`, `package.json`
+import { display1 } from '@marioschmidt/design-system-tokens/js/brands/bild/semantic/typography/typography-lg';
 
-**Steps:**
-1. Rebuild tokens (fresh dist/)
-2. Bump version (patch)
-3. Publish to npm
-4. Create GitHub Release
-5. Tag with version
+// Use in styled components
+const Button = styled.button`
+  background-color: ${textColorPrimary};  // "#232629"
+  padding: ${space2x};  // "16px"
+  opacity: ${layerOpacity50};  // "0.5"
+`;
 
----
+// Use typography
+const Headline = styled.h1`
+  font-family: ${display1.fontFamily};  // "Gotham"
+  font-size: ${display1.fontSize};  // "120px"
+  font-weight: ${display1.fontWeight};  // 800
+`;
+```
 
-### Workflow Comparison
+### iOS Swift (UIKit / SwiftUI)
 
-| Workflow | Trigger | Builds dist/ | Commits dist/ | Creates PR | Publishes NPM |
-|----------|---------|--------------|---------------|------------|---------------|
-| **build-tokens.yml** | Push/PR to tracked branches | ✅ Yes | ❌ No (artifacts only) | ❌ No | ❌ No |
-| **auto-pr-from-figma.yml** | Push to `figma-tokens` | ✅ Yes | ❌ No (artifacts only) | ✅ Yes | ❌ No |
-| **publish-on-merge.yml** | Merge to `main` | ✅ Yes (fresh) | ❌ No | ❌ No | ✅ Yes |
+```swift
+import UIKit
 
----
+// Colors (UIColor objects, not strings!)
+view.backgroundColor = StyleDictionary.TextColorPrimary
+// → UIColor(red: 0.137, green: 0.149, blue: 0.161, alpha: 1)
 
-### Manual Workflow Dispatch
+button.setTitleColor(StyleDictionary.TextColorAccentConstant, for: .normal)
+// → UIColor(red: 0.867, green: 0, blue: 0, alpha: 1)
 
-**Via GitHub UI:**
-1. Go to **Actions** tab
-2. Select **"Build Design Tokens"**
-3. Click **"Run workflow"**
-4. Download artifacts from run details
+// Dimensions (CGFloat Points, not "Xpx" strings!)
+let padding: CGFloat = StyleDictionary.Space2x  // 16 (Points)
+let borderWidth: CGFloat = StyleDictionary.BorderWidthHairline  // 0.33
 
-**Via GitHub CLI:**
-```bash
-# Trigger build
-gh workflow run build-tokens.yml
+// Opacity (CGFloat)
+view.alpha = StyleDictionary.LayerOpacity50  // 0.5
 
-# List recent runs
-gh run list --workflow=build-tokens.yml
+// Typography (UIFont instances)
+label.font = UIFont.TypographyBildregular.display1
+// → UIFont(name: "Gotham", size: 120)?.withWeight(.heavy)
 
-# Download artifacts from specific run
-gh run download <run-id>
+// Effects (NSShadow arrays)
+view.layer.shadowColor = Effects.Shadowsoftmd[0].shadowColor
+view.layer.shadowOffset = Effects.Shadowsoftmd[0].shadowOffset
+view.layer.shadowRadius = Effects.Shadowsoftmd[0].shadowBlurRadius
 ```
 
----
+### Flutter
 
-### Reviewing Build Artifacts
+```dart
+import 'package:design_tokens/brands/bild/semantic/color/colormode_light.dart';
+import 'package:design_tokens/brands/bild/semantic/typography/typography_lg.dart';
+
+// Colors (native Color objects)
+Container(
+  color: Colors.textColorPrimary,  // Color(0xFF232629)
+  child: Text(
+    'Headline',
+    style: TextStyle(
+      fontFamily: TypographyBildLg.display1['fontFamily'],  // 'Gotham'
+      fontSize: double.parse(
+        TypographyBildLg.display1['fontSize'].replaceAll('px', '')
+      ),  // 120.0
+      fontWeight: FontWeight.w${TypographyBildLg.display1['fontWeight']},
+    ),
+  ),
+)
+
+// Shadows (BoxShadow arrays)
+Container(
+  decoration: BoxDecoration(
+    boxShadow: EffectsLight.shadowsoftmd,  // [BoxShadow(...), ...]
+  ),
+)
+```
 
-**Method 1: Via PR Comment Link**
-1. Open Pull Request
-2. Find bot comment "🎨 Design Tokens Build erfolgreich!"
-3. Click "Download Build Artifacts"
-4. Extract ZIP and review files locally
+### Android XML
 
-**Method 2: Via Actions Tab**
-1. Go to repository Actions tab
-2. Click on workflow run
-3. Scroll to "Artifacts" section
-4. Download `design-tokens-{sha}.zip`
+```xml
+<!-- Colors -->
+<TextView
+    android:textColor="@color/text-color-primary"
+    android:background="@color/surface-color-primary" />
+
+<!-- Dimensions -->
+<View
+    android:padding="@dimen/space2x"
+    android:layout_width="@dimen/size80x" />
+
+<!-- Typography Styles -->
+<TextView
+    style="@style/Display1"
+    android:text="Headline" />
+```
 
-**Method 3: Via GitHub CLI**
-```bash
-# List artifacts for a run
-gh run view <run-id>
+### SCSS
 
-# Download all artifacts
-gh run download <run-id>
+```scss
+@import '@marioschmidt/design-system-tokens/scss/brands/bild/semantic/color/colormode-light';
+@import '@marioschmidt/design-system-tokens/scss/brands/bild/semantic/typography/typography-lg';
+
+.button {
+  background-color: $text-color-accent-constant;  // #DD0000
+  padding: $space2x;  // 16px
+  opacity: $layer-opacity50;  // 0.5
+}
 
-# Extract and review
-unzip design-tokens-*.zip
-ls dist/
+.headline {
+  font-family: map-get($display1, 'fontFamily');  // Gotham
+  font-size: map-get($display1, 'fontSize');  // 120px
+  font-weight: map-get($display1, 'fontWeight');  // 800
+}
 ```
 
 ---
 
-### Branch Protection & Artifact Workflow
+## 📁 Output Structure
 
-**Why dist/ is not in Git:**
-- Generated files cause merge conflicts (353 files × multiple developers)
-- Unnecessary repository bloat (~15 MB per commit)
-- Source of truth is `src/design-tokens/` (single JSON file)
-- Style Dictionary can regenerate dist/ deterministically
+```
+dist/
+├── manifest.json                    # Build metadata
+│
+├── css/                             # CSS Custom Properties
+│   ├── shared/                      # Primitives (4 files)
+│   │   ├── colorprimitive.css
+│   │   ├── fontprimitive.css
+│   │   ├── sizeprimitive.css
+│   │   └── spaceprimitive.css
+│   └── brands/
+│       ├── bild/
+│       │   ├── density/             # 3 files (compact, default, spacious)
+│       │   ├── overrides/           # 2 files (brand + color mappings)
+│       │   ├── components/          # ~300 component token files
+│       │   └── semantic/
+│       │       ├── breakpoints/     # 4 files + 1 responsive
+│       │       ├── color/           # 2 files (light, dark)
+│       │       ├── typography/      # 4 files (xs, sm, md, lg)
+│       │       └── effects/         # 2 files (light, dark)
+│       ├── sportbild/               # Same structure as bild
+│       └── advertorial/             # No color/ folder!
+│
+├── scss/                            # SCSS Variables (same structure)
+├── js/                              # JavaScript ES6 (same structure)
+├── json/                            # JSON Data (same structure)
+│
+├── ios/                             # Swift Classes
+│   ├── shared/                      # 4 files
+│   └── brands/{brand}/
+│       ├── density/
+│       ├── overrides/
+│       ├── components/
+│       ├── semantic/
+│       │   ├── breakpoints/
+│       │   ├── color/
+│       │   └── effects/
+│       ├── sizeclass-compact/       # sm breakpoint: Typography.swift
+│       └── sizeclass-regular/       # lg breakpoint: Typography.swift
+│
+├── android/                         # Android XML Resources
+│   └── res/values/
+│       ├── shared/
+│       └── brands/{brand}/
+│           └── sizeclass-{compact|regular}/
+│               └── typography_styles.xml
+│
+├── flutter/                         # Flutter Dart (same as CSS structure)
+│
+└── bundles/                         # Convenience bundle files
+    ├── bild-all.css                 # All BILD tokens
+    ├── bild-semantic.css            # Semantic layer only
+    └── bild/components/             # Per-component bundles
+```
 
-**How to review changes without dist/ in Git:**
-1. Source changes visible in PR diff (JSON file)
-2. Build artifacts downloadable from Actions (30 days)
-3. Local testing: `npm run build` generates dist/
-4. CI validates all builds pass (52/52)
+### Brand Differences
 
-This approach follows modern best practices used by design systems like Shopify Polaris, GitHub Primer, and Adobe Spectrum.
+| Brand | Color Folder | Color Mapping | Notes |
+|-------|--------------|---------------|-------|
+| **BILD** | ✅ Yes | ✅ Yes | Full token set |
+| **SportBILD** | ✅ Yes | ✅ Yes | Full token set |
+| **Advertorial** | ❌ No | ❌ No | No BrandColorMapping collection in Figma |
 
 ---
 
-## 🧪 Testing & Verification
+## 🔧 Development
 
-### Build Verification
+### Project Structure
 
-```bash
-# Run full build
-npm run build
+```
+.
+├── src/design-tokens/
+│   └── bild-design-system-raw-data.json     # Figma Variables export
+│
+├── scripts/
+│   ├── preprocess-plugin-tokens.js          # Preprocessing (1100+ lines)
+│   │   • Scope-based type determination
+│   │   • Alias resolution
+│   │   • Opacity conversion (Figma % → 0-1)
+│   │   • Floating-point rounding
+│   │
+│   ├── build-tokens-v2.js                   # Build orchestration (600+ lines)
+│   │   • Multi-platform configuration
+│   │   • 969 builds across 7 platforms
+│   │   • Composite token support
+│   │
+│   └── build-bundles.js                     # Bundle generation
+│       • Quick Start bundles
+│       • Semantic bundles
+│       • Component bundles
+│
+├── build-config/
+│   └── style-dictionary.config.js           # Custom transforms (2000+ lines)
+│       • iOS Points transform (CGFloat not px strings)
+│       • iOS UIColor transform (objects not strings)
+│       • Opacity transform (% → decimal)
+│       • Floating-point rounding transform
+│       • Typography/Effects formats
+│
+├── tokens/                                  # Intermediate (tracked in Git)
+│   ├── shared/                              # 4 primitive files
+│   └── brands/                              # ~920 brand/mode/component files
+│
+├── dist/                                    # Build output (NOT in Git)
+│   └── [Generated by npm run build]
+│
+└── README.md
+```
 
-# 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
+### Development Workflow
 
-```bash
-# BILD should use Gotham Condensed
-grep "font-family-gotham-cond" dist/css/brands/bild/semantic/typography/typography-md.css
+1. **Export from Figma**
+   - Use TokenSync plugin (custom-built)
+   - Target branch: `figma-tokens` (recommended)
+   - Exports to: `src/design-tokens/bild-design-system-raw-data.json`
 
-# SportBILD should use AntennaExtraCond
-grep "font-family-antenna-extra-cond" dist/css/brands/sportbild/semantic/typography/typography-md.css
+2. **Plugin Pushes to GitHub**
+   - Creates/updates `figma-tokens` branch
+   - Triggers `auto-pr-from-figma.yml` workflow
+   - PR automatically created with build artifacts
 
-# BILD red: #DD0000
-grep "bild-red-bild-red" dist/css/shared/colorprimitive.css
-# Expected: --bild-red-bild-red: #DD0000;
+3. **Review PR**
+   - Source changes: View JSON diff
+   - Platform outputs: Download CI artifacts
+   - Verify build: 969/969 successful
 
-# SportBILD has different brand colors
-grep "sport-bild-dark-blue" dist/css/shared/colorprimitive.css
-```
+4. **Merge to main**
+   - `publish-on-merge.yml` triggers
+   - Fresh build + version bump
+   - Publish to npm + GitHub Release
 
-### Advertorial Special Case
+### Local Development
 
 ```bash
-# Advertorial should NOT have color/ folder
-ls dist/css/brands/advertorial/semantic/
-# Expected: breakpoints/ effects/ typography/ (NO color/)
+# Make changes to source
+vim src/design-tokens/bild-design-system-raw-data.json
 
-ls dist/css/brands/bild/semantic/
-# Expected: breakpoints/ color/ effects/ typography/
+# Build locally
+npm run build
+
+# Verify outputs
+ls dist/css/brands/bild/
+grep "text-color-primary" dist/css/brands/bild/semantic/color/colormode-light.css
 ```
 
-### Breakpoint Scaling
+---
 
-```bash
-# Typography scales across breakpoints
-# headline1 should scale from 48px (xs) to 100px (lg) for BILD
+## 🔄 CI/CD Integration
 
-grep "headline1" dist/json/brands/bild/semantic/typography/typography-xs.json | grep fontSize
-# Expected: 48px
+### GitHub Actions Workflows
 
-grep "headline1" dist/json/brands/bild/semantic/typography/typography-lg.json | grep fontSize
-# Expected: 100px
-```
+#### 1. Build Tokens (`.github/workflows/build-tokens.yml`)
+- **Trigger**: Push/PR to main, develop, claude/**, figma-tokens
+- **Outputs**: Build artifacts (30-day retention)
+- **PR Comment**: Download link + build stats
 
----
+#### 2. Auto PR from Figma (`.github/workflows/auto-pr-from-figma.yml`)
+- **Trigger**: Push to `figma-tokens` branch
+- **Creates**: Pull Request to main
+- **Includes**: Build artifacts + stats
 
-## 🆘 Troubleshooting
+#### 3. Publish on Merge (`.github/workflows/publish-on-merge.yml`)
+- **Trigger**: Merge to main
+- **Actions**: Fresh build, version bump, npm publish, GitHub Release
 
-### ⚠️ Variable nicht gefunden: VariableID:16104:163534
+### Why dist/ is NOT in Git
 
-**Problem:** Preprocessing warns about missing variable
+- ✅ No merge conflicts (969 generated files)
+- ✅ Clean Git history (only source files)
+- ✅ PR review via CI artifacts (30 days)
+- ✅ Deterministic builds (Style Dictionary)
+- ✅ Smaller repo size (~15MB saved per commit)
 
-**Cause:** Variable `Component/Kicker/Partner/kickerStylebookBgColor` references a deleted/renamed variable in Figma
+Modern design systems (Shopify Polaris, GitHub Primer, Adobe Spectrum) follow this pattern.
 
-**Impact:** Non-critical - Token gets `UNRESOLVED_` value, build continues
+---
 
-**Solution:** In Figma, check and re-link the `kickerStylebookBgColor` variable
+## 🆘 Troubleshooting
 
-### ⚠️ Token Collisions in fontprimitive/sizeprimitive/spaceprimitive
+### Missing dist/ Folder
 
-**Problem:** Style Dictionary warns about token name collisions for some platforms
+**Q: Where is the dist/ folder?**
 
-**Cause:** LetterSpacing tokens have positive/negative values with similar names:
-- `letterSpace-0_25` (negative) → `LetterSpace025` (JS/iOS/Flutter)
-- `letterSpace0_25` (positive) → `LetterSpace025` (same!)
+**A:** The `dist/` folder is **intentionally not tracked in Git**. Generate it:
 
-**Impact:** Non-critical - Last value wins, usually works fine
+```bash
+# Option 1: Generate locally
+npm run build
 
-**Platforms Affected:**
-- ❌ JavaScript, iOS, Android, Flutter, JSON (name collision)
-- ✅ CSS, SCSS (no collision - hyphens preserved)
+# Option 2: Download from CI
+# Go to Actions → Workflow Run → Download Artifacts
 
-**Solution (Figma-side):**
-Rename tokens in Figma:
-```
-letterSpace-0_25 → letterSpaceNeg0_25  (or letterSpaceMinus0_25)
-letterSpace0_25  → letterSpacePos0_25  (or letterSpacePlus0_25)
+# Option 3: Install from npm (includes dist/)
+npm install @marioschmidt/design-system-tokens
 ```
 
 ### Build Failures
 
-**Problem:** Build fails with "ENOENT: no such file or directory"
-
-**Solution:**
 ```bash
-# Make sure preprocessing ran first
-npm run preprocess
+# Clean and rebuild
+npm run clean
+npm install
+npm run build
 
-# Then build
-npm run build:tokens
+# Check for errors
+npm run build 2>&1 | grep "❌"
 
-# Or use the combined command
-npm run build
+# Expected: 969/969 builds successful
 ```
 
-**Problem:** "Cannot find module 'style-dictionary'"
+### Token Value Issues
 
-**Solution:**
 ```bash
-npm install
-```
+# Check preprocessing worked
+cat tokens/brands/bild/semantic/color/colormode-light.json | grep "textColorPrimary"
 
-### Missing dist/ Folder
+# Check final output
+grep "text-color-primary" dist/css/brands/bild/semantic/color/colormode-light.css
+```
 
-**Problem:** dist/ folder not visible in repository or after clone
+### iOS px String Issue (Fixed)
 
-**Explanation:** The `dist/` folder is **intentionally not tracked in Git** (as of v2.1.0). This prevents merge conflicts and keeps the repository clean.
+**Old Problem:** iOS was getting `"8px"` strings instead of `8` CGFloat.
 
-**Solutions:**
+**Solution:** Now using `custom/size/ios-points` transform. Verify:
 
-**Option 1: Generate Locally**
 ```bash
-npm run build
-ls dist/  # Should show css/, scss/, js/, json/, ios/, android/, flutter/
+grep "Space2x" dist/ios/shared/Spaceprimitive.swift
+# Expected: public static let Space2x = 16 (not "16px")
 ```
 
-**Option 2: Download from CI Artifacts**
-1. Go to repository **Actions** tab
-2. Find the latest workflow run for your branch
-3. Download `design-tokens-{sha}.zip` from Artifacts section
-4. Extract the `dist/` folder
+### iOS UIColor String Issue (Fixed)
 
-**Option 3: From Pull Request**
-1. Find the PR you're interested in
-2. Look for bot comment with artifact download link
-3. Download and extract
+**Old Problem:** iOS was getting `"UIColor(red: ...)"` strings instead of objects.
 
-**Note:** The `dist/` folder is automatically included in npm packages. If you install via npm, the dist/ folder will be in `node_modules/@marioschmidt/design-system-tokens/dist/`.
+**Solution:** Format now detects UIColor syntax. Verify:
+
+```bash
+grep "TextColorPrimary" dist/ios/brands/bild/semantic/color/ColormodeLight.swift
+# Expected: public static let TextColorPrimary = UIColor(red: ..., alpha: ...)
+# NOT: "UIColor(red: ..., alpha: ...)"
+```
 
-### Wrong Platform Outputs
+### Opacity Not Converting (Fixed)
 
-**Problem:** Some platforms missing files
+**Old Problem:** Opacity showed as `5` instead of `0.05`.
+
+**Solution:** `custom/opacity` transform now divides by 100. Verify:
 
-**Solution:** Check build output for errors:
 ```bash
-npm run build 2>&1 | grep "❌"
+grep "layer-opacity05" dist/css/brands/bild/semantic/color/colormode-light.css
+# Expected: --layer-opacity05: 0.05; (not 5)
 ```
 
-All platforms should build successfully: 52/52
-
 ---
 
-## 📊 Technical Details
-
-### Key Design Decisions
+## 📝 Changelog
 
-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
+### v3.0.0 (Current) - Production-Ready Transforms
 
-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
+**✨ Major Features:**
 
-3. **Mode Name Matching**
-   - Collections have different mode IDs
-   - Match by `mode.name` instead of `mode.modeId`
-   - Robust against Figma re-creating modes
+- **Scope-Based Type Detection**: Figma scopes determine token types semantically
+- **iOS Points Transform**: CGFloat numbers instead of "px" strings
+- **iOS UIColor Objects**: Proper UIColor instances instead of strings
+- **Opacity Conversion**: Figma % (5, 10, 70) → CSS decimal (0.05, 0.1, 0.7)
+- **Floating-Point Rounding**: Eliminates precision errors across all platforms
+- **Typography px Units**: fontSize, lineHeight, letterSpacing get proper px units
 
-4. **Brand-Specific Processing**
-   - Separate token files per brand and mode
-   - Prevents collisions during Style Dictionary build
-   - Enables brand-specific value verification
+**🔧 Technical Changes:**
 
-5. **Size Class Terminology**
-   - iOS/Android use "sizeclass" terminology
-   - Only compact (sm) and regular (lg) generated
-   - xs and md breakpoints skipped for native platforms
+- Added `determineTokenType()` with 2-tier logic (scopes → name fallback)
+- Added `custom/size/ios-points` transform (CGFloat output)
+- Added `custom/opacity` transform (% to decimal conversion)
+- Added `custom/fontWeight` and `custom/number` transforms
+- Fixed iOS color format to output UIColor objects
+- Fixed all format functions to use `token.$value` (transformed) not `token.value`
+- Updated typography formats with px units for web platforms
 
-### Performance
+**📊 Production Readiness:**
 
-- **Preprocessing**: ~2-3 seconds
-- **Build**: ~8-10 seconds (all 52 builds)
-- **Total**: ~11 seconds
-- **Output Size**: ~15 MB (all platforms)
+| Token Type | Platforms Tested | Status |
+|------------|------------------|--------|
+| Colors | 6/6 | ✅ |
+| Dimensions | 6/6 | ✅ |
+| Opacity | 6/6 | ✅ |
+| Font Weight | 6/6 | ✅ |
+| Typography | 6/6 | ✅ |
+| Effects | 5/6 | ✅ |
 
----
+**🐛 Bug Fixes:**
 
-## 📝 Changelog
+- iOS dimensions now output as CGFloat (16) not strings ("16px")
+- iOS colors now output as UIColor objects not strings
+- Opacity values properly converted from Figma % to 0-1 range
+- Typography fontSize/lineHeight/letterSpacing have px units
+- Floating-point precision errors eliminated (0.699999988 → 0.7)
 
-### v2.1.0 (Current) - CI Artifacts Workflow
+**📚 Documentation:**
 
-**✨ Features:**
-- **Modern CI/CD**: dist/ no longer tracked in Git (prevents merge conflicts)
-- **GitHub Actions Artifacts**: Build outputs available as downloadable artifacts (30 days)
-- **PR Bot Comments**: Automatic comments on PRs with artifact download links
-- **Build Statistics**: Detailed file counts and build summaries in PR comments
-- **Figma Branch Workflow**: Documented recommended workflow with `figma-tokens` branch
+- Complete README overhaul with transform reference tables
+- Added Figma Integration & Dependencies section
+- Documented stable vs. unstable changes
+- Added platform usage examples for all 7 platforms
+- Added troubleshooting for common issues
 
-**🔧 Changes:**
-- `dist/` folder now gitignored (removed 353 files from tracking)
-- `tokens/` folder now tracked in Git (preprocessed intermediate files)
-- Updated workflows: `build-tokens.yml`, `auto-pr-from-figma.yml`
-- Removed dist/ commit steps from CI workflows
-- Added artifact upload and PR comment features
+**🎯 Build Stats:**
 
-**📚 Documentation:**
-- Complete CI/CD Integration section rewrite
-- Added "Token Processing Pipeline" visualization
-- Added "Why the tokens/ Intermediate Step?" explanation
-- Added "Figma Export Target Branches" comparison table
-- Added "Reviewing Build Artifacts" guide
-- Translated all German comments in build scripts to English
-
-**🎯 Benefits:**
-- ✅ No more merge conflicts on generated files
-- ✅ Cleaner Git history (only source files tracked)
-- ✅ PR review still possible via downloadable artifacts
-- ✅ Follows modern best practices (Shopify Polaris, GitHub Primer, Adobe Spectrum)
-- ✅ Smaller repository size (~15 MB removed per commit)
-
-**⚡ Performance:**
-- Same build performance: 52/52 builds successful
-- ~11 seconds total build time
-- Artifacts upload in ~2-3 seconds
+- 969/969 builds successful (up from 52/52)
+- Components: 917 files
+- All platforms: production-ready outputs
 
 ---
 
-### v2.0.0 - Custom Plugin Migration
+### v2.1.0 - CI Artifacts Workflow
 
-**✨ Features:**
-- 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
+- dist/ no longer tracked in Git
+- GitHub Actions artifacts for PR review
+- Automatic PR comments with download links
+- 30-day artifact retention
 
-**🐛 Bug Fixes:**
-- 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
+---
 
-**⚡ Performance:**
-- 52/52 builds successful (up from 30/30)
-- All 7 platforms generate complete token sets
-- ~11 seconds total build time
+### v2.0.0 - Custom Plugin Migration
 
-**📦 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
+- Custom Figma Plugin integration
+- 7 platform support
+- Complete alias resolution
+- Composite tokens (Typography, Effects)
+- 52/52 builds successful
 
 ---
 
@@ -1201,3 +1255,5 @@ All platforms should build successfully: 52/52
 ---
 
 **Built with ❤️ for the BILD Design System**
+
+Version 3.0.0 | Production-Ready | 969 Successful Builds | 7 Platforms | 3 Brands