@marioschmidt/design-system-tokens 1.0.69 → 1.0.71

package/README.md

@@ -1,30 +1,27 @@
-# 🎨 BILD Design Ops Pipeline
+# 🎨 BILD Design System - Token Pipeline
 
-> **⚠️ IMPORTANT NOTICE**
->
-> This pipeline is under active development. Generated packages are for **testing purposes only**.
+> **Part of the [BILD Design Ops Pipeline](../../README.md)** | [Icon Documentation](../icons/README.md) | [Component Documentation](../components/README.md)
 
-A comprehensive design operations pipeline for the BILD Design System. Transforms Figma exports into production-ready assets across multiple platforms using the **TokenSync Plugin**.
+Multi-platform design token transformation pipeline powered by **Style Dictionary v4** with **Figma-scoped semantic type detection**.
 
-[![Build Tokens](https://github.com/UXWizard25/vv-token-test-v3/workflows/Build%20Design%20Tokens/badge.svg)](https://github.com/UXWizard25/vv-token-test-v3/actions)
-[![Build Icons](https://github.com/UXWizard25/vv-token-test-v3/workflows/Build%20Icons/badge.svg)](https://github.com/UXWizard25/vv-token-test-v3/actions)
-[![npm tokens](https://img.shields.io/npm/v/@marioschmidt/design-system-tokens.svg?label=tokens)](https://www.npmjs.com/package/@marioschmidt/design-system-tokens)
-[![npm icons](https://img.shields.io/npm/v/@marioschmidt/design-system-icons.svg?label=icons)](https://www.npmjs.com/package/@marioschmidt/design-system-icons)
+[![npm version](https://img.shields.io/npm/v/@marioschmidt/design-system-tokens.svg)](https://www.npmjs.com/package/@marioschmidt/design-system-tokens)
+[![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)
 
 ---
 
 ## 📋 Table of Contents
 
 - [🎯 Overview](#-overview)
-- [📦 Packages](#-packages)
-- [🏗️ Architecture](#️-architecture)
+- [🏗️ Pipeline Flow](#️-pipeline-flow)
+- [📦 Installation](#-installation)
 - [🚀 Quick Start](#-quick-start)
-- [🔗 Figma Integration](#-figma-integration)
-- [📁 Project Structure](#-project-structure)
-- [⚙️ Build Commands](#️-build-commands)
+- [🎨 Platform Usage](#-platform-usage)
+- [📊 Token Transform Reference](#-token-transform-reference)
+- [📁 Output Structure](#-output-structure)
+- [🔗 Figma Integration & Dependencies](#-figma-integration--dependencies)
 - [🔄 CI/CD Workflows](#-cicd-workflows)
-- [📊 Platform Support](#-platform-support)
-- [📚 Documentation](#-documentation)
+- [🆘 Troubleshooting](#-troubleshooting)
+- [🔗 Related](#-related)
 - [🤝 Contributing](#-contributing)
 - [📄 License](#-license)
 
@@ -32,426 +29,805 @@ A comprehensive design operations pipeline for the BILD Design System. Transform
 
 ## 🎯 Overview
 
-The BILD Design Ops Pipeline transforms design assets from Figma into production-ready code for multiple platforms. It consists of two independent sub-pipelines:
+This pipeline processes the multi-layer, multi-brand BILD Design System architecture:
 
-| Pipeline | Input | Output | Platforms |
-|----------|-------|--------|-----------|
-| **🎨 Token Pipeline** | Figma Variables | Design Tokens | 3 platforms (6 formats) |
-| **🖼️ Icon Pipeline** | Figma Icons (SVG) | Multi-format Icons | 5 platforms |
+- **3 Brands**: BILD, SportBILD, Advertorial
+- **3 Platforms** (6 formats): Web (CSS, SCSS, JS, JSON), iOS (SwiftUI), Android (Compose)
+- **Multiple Modes**: Density (3), Breakpoints (4), Color Modes (2)
+- **Token Types**: Primitives, Semantic Tokens, Component Tokens (~970 files)
+- **Shadow DOM Compatible**: Works with Stencil, Lit, and native Web Components
 
-Both pipelines use the **TokenSync Figma Plugin** for automated exports.
+### Token Architecture (4 Layers)
 
----
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  LAYER 4: Component Tokens                                                   │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│  Button, Card, Teaser, Alert, InputField, etc.                              │
+│  Modes: color (light/dark), density, breakpoint, typography                 │
+│  References → Semantic Tokens                                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  LAYER 3: Semantic Tokens                                                    │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│  text-color-primary, surface-color-secondary, border-color-*, etc.          │
+│  Modes: color (light/dark), breakpoint                                      │
+│  References → Brand Mapping                                                 │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  LAYER 2: Brand Mapping + Density                                            │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│  BrandColorMapping: Color Primitives → Brands                               │
+│  BrandTokenMapping: Other Primitives → Brands                               │
+│  Density: default, dense, spacious                                          │
+│  Modes: BILD, SportBILD, Advertorial                                        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  LAYER 1: Primitives (Global)                                                │
+│  ─────────────────────────────────────────────────────────────────────────  │
+│  colorprimitive, spaceprimitive, sizeprimitive, fontprimitive               │
+│  Absolute values: --bildred: #DD0000, --space2x: 16px                       │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
 
-## 📦 Packages
+### CSS var() Alias Chain
 
-| Package | Description | Version | Documentation |
-|---------|-------------|---------|---------------|
-| **@marioschmidt/design-system-tokens** | Multi-platform design tokens | [![npm](https://img.shields.io/npm/v/@marioschmidt/design-system-tokens.svg)](https://www.npmjs.com/package/@marioschmidt/design-system-tokens) | [📖 README.tokens.md](./README.tokens.md) |
-| **@marioschmidt/design-system-icons** | Multi-platform icon assets | [![npm](https://img.shields.io/npm/v/@marioschmidt/design-system-icons.svg)](https://www.npmjs.com/package/@marioschmidt/design-system-icons) | [📖 README.icons.md](./README.icons.md) |
-| **JavaScript/React** | ESM + ThemeProvider (Dual-Axis) | - | [📖 docs/js.md](./docs/js.md) |
-| **Android Compose** | Jetpack Compose (Dual-Axis) | - | [📖 docs/android.md](./docs/android.md) |
-| **iOS SwiftUI** | SwiftUI (Dual-Axis) | - | [📖 docs/ios.md](./docs/ios.md) |
-| **Web Components** | Stencil, Lit, Shadow DOM | - | [📖 docs/css.md](./docs/css.md#shadow-dom--web-components) |
+Tokens use `var()` references to maintain the alias chain from Figma:
 
----
+```css
+/* Component → Semantic → Primitive */
+--button-primary-bg-color: var(--core-color-primary, #DD0000);
+                                ↓
+--core-color-primary: var(--bildred, #DD0000);
+                           ↓
+--bildred: #DD0000;
+```
 
-## 🏗️ Architecture
+This enables:
+- **Theme switching** without recompiling (change primitives = change all)
+- **Brand switching** via data attributes
+- **Fallback values** for robustness
 
-### High-Level Overview
+### Pipeline Flow
 
 ```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                              FIGMA                                          │
-│  ┌─────────────────────┐              ┌─────────────────────┐              │
-│  │  📊 Variables       │              │  🖼️ Icons           │              │
-│  │  (Design Tokens)    │              │  (SVG Assets)       │              │
-│  └──────────┬──────────┘              └──────────┬──────────┘              │
-└─────────────┼───────────────────────────────────┼──────────────────────────┘
-              │                                   │
-              │  TokenSync Plugin                 │  TokenSync Plugin
-              │                                   │
-              ▼                                   ▼
-┌─────────────────────────────┐    ┌─────────────────────────────┐
-│  📁 figma-tokens branch     │    │  📁 figma-icons branch      │
-│  src/design-tokens/*.json   │    │  src/icons/*.svg            │
-└──────────────┬──────────────┘    └──────────────┬──────────────┘
-               │                                  │
-               │  GitHub Actions                  │  GitHub Actions
-               │                                  │
-               ▼                                  ▼
-┌─────────────────────────────┐    ┌─────────────────────────────┐
-│  🔧 TOKEN PIPELINE          │    │  🔧 ICON PIPELINE           │
-│                             │    │                             │
-│  ┌───────────────────────┐  │    │  ┌───────────────────────┐  │
-│  │ 1. Preprocessing      │  │    │  │ 1. SVG Validation     │  │
-│  │    • Scope detection  │  │    │  │    • Security checks  │  │
-│  │    • Alias resolution │  │    │  │    • Structure check  │  │
-│  │    • Type mapping     │  │    │  └───────────┬───────────┘  │
-│  └───────────┬───────────┘  │    │              │              │
-│              │              │    │              ▼              │
-│              ▼              │    │  ┌───────────────────────┐  │
-│  ┌───────────────────────┐  │    │  │ 2. SVGO Optimization  │  │
-│  │ 2. Style Dictionary   │  │    │  │    • currentColor     │  │
-│  │    • Transforms       │  │    │  │    • Remove metadata  │  │
-│  │    • Formats          │  │    │  └───────────┬───────────┘  │
-│  │    • Platform builds  │  │    │              │              │
-│  └───────────┬───────────┘  │    │              ▼              │
-│              │              │    │  ┌───────────────────────┐  │
-│              ▼              │    │  │ 3. Platform Generation│  │
-│  ┌───────────────────────┐  │    │  │    • React (TSX→JS)   │  │
-│  │ 3. Bundle Generation  │  │    │  │    • Android XML      │  │
-│  │    • Quick Start      │  │    │  │    • Flutter TTF      │  │
-│  │    • Per-component    │  │    │  │    • iOS Assets       │  │
-│  └───────────────────────┘  │    │  └───────────────────────┘  │
-└──────────────┬──────────────┘    └──────────────┬──────────────┘
-               │                                  │
-               ▼                                  ▼
-┌─────────────────────────────┐    ┌─────────────────────────────┐
-│  📤 OUTPUT                  │    │  📤 OUTPUT                  │
-│                             │    │                             │
-│  dist/                      │    │  dist/icons/                │
-│  ├── css/     (CSS Vars)    │    │  ├── svg/      (Optimized)  │
-│  │   └── bundles/ (Quick)   │    │  ├── react/    (ESM + d.ts) │
-│  ├── scss/    (SCSS Vars)   │    │  ├── android/  (XML)        │
-│  ├── js/      (ESM + React) │    │  ├── flutter/  (TTF + Dart) │
-│  ├── json/    (Raw Data)    │    │  └── ios/      (xcassets)   │
-│  ├── ios/     (Swift)       │    │                             │
-│  └── android/ (Compose/Kt)  │    │                             │
-│                             │    │                             │
-└──────────────┬──────────────┘    └──────────────┬──────────────┘
-               │                                  │
-               │  npm publish                     │  npm publish
-               │                                  │
-               ▼                                  ▼
-┌─────────────────────────────┐    ┌─────────────────────────────┐
-│  📦 @marioschmidt/          │    │  📦 @marioschmidt/          │
-│     design-system-tokens    │    │     design-system-icons     │
-└─────────────────────────────┘    └─────────────────────────────┘
+┌─────────────────────────────────────────────────┐
+│ Figma Variables (Design Source)                 │
+│ • BILD Design System file                       │
+│ • Variables with Scopes & Aliases               │
+│ • CodeBridge plugin export                      │
+└───────────────────────┬─────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────┐
+│ Raw Export (src/design-tokens/)                 │
+│ • bild-design-system-raw-data.json              │
+└───────────────────────┬─────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────┐
+│ Preprocessing (scripts/tokens/preprocess.js)    │
+│ • Scope-based type determination                │
+│ • Alias resolution                              │
+│ • Component token detection                     │
+└───────────────────────┬─────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────┐
+│ Intermediate (tokens/)                          │
+│ • Style Dictionary format                       │
+│ • ~920 JSON files (tracked in Git)              │
+└───────────────────────┬─────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────┐
+│ Style Dictionary Build                          │
+│ • Platform-specific transforms                  │
+│ • iOS: CGFloat Points (not px strings)          │
+│ • iOS: SwiftUI Color                            │
+└───────────────────────┬─────────────────────────┘
+                        ↓
+┌─────────────────────────────────────────────────┐
+│ Build Output (dist/)                            │
+│ • 969 successful builds                         │
+│ • NOT tracked in Git (CI artifacts)             │
+└─────────────────────────────────────────────────┘
 ```
 
----
+## Installation
 
-## 🚀 Quick Start
+```bash
+npm install @marioschmidt/design-system-tokens
+```
 
-### Installation
+## Quick Start
 
 ```bash
-# Design Tokens
-npm install @marioschmidt/design-system-tokens
+# Full build (tokens + components)
+npm run build
+
+# Build tokens only
+npm run build:tokens   # Preprocess + Style Dictionary + bundles
 
-# Icons
-npm install @marioschmidt/design-system-icons
+# Build everything (tokens + icons + components)
+npm run build:all
+
+# Stencil Web Components
+npm run build:components  # Build Stencil components (requires tokens built first)
+npm run dev:stencil       # Dev server with hot reload (port 3333)
 ```
 
-### Token Usage
+### Monorepo Structure
+
+This package is part of the npm workspaces monorepo:
+
+| Package | npm Name | Location |
+|---------|----------|----------|
+| Tokens | `@marioschmidt/design-system-tokens` | `packages/tokens/` |
+| Icons | `@marioschmidt/design-system-icons` | `packages/icons/` |
+| Components | `@marioschmidt/design-system-components` | `packages/components/` |
+
+## Token Type Mapping
+
+Figma token types (`$type`) are automatically mapped to platform-specific types:
+
+| Figma `$type` | CSS | Swift (iOS) | Kotlin (Android) |
+|---------------|-----|-------------|------------------|
+| `dimension` | `var(--token)` (px) | `CGFloat` | `Dp` (.dp) |
+| `fontSize` | `var(--token)` (px) | `CGFloat` | `TextUnit` (.sp) |
+| `lineHeight` | `var(--token)` (px) | `CGFloat` | `TextUnit` (.sp) |
+| `letterSpacing` | `var(--token)` (px) | `CGFloat` | `TextUnit` (.sp) |
+| `fontWeight` | `var(--token)` | `FontWeight` | `FontWeight` |
+| `number` | `var(--token)` | `CGFloat` | `Float` |
+| `fontFamily` | `var(--token)` | `String` | `String` |
+| `string` | `var(--token)` | `String` | `String` |
+| `boolean` | `var(--token)` | `Bool` | `Boolean` |
+| `opacity` | `var(--token)` (0-1) | `CGFloat` | `Float` |
+| `color` | `var(--token)` (hex/rgba) | `Color` | `Color` |
+| `shadow` | `box-shadow` | `ShadowStyle` | `ShadowStyle` |
+| `typography` | CSS classes | `TextStyle` | `DesignTextStyle` |
+
+### Token Type Distribution
+
+| $type | Count | Description |
+|-------|-------|-------------|
+| `dimension` | 3557 | Spacing, sizing, layout values |
+| `typography` | 1356 | Composite font definitions |
+| `fontSize` | 1086 | Font size values |
+| `color` | 1012 | Color values (hex, rgba) |
+| `lineHeight` | 840 | Line height values |
+| `fontWeight` | 318 | Font weight values (100-1000) |
+| `fontFamily` | 307 | Font family names |
+| `letterSpacing` | 155 | Letter spacing values |
+| `string` | 133 | String values (e.g., breakpoint names) |
+| `boolean` | 102 | Boolean flags |
+| `shadow` | 78 | Drop shadow definitions |
+| `opacity` | 72 | Opacity percentages (0-100) |
+| `number` | 24 | Generic numeric values |
+
+## Platform Usage
+
+### CSS
 
 ```css
-/* CSS */
 @import '@marioschmidt/design-system-tokens/css/brands/bild/semantic/color/colormode-light.css';
 
 .button {
   background-color: var(--text-color-accent-constant);
   padding: var(--space2x);
+  opacity: var(--layer-opacity50);
 }
 ```
 
+### JavaScript / React
+
+> **See [docs/js.md](./docs/js.md) for complete documentation**
+
 ```javascript
-// JavaScript (ES Modules) - Values are CSS-ready strings
-import { createTheme } from '@marioschmidt/design-system-tokens/themes';
+// With React ThemeProvider (Dual-Axis Architecture)
 import { ThemeProvider, useTheme } from '@marioschmidt/design-system-tokens/react';
 
-const theme = createTheme({ colorBrand: 'bild', colorMode: 'light' });
+function App() {
+  return (
+    <ThemeProvider colorBrand="bild" colorMode="light">
+      <MyComponent />
+    </ThemeProvider>
+  );
+}
+
+function MyComponent() {
+  const { theme } = useTheme();
+  return (
+    <div style={{
+      color: theme.colors.textColorPrimary,      // "#232629"
+      padding: theme.spacing.gridSpaceRespBase   // "12px" - CSS-ready!
+    }}>
+      Content
+    </div>
+  );
+}
+
+// Without React - Direct theme creation
+import { createTheme } from '@marioschmidt/design-system-tokens/themes';
+
+const theme = createTheme({
+  colorBrand: 'bild',
+  colorMode: 'light',
+  breakpoint: 'md'
+});
 console.log(theme.colors.textColorPrimary);   // "#232629"
-console.log(theme.spacing.gridSpaceRespBase); // "12px" - CSS-ready!
+console.log(theme.spacing.gridSpaceRespBase); // "12px"
 ```
 
+#### JS Token Type Mapping
+
+Token values are automatically formatted based on their `$type` from Figma:
+
+| Token `$type` | JS Output | Example |
+|---------------|-----------|---------|
+| `dimension`, `fontSize`, `lineHeight`, `letterSpacing` | String with `px` | `"24px"` |
+| `color` | String (hex/rgba) | `"#DD0000"` |
+| `fontWeight`, `opacity`, `number` | Number | `700`, `50` |
+| `fontFamily`, `string` | String | `"Gotham Condensed"` |
+
+This follows the W3C DTCG spec and industry best practices (Chakra UI, MUI).
+
+### iOS Swift
+
 ```swift
-// iOS Swift
-view.backgroundColor = StyleDictionary.textColorPrimary
-let padding: CGFloat = StyleDictionary.space2x
+import SwiftUI
+import BildDesignTokens
+
+// Colors (SwiftUI Color)
+Rectangle()
+    .fill(BildColorsLight.textColorPrimary)
+
+// Dimensions (CGFloat)
+let padding: CGFloat = BildSizingCompact.space2x  // 16
+
+// With Theme Provider
+.designSystemTheme(colorBrand: .bild, darkTheme: false) {
+    theme.colors.textColorPrimary
+}
 ```
 
+### Android Jetpack Compose (Dual-Axis Architecture)
+
+> **See [docs/android.md](./docs/android.md) for complete documentation**
+
 ```kotlin
-// Android Jetpack Compose
-import com.bild.designsystem.bild.theme.BildTheme
+import com.bild.designsystem.shared.DesignSystemTheme
+import com.bild.designsystem.shared.ColorBrand
+import com.bild.designsystem.shared.ContentBrand
 import com.bild.designsystem.bild.components.ButtonTokens
-import com.bild.designsystem.shared.Density
-import com.bild.designsystem.shared.WindowSizeClass
 
 @Composable
-fun MyApp() {
-    BildTheme(
+fun MyScreen() {
+    // Dual-Axis Theme Provider
+    DesignSystemTheme(
+        colorBrand = ColorBrand.Bild,        // Color palette (Bild or Sportbild)
+        contentBrand = ContentBrand.Bild,    // Sizing/Typography (Bild, Sportbild, Advertorial)
         darkTheme = isSystemInDarkTheme(),
         sizeClass = WindowSizeClass.Compact,
         density = Density.Default
     ) {
-        Button(
-            colors = ButtonDefaults.buttonColors(
-                // Theme-aware: auto-selects Light/Dark
-                containerColor = ButtonTokens.Colors.current().buttonPrimaryBgColorIdle
-            )
-        ) {
-            Text(
-                // Semantic tokens via Theme
-                color = BildTheme.colors.textColorPrimary,
-                // Component typography: auto-selects Compact/Regular
-                fontSize = ButtonTokens.Typography.current().buttonLabelFontSize
-            )
+        // Polymorphic access via unified interfaces
+        Text(color = DesignSystemTheme.colors.textColorPrimary)
+        val fontSize = DesignSystemTheme.sizing.headline1FontSize
+
+        // Component tokens via current() accessors
+        val bgColor = ButtonTokens.Colors.current().buttonPrimaryBgColorIdle
+    }
+}
+
+// Advertorial with SportBILD colors (key use case)
+DesignSystemTheme(
+    colorBrand = ColorBrand.Sportbild,
+    contentBrand = ContentBrand.Advertorial
+) { AdvertorialContent() }
+```
+
+#### Dual-Axis Architecture
+
+Separates color selection from content selection:
+
+| Axis | Enum | Values | Purpose |
+|------|------|--------|---------|
+| **Color** | `ColorBrand` | `Bild`, `Sportbild` | Color palette & effects |
+| **Content** | `ContentBrand` | `Bild`, `Sportbild`, `Advertorial` | Sizing, typography, layout |
+
+#### Unified Interfaces (Polymorphic Access)
+
+Both iOS and Android implement identical unified protocols/interfaces for polymorphic theme access:
+
+| Interface | Purpose | Property Count | iOS Type | Android Type |
+|-----------|---------|----------------|----------|--------------|
+| `DesignColorScheme` | All color tokens | 80+ colors | `Color` | `Color` |
+| `DesignSizingScheme` | All sizing tokens | 180+ values | `CGFloat` | `Dp` |
+| `DesignTypographyScheme` | All text styles | 37 styles | `TextStyle` | `DesignTextStyle` |
+| `DesignEffectsScheme` | Shadow tokens (brand-independent) | 8 shadows | `ShadowStyle` | `ShadowStyle` |
+
+> **Note:** Full iOS/Android architecture parity. Both platforms provide `theme.colors`, `theme.sizing`, `theme.typography`, and `theme.effects` accessors with polymorphic brand switching at runtime.
+
+#### Component Token Accessors
+
+All Component Tokens provide theme-aware `current()` accessors:
+
+| Accessor | Selects based on | iOS Values | Android Values |
+|----------|-----------------|------------|----------------|
+| `Colors.current()` | `isDarkTheme` | Light / Dark | Light / Dark |
+| `Sizing.current()` | `sizeClass` | Compact / Regular | Compact / Medium / Expanded |
+| `Typography.current()` | `sizeClass` | Compact / Regular | Compact / Medium / Expanded |
+| `Density.current()` | `density` | Dense / Default / Spacious | Dense / Default / Spacious |
+| `Effects.current()` | `isDarkTheme` | Light / Dark | Light / Dark |
+
+> **Note:** Android uses Material 3 WindowSizeClass with 3 values (Compact/Medium/Expanded), while iOS uses Apple's 2-value system (compact/regular).
+
+### iOS SwiftUI (Dual-Axis Architecture)
+
+> **See [docs/ios.md](./docs/ios.md) for complete documentation**
+
+```swift
+import SwiftUI
+
+struct MyApp: App {
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+                .designSystemTheme(
+                    colorBrand: .bild,        // Color palette
+                    contentBrand: .bild,      // Sizing/Typography
+                    darkTheme: false,
+                    sizeClass: .compact
+                )
         }
     }
 }
 
-// Multi-brand apps: Use DesignSystemTheme
-import com.bild.designsystem.shared.Brand
-import com.bild.designsystem.shared.DesignSystemTheme
+struct MyView: View {
+    @Environment(\.designSystemTheme) var theme
+
+    var body: some View {
+        // Polymorphic access via unified protocols
+        Text("Hello")
+            .foregroundColor(theme.colors.textColorPrimary)
+            .textStyle(theme.typography.headline1)  // Typography
+
+        // Sizing tokens
+        let padding = theme.sizing.gridSpaceRespBase
+
+        // Component tokens
+        Button("Click") { }
+            .background(ButtonTokens.Colors.light.buttonPrimaryBrandBgColorIdle)
+    }
+}
+
+// Advertorial with SportBILD colors
+.designSystemTheme(
+    colorBrand: .sportbild,
+    contentBrand: .advertorial
+)
+```
+
+#### iOS Unified Protocols
+
+| Protocol | Purpose |
+|----------|---------|
+| `DesignColorScheme` | All color tokens |
+| `DesignSizingScheme` | All sizing tokens |
+| `DesignTypographyScheme` | All text styles (TextStyle composites) |
+| `DesignEffectsScheme` | Shadow tokens (ShadowStyle composites, brand-independent) |
+
+### SCSS
+
+```scss
+@import '@marioschmidt/design-system-tokens/scss/brands/bild/semantic/color/colormode-light';
 
-DesignSystemTheme(brand = Brand.Bild) { /* ... */ }
+.button {
+  background-color: $text-color-accent-constant;
+  padding: $space2x;
+}
 ```
 
+### Web Components (Stencil, Lit)
+
+CSS Custom Properties **inherit through Shadow DOM**, enabling seamless theming:
+
 ```tsx
-// Web Components (Stencil) - CSS Custom Properties inherit through Shadow DOM
+// Stencil Component
 @Component({
   tag: 'my-button',
   shadow: true,
   styles: `
     .btn {
+      /* Token values inherit from Light DOM automatically! */
       background: var(--button-primary-brand-bg-color-idle);
       color: var(--button-primary-label-color);
+      padding: var(--button-stack-space) var(--button-inline-space);
+      border-radius: var(--button-border-radius);
+    }
+    .btn:hover {
+      background: var(--button-primary-brand-bg-color-hover);
     }
   `
 })
 export class MyButton { /* ... */ }
 ```
 
-### Icon Usage
+```html
+<!-- Usage: Tokens on body, components inherit automatically -->
+<body data-color-brand="bild" data-content-brand="bild" data-theme="light" data-density="default">
+  <my-button>BILD Button</my-button>  <!-- Red -->
+</body>
 
-```tsx
-// React
-import { Add, Menu, Search } from '@marioschmidt/design-system-icons';
+<body data-color-brand="sportbild" data-content-brand="sportbild" data-theme="dark" data-density="dense">
+  <my-button>Sport Button</my-button>  <!-- Blue -->
+</body>
+```
+
+**Theming Attributes:**
+
+| Attribute | Options | Purpose |
+|-----------|---------|---------|
+| `data-color-brand` | bild, sportbild | Colors & effects |
+| `data-content-brand` | bild, sportbild, advertorial | Typography & sizing |
+| `data-theme` | light, dark | Color mode |
+| `data-density` | default, dense, spacious | Spacing density |
 
-<Add size={24} aria-label="Add item" />
+> **Note:** See [docs/css.md](./docs/css.md#shadow-dom--web-components) for complete Shadow DOM documentation.
+
+## Responsive CSS Architecture
+
+### Breakpoint Implementation
+
+Breakpoints use native `@media` queries instead of `data-breakpoint` attributes:
+
+```css
+/* Base values (xs breakpoint) */
+[data-brand="bild"] {
+  --headline1-font-size: 32px;
+}
+
+/* Responsive overrides */
+@media (min-width: 390px) {  /* sm */
+  [data-brand="bild"] { --headline1-font-size: 40px; }
+}
+@media (min-width: 600px) {  /* md */
+  [data-brand="bild"] { --headline1-font-size: 48px; }
+}
+@media (min-width: 1024px) { /* lg */
+  [data-brand="bild"] { --headline1-font-size: 64px; }
+}
 ```
 
-```xml
-<!-- Android -->
-<ImageView android:src="@drawable/ic_add" />
+**Breakpoint Values:**
+| Breakpoint | Min-Width | Use Case |
+|------------|-----------|----------|
+| `xs` | 320px | Mobile (default) |
+| `sm` | 390px | Large mobile |
+| `md` | 600px | Tablet |
+| `lg` | 1024px | Desktop |
+
+### Native Sizeclass Mapping (iOS/Android)
+
+Native platforms use different size class systems:
+
+#### iOS (2 Size Classes - Apple HIG)
+
 ```
+Web Breakpoints         iOS Size Classes
+─────────────────       ────────────────
+xs (320px) ─────┐
+                ├────→  compact (Phones)
+sm (390px) ─────┘
+
+md (600px) ─────┐
+                ├────→  regular (Tablets)
+lg (1024px) ────┘
+```
+
+| Size Class | iOS Trait | Web Breakpoint |
+|------------|-----------|----------------|
+| `compact` | `.compact` | sm (390px) |
+| `regular` | `.regular` | lg (1024px) |
+
+#### Android (3 Size Classes - Material 3 WindowSizeClass)
 
-```dart
-// Flutter
-Icon(BildIcons.add, size: 24)
 ```
+Web Breakpoints         Android WindowSizeClass
+─────────────────       ───────────────────────
+xs (320px) ─────┐
+                ├────→  Compact (< 600dp)
+sm (390px) ─────┘
 
-```swift
-// iOS SwiftUI
-BildIcon.add.image.foregroundColor(.primary)
+md (600px) ──────────→  Medium (600-839dp)
+
+lg (1024px) ─────────→  Expanded (≥ 840dp)
 ```
 
-➡️ See [README.tokens.md](./README.tokens.md) and [README.icons.md](./README.icons.md) for complete usage examples.
+| Size Class | Material 3 Range | Web Breakpoint |
+|------------|------------------|----------------|
+| `Compact` | width < 600dp | sm (390px) |
+| `Medium` | 600dp ≤ width < 840dp | md (600px) |
+| `Expanded` | width ≥ 840dp | lg (1024px) |
 
 ---
 
-## 🔗 Figma Integration
+## Token Transform Reference
 
-Both pipelines integrate with Figma via the **TokenSync Plugin**:
+### Naming Conventions
 
-| Branch | Content | Trigger |
-|--------|---------|---------|
-| `figma-tokens` | Design Variables (JSON) | Token export from Figma |
-| `figma-icons` | Icon SVGs | Icon export from Figma |
+| Platform | Convention | Example |
+|----------|-----------|---------|
+| CSS | `kebab-case` with `--` | `--text-color-primary` |
+| SCSS | `kebab-case` with `$` | `$text-color-primary` |
+| JavaScript | `camelCase` | `textColorPrimary` |
+| iOS Swift | `camelCase` | `textColorPrimary` |
+| Android Compose | `camelCase` | `textColorPrimary` |
 
-### Workflow
+### Name Transformations
 
-```
-1. Designer exports from Figma using TokenSync Plugin
-2. Plugin pushes to dedicated branch (figma-tokens / figma-icons)
-3. GitHub Actions automatically builds and creates PR
-4. Team reviews PR with build artifacts
-5. Merge to main triggers npm publish
-```
+The pipeline applies these transformations to token names:
 
-➡️ See [Figma Integration Guide](./README.tokens.md#-figma-integration--dependencies) for details.
+| Input | CSS/SCSS | JS/Swift/Compose | Notes |
+|-------|----------|------------------|-------|
+| `TextColorPrimary` | `text-color-primary` | `textColorPrimary` | CamelCase → kebab/camel |
+| `bildred` | `bildred` | `bildred` | Lowercase preserved |
+| `bild085` | `bild085` | `bild085` | Numbers allowed |
+| `alpha-black-20` | `alpha-black-20` | `alphaBlack20` | Numbers at end OK |
+| `space2x` | `space2x` | `space2x` | Dimension pattern |
+| `700-black` | `700-black` | `n700Black` | Number prefix → `n` prefix |
 
----
+**Important:** Tokens with numeric prefixes (e.g., `700-black-font-weight`) get an `n` prefix in camelCase platforms to ensure valid identifiers.
 
-## 📁 Project Structure
+### Token Types
 
-```
-vv-token-test-v3/
-│
-├── 📁 src/
-│   ├── design-tokens/                  # 🎨 Figma token export
-│   │   └── bild-design-system-raw-data.json
-│   ├── icons/                          # 🖼️ Figma icon export
-│   │   ├── icon-*.svg
-│   │   └── .codepoints.json            # Flutter codepoint registry
-│   └── components/                     # 🧩 Stencil Web Components
-│       ├── ds-button/                  # Button component
-│       ├── ds-card/                    # Card component
-│       └── index.html                  # Dev/test page
-│
-├── 📁 scripts/
-│   ├── tokens/                         # Token scripts
-│   │   ├── preprocess.js               # Token preprocessing
-│   │   ├── build.js                    # Token build orchestrator
-│   │   ├── bundles.js                  # Bundle generation
-│   │   ├── compare-builds.js           # Dist comparison
-│   │   └── release-notes.js            # Release notes generator
-│   └── icons/                          # Icon scripts
-│       ├── build-icons.js              # Main orchestrator
-│       ├── optimize-svg.js             # SVGO + validation
-│       ├── generate-react.js           # React TSX generation
-│       ├── compile-react.js            # TypeScript compilation
-│       ├── generate-android.js         # Android XML
-│       ├── generate-flutter.js         # Flutter TTF + Dart
-│       └── generate-ios.js             # iOS xcassets
-│
-├── 📁 build-config/
-│   ├── tokens/
-│   │   └── style-dictionary.config.js  # Token transforms
-│   ├── icons/
-│   │   ├── svgo.config.js              # SVG optimization
-│   │   └── tsconfig.json               # React TypeScript config
-│   └── stencil/
-│       ├── stencil.config.ts           # Stencil Web Components config
-│       └── tsconfig.json               # Stencil TypeScript config
-│
-├── 📁 tokens/                          # Preprocessed (Git tracked)
-├── 📁 dist/                            # Build output (Git ignored)
-│
-├── 📄 package.json                     # Token package config
-├── 📄 package.icons.json               # Icon package config
-│
-├── 📁 docs/                            # Platform documentation
-│   ├── css.md                          # CSS Custom Properties
-│   ├── js.md                           # JavaScript/React
-│   ├── android.md                      # Android Compose
-│   └── ios.md                          # iOS SwiftUI
-│
-├── 📄 README.md                        # 👈 This file
-├── 📄 README.tokens.md                 # Token documentation
-└── 📄 README.icons.md                  # Icon documentation
-```
+#### Colors
 
----
+| Platform | Format | Example |
+|----------|--------|---------|
+| CSS | `#HEX` / `rgba()` | `#DD0000` |
+| iOS Swift | `SwiftUI Color` | `Color(red: 0.867, ...)` |
+| Android Compose | `Color(0xFF...)` | `Color(0xFFDD0000)` |
 
-## ⚙️ Build Commands
+#### Dimensions
 
-### 🎨 Tokens
+| Platform | Format | Example |
+|----------|--------|---------|
+| CSS | `Xpx` | `16px` |
+| iOS Swift | `CGFloat` number | `16` |
+| Android Compose | `X.dp` | `16.dp` |
 
-```bash
-npm run build              # Full build (preprocess + tokens + bundles)
-npm run preprocess         # Figma JSON → Style Dictionary format
-npm run build:tokens       # Style Dictionary → 7 platforms
-npm run build:bundles      # Generate convenience bundles
-npm run clean              # Remove dist/ and tokens/
-```
+#### Typography (Compose)
 
-### 🧩 Stencil Components
+Typography tokens in Compose use `.sp` for accessibility scaling:
 
-```bash
-npm run build:stencil      # Build Stencil Web Components
-npm run dev:stencil        # Dev server with hot reload (port 3333)
-npm run build:all          # Full build (tokens + bundles + stencil)
-```
+| Property | Format | Example |
+|----------|--------|---------|
+| `fontSize` | `X.sp` | `16.sp` |
+| `lineHeight` | `X.sp` | `24.sp` |
+| `letterSpacing` | `Xf.sp` | `0.5f.sp` |
+| `fontWeight` | `Int` | `700` |
+| `fontStyle` | `FontStyle` | `FontStyle.Italic` |
+| `fontFamily` | `String` | `"Gotham XNarrow"` |
 
-### 🖼️ Icons
+#### Opacity
 
-```bash
-npm run build:icons        # Full build (all platforms)
-npm run build:icons:svg    # SVG optimization only
-npm run build:icons:react  # React components only
-npm run build:icons:android
-npm run build:icons:flutter
-npm run build:icons:ios
-npm run clean:icons        # Remove dist/icons/
+| Platform | Format | Example |
+|----------|--------|---------|
+| CSS | `0-1` number | `0.5` |
+| iOS Swift | `CGFloat` | `0.5` |
+| Android Compose | `Float` | `0.5f` |
+
+**Note:** Figma exports opacity as percentage (5, 10, 70). Transform converts to decimal: `5` → `0.05`. iOS/Swift uses per-token type detection to correctly map opacity tokens to `CGFloat` in component protocols.
+
+## Output Toggles
+
+The build pipeline supports toggles to enable/disable specific outputs:
+
+```javascript
+// In scripts/tokens/build.js
+
+// Platform output toggles
+const COMPOSE_ENABLED = true;         // Enables dist/android/compose/ output
+
+// Token type toggles
+const BOOLEAN_TOKENS_ENABLED = false; // Excludes visibility tokens
 ```
 
+| Toggle | Default | Description |
+|--------|---------|-------------|
+| `COMPOSE_ENABLED` | `true` | Jetpack Compose Kotlin output in `dist/android/compose/` |
+| `BOOLEAN_TOKENS_ENABLED` | `false` | Boolean/visibility tokens (13 tokens like `hideOnMobile`) |
+
 ---
 
-## 🔄 CI/CD Workflows
+## 📁 Output Structure
+
+Token output is located in `packages/tokens/dist/`:
+
+```
+packages/tokens/dist/
+├── css/
+│   ├── shared/                      # Primitives
+│   ├── bundles/                     # Convenience bundles (Quick Start)
+│   └── brands/
+│       └── bild/
+│           ├── density/
+│           ├── components/          # ~300 component files
+│           └── semantic/
+│               ├── breakpoints/
+│               ├── color/
+│               ├── typography/
+│               └── effects/
+├── scss/                            # Same structure
+├── js/                              # Optimized ESM output
+│   ├── index.js                     # Main entry point
+│   ├── types.d.ts                   # TypeScript definitions
+│   ├── primitives/                  # Shared primitives
+│   ├── brands/{brand}/              # Brand tokens (colors, spacing, typography)
+│   ├── themes/                      # Pre-built themes + createTheme()
+│   └── react/                       # ThemeProvider, useTheme, useBreakpoint
+├── json/                            # Same structure
+├── ios/                             # Swift Classes
+├── android/
+│   └── compose/                     # Jetpack Compose (Kotlin)
+│       ├── shared/
+│       │   ├── DesignTokenPrimitives.kt   # All primitives consolidated
+│       │   ├── Density.kt                 # Dense/Default/Spacious enum
+│       │   ├── WindowSizeClass.kt         # Material 3: Compact/Medium/Expanded enum
+│       │   ├── Brand.kt                   # Bild/Sportbild/Advertorial enum
+│       │   └── DesignSystemTheme.kt       # Multi-brand theme provider
+│       └── brands/{brand}/
+│           ├── components/{Component}/
+│           │   └── {Component}Tokens.kt   # Aggregated with current() accessors
+│           ├── semantic/
+│           │   ├── {Brand}SemanticTokens.kt   # Aggregated Light/Dark + Compact/Medium/Expanded
+│           │   ├── color/
+│           │   │   ├── ColorsLight.kt     # BildColorScheme interface + BildLightColors
+│           │   │   └── ColorsDark.kt      # BildDarkColors object
+│           │   └── sizeclass/
+│           │       ├── SizingCompact.kt   # BildSizingScheme interface + BildSizingCompact
+│           │       ├── SizingMedium.kt    # BildSizingMedium object (Material 3)
+│           │       └── SizingExpanded.kt  # BildSizingExpanded object
+│           └── theme/
+│               └── {Brand}Theme.kt        # CompositionLocal Theme Provider
+```
 
-### 🎨 Token Workflows
+### Compose File Organization
+
+Compose output is optimized for Android development:
+
+**Shared Files (brand-independent):**
+
+| File | Content | Access Pattern |
+|------|---------|----------------|
+| `shared/DesignTokenPrimitives.kt` | All primitives (Colors, Space, Size, Font) | `DesignTokenPrimitives.Colors.bildred` |
+| `shared/Density.kt` | UI density enum | `Density.Dense`, `Density.Default`, `Density.Spacious` |
+| `shared/WindowSizeClass.kt` | Material 3 responsive layout enum | `WindowSizeClass.Compact`, `WindowSizeClass.Medium`, `WindowSizeClass.Expanded` |
+| `shared/ColorBrand.kt`, `ContentBrand.kt` | Dual-axis brand enums | `ColorBrand.Bild`, `ContentBrand.Advertorial` |
+| `shared/DesignColorScheme.kt` | Unified color interface | `DesignSystemTheme.colors.textColorPrimary` |
+| `shared/DesignSizingScheme.kt` | Unified sizing interface | `DesignSystemTheme.sizing.gridSpaceRespBase` |
+| `shared/DesignTypographyScheme.kt` | Unified typography interface | `DesignSystemTheme.typography.headline1` |
+| `shared/DesignTextStyle.kt` | Typography composite type | `.toComposeTextStyle()` |
+| `shared/DesignEffectsScheme.kt` | Unified effects interface | `DesignSystemTheme.effects.shadowSoftMd` |
+| `shared/DropShadow.kt`, `ShadowStyle.kt` | Shadow composite types | `.toModifier()` |
+| `shared/EffectsLight.kt`, `EffectsDark.kt` | Light/Dark shadows | Brand-independent, only theme-dependent |
+| `shared/DesignSystemTheme.kt` | Multi-brand theme provider | `DesignSystemTheme(colorBrand, contentBrand) { }` |
+
+**Brand Files:**
+
+| File | Content | Access Pattern |
+|------|---------|----------------|
+| `{Brand}Theme.kt` | CompositionLocal Theme Provider | `BildTheme { }`, `BildTheme.colors.x`, `BildTheme.sizing.x` |
+| `{Brand}SemanticTokens.kt` | Colors + Sizing aggregated | `BildSemanticTokens.Colors.Light.textColorPrimary` |
+| `ColorsLight.kt` / `ColorsDark.kt` | ColorScheme interface + impl | Used by BildTheme internally |
+| `SizingCompact.kt` / `SizingRegular.kt` | SizingScheme interface + impl | Used by BildTheme internally |
+| `{Component}Tokens.kt` | Component tokens with `current()` | `ButtonTokens.Colors.current().buttonPrimaryBgColorIdle` |
+
+## 🔗 Figma Integration & Dependencies
+
+### Supported Figma Scopes
+
+| Scope | Assigned Type | Output Format |
+|-------|---------------|---------------|
+| `FONT_SIZE` | `fontSize` | px (CSS), `.sp` (Compose) |
+| `LINE_HEIGHT` | `lineHeight` | px (CSS), `.sp` (Compose) |
+| `LETTER_SPACING` | `letterSpacing` | px (CSS), `.sp` (Compose) |
+| `FONT_WEIGHT` | `fontWeight` | Unitless integer (100-900) |
+| `FONT_FAMILY` | `fontFamily` | String |
+| `FONT_STYLE` | `fontStyle` | String, `FontStyle.Italic` (Compose) |
+| `OPACITY` | `opacity` | 0-1 decimal (÷100) |
+| `WIDTH_HEIGHT` | `dimension` | px (CSS), `.dp` (Compose) |
+| `GAP` | `dimension` | px (CSS), `.dp` (Compose) |
+| `CORNER_RADIUS` | `dimension` | px (CSS), `.dp` (Compose) |
+| `STROKE_FLOAT` | `dimension` | px (CSS), `.dp` (Compose) |
+| `PARAGRAPH_SPACING` | `dimension` | px (CSS), `.dp` (Compose) |
+| `PARAGRAPH_INDENT` | `dimension` | px (CSS), `.dp` (Compose) |
+| `ALL_FILLS`, `FRAME_FILL`, `SHAPE_FILL`, `TEXT_FILL` | `color` | #HEX, `Color(0xFF...)` |
+| `STROKE_COLOR`, `EFFECT_COLOR` | `color` | #HEX, `Color(0xFF...)` |
+
+### Compose Unit Mapping
+
+Android Compose uses type-safe units. The pipeline automatically maps token types:
+
+| Token Type | Compose Unit | Example Output |
+|------------|--------------|----------------|
+| `fontSize` | `.sp` | `16.sp` |
+| `lineHeight` | `.sp` | `24.sp` |
+| `letterSpacing` | `.sp` | `0.5f.sp` |
+| `dimension` | `.dp` | `16.dp` |
+| `fontWeight` | `Int` | `700` |
+| `fontStyle` | `FontStyle` | `FontStyle.Italic` |
+| `fontFamily` | `String` | `"Gotham XNarrow"` |
+| `color` | `Color` | `Color(0xFFDD0000)` |
+| `opacity` | `Int` | `50` (percentage) |
+
+**Note:** `.sp` (scale-independent pixels) is used for text-related measurements to support accessibility scaling. `.dp` (density-independent pixels) is used for layout dimensions.
+
+### Stable Changes
+
+| Change Type | Impact | Auto-Recovery |
+|-------------|--------|---------------|
+| New token | Added | Yes |
+| Edit value | Updated | Yes |
+| Add scope | Better typing | Yes |
+| New component | Folder created | Yes |
+
+### Unstable Changes
+
+| Change Type | Impact | Fix Required |
+|-------------|--------|--------------|
+| Delete collection | Build fails | Code update |
+| Rename collection | Tokens skipped | Code update |
+| Circular alias | Token unresolved | Fix in Figma |
 
-| Workflow | Trigger | Action |
-|----------|---------|--------|
-| `build-tokens.yml` | Push to main/develop/claude/** | Build + upload artifacts |
-| `auto-pr-from-figma.yml` | Push to `figma-tokens` | Create/update PR |
-| `publish-on-merge.yml` | Merge to main | npm publish + GitHub Release |
+## 🔄 CI/CD Workflows
 
-### 🖼️ Icon Workflows
+### build-tokens.yml
+- **Trigger**: Push to main, develop, claude/**
+- **Outputs**: Build artifacts (30-day retention)
 
-| Workflow | Trigger | Action |
-|----------|---------|--------|
-| `build-icons.yml` | Push to main/develop/claude/** | Build + upload artifacts |
-| `auto-pr-from-figma-icons.yml` | Push to `figma-icons` | Create/update PR |
-| `publish-icons-on-merge.yml` | Merge to main | npm publish + GitHub Release |
+### auto-pr-from-figma.yml
+- **Trigger**: Push to `figma-tokens` branch
+- **Creates**: Pull Request to main with release notes
 
-### Why dist/ is NOT in Git
+### publish-on-merge.yml
+- **Trigger**: Merge to main
+- **Actions**: Version bump, npm publish, GitHub Release
 
-- ✅ No merge conflicts (~970 generated files)
-- ✅ Clean Git history (only source files)
-- ✅ PR review via CI artifacts (30 days retention)
-- ✅ Deterministic builds
-- ✅ Smaller repo size
+## 🆘 Troubleshooting
 
----
+### Missing dist/ Folder
 
-## 📊 Platform Support
+```bash
+# Generate locally
+npm run build
 
-### 🎨 Token Platforms
+# Or download from CI artifacts
+```
 
-| Platform | Format | Files | Status |
-|----------|--------|-------|--------|
-| CSS | Custom Properties | `dist/css/**/*.css` | ✅ Production |
-| SCSS | Variables | `dist/scss/**/*.scss` | ✅ Production |
-| JavaScript | ES Modules + React | `dist/js/**/*.js` | ✅ Production |
-| JSON | Raw Data | `dist/json/**/*.json` | ✅ Production |
-| iOS Swift | SwiftUI Color, CGFloat | `dist/ios/**/*.swift` | ✅ Production |
-| Android | Jetpack Compose (Kotlin) | `dist/android/compose/**/*.kt` | ✅ Production |
+### Build Failures
 
-### 🖼️ Icon Platforms
+```bash
+npm run clean
+npm install
+npm run build
+```
 
-| Platform | Format | Files | Status |
-|----------|--------|-------|--------|
-| SVG | Optimized | `dist/icons/svg/*.svg` | ✅ Production |
-| React | ESM + TypeScript | `dist/icons/react/*.js` + `.d.ts` | ✅ Production |
-| Android | Vector Drawable | `dist/icons/android/drawable/*.xml` | ✅ Production |
-| Flutter | TTF + Dart | `dist/icons/flutter/` | ✅ Production |
-| iOS | Asset Catalog | `dist/icons/ios/*.xcassets` | ✅ Production |
+### iOS px String Issue
 
----
+**Fixed:** iOS now uses `custom/size/ios-points` transform. Verify:
+```bash
+grep "Space2x" dist/ios/shared/Spaceprimitive.swift
+# Expected: public static let Space2x = 16 (not "16px")
+```
 
-## 📚 Documentation
+## 🔗 Related
 
 | Document | Description |
 |----------|-------------|
-| [📖 README.tokens.md](./README.tokens.md) | Complete token pipeline documentation |
+| [📖 Main README](../../README.md) | Project overview |
+| [📖 docs/css.md](./docs/css.md) | CSS Custom Properties documentation |
 | [📖 docs/js.md](./docs/js.md) | JavaScript/React integration (Dual-Axis) |
-| [📖 README.icons.md](./README.icons.md) | Complete icon pipeline documentation |
 | [📖 docs/android.md](./docs/android.md) | Android Jetpack Compose (Dual-Axis) |
 | [📖 docs/ios.md](./docs/ios.md) | iOS SwiftUI (Dual-Axis) |
-
-### Quick Links
-
-**Tokens:**
-- [Platform Usage Examples](./README.tokens.md#-platform-usage)
-- [Transform Reference](./README.tokens.md#-token-transform-reference)
-- [Figma Integration](./README.tokens.md#-figma-integration--dependencies)
-- [Troubleshooting](./README.tokens.md#-troubleshooting)
-
-**JavaScript/React:**
-- [Quick Start](./docs/js.md#quick-start)
-- [React ThemeProvider](./docs/js.md#react-themeprovider)
-- [Token Type Mapping](./docs/js.md#token-type-mapping)
-- [Multi-Brand Apps](./docs/js.md#multi-brand-apps)
-
-**Icons:**
-- [Platform Usage Examples](./README.icons.md#usage)
-- [Naming Conventions](./README.icons.md#naming-conventions)
-- [Accessibility](./README.icons.md#accessibility)
-- [SVG Requirements](./README.icons.md#svg-requirements)
+| [📖 Icons README](../icons/README.md) | Icon pipeline documentation |
+| [📖 Components README](../components/README.md) | Stencil Web Components |
+| [Style Dictionary](https://styledictionary.com/) | Build tool documentation |
 
 ---
 
@@ -459,37 +835,25 @@ npm run clean:icons        # Remove dist/icons/
 
 > **⚠️ IMPORTANT: Figma is the Single Source of Truth**
 >
-> Design assets (tokens and icons) must **NOT** be edited directly in the repository.
-> All changes must be made in Figma and exported via the **TokenSync Plugin**.
-
-### Allowed Workflow
-
-```
-1. Make changes in Figma
-2. Export with TokenSync Plugin
-3. Automatic PR is created
-4. Review and merge PR
-```
+> Design Tokens must **NOT** be edited directly in the repository.
+> All token changes must be made in Figma and exported via the **CodeBridge Plugin**.
 
-### NOT Allowed
+**Workflow:**
+1. Edit/create tokens in Figma
+2. Export with CodeBridge Plugin
+3. Review and merge PR
 
+**NOT Allowed:**
 - ❌ Direct changes to `src/design-tokens/*.json`
-- ❌ Direct changes to `src/icons/*.svg`
-- ❌ Manual commits to `figma-tokens` or `figma-icons` branch
+- ❌ Manual commits to `figma-tokens` branch
 - ❌ Changes to generated files in `dist/`
 
-### Allowed (Pipeline Development)
-
+**Allowed (Pipeline Development):**
 - ✅ Changes to build scripts (`scripts/`)
 - ✅ Changes to configuration (`build-config/`)
 - ✅ Workflow adjustments (`.github/workflows/`)
 - ✅ Documentation
 
-For pipeline changes:
-```bash
-npm run build && npm run build:icons
-```
-
 ---
 
 ## 📄 License
@@ -498,19 +862,17 @@ MIT License - See [LICENSE](./LICENSE) file.
 
 ---
 
-## 🔗 Resources
-
-- [Style Dictionary Documentation](https://styledictionary.com/)
-- [SVGO Documentation](https://svgo.dev/)
-- [Figma Variables API](https://www.figma.com/plugin-docs/api/properties/figma-variables/)
-- [Repository Issues](https://github.com/UXWizard25/vv-token-test-v3/issues)
-
----
-
 **Built with ❤️ for the BILD Design System**
 
-| Tokens | Icons |
-|--------|-------|
-| ~970 files | 5 platforms |
-| 6 platforms (incl. Compose) | TypeScript support |
-| 3 brands | Accessibility ready |
+| Feature | Status |
+|---------|--------|
+| 6 Platforms | ✅ |
+| 3 Brands | ✅ |
+| ~970 Files | ✅ |
+| Figma Scopes | ✅ |
+| var() Aliases | ✅ |
+| Responsive CSS | ✅ |
+| Jetpack Compose | ✅ |
+| Theme Provider | ✅ |
+| Shadow DOM / Web Components | ✅ |
+| Stencil Components | ✅ |