@marioschmidt/design-system-tokens 1.0.62 → 1.0.64

package/README.md

@@ -49,6 +49,8 @@ Both pipelines use the **TokenSync Figma Plugin** for automated exports.
 |---------|-------------|---------|---------------|
 | **@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) |
+| **Android Compose** | Jetpack Compose (Dual-Axis) | - | [📖 README.android.md](./README.android.md) |
+| **iOS SwiftUI** | SwiftUI (Dual-Axis) | - | [📖 README.ios.md](./README.ios.md) |
 
 ---
 
@@ -167,16 +169,37 @@ let padding: CGFloat = StyleDictionary.space2x
 // Android Jetpack Compose
 import com.bild.designsystem.bild.theme.BildTheme
 import com.bild.designsystem.bild.components.ButtonTokens
-
-BildTheme {
-    Button(
-        colors = ButtonDefaults.buttonColors(
-            containerColor = ButtonTokens.Colors.Light.buttonPrimaryBrandBgColorIdle
-        )
+import com.bild.designsystem.shared.Density
+import com.bild.designsystem.shared.WindowSizeClass
+
+@Composable
+fun MyApp() {
+    BildTheme(
+        darkTheme = isSystemInDarkTheme(),
+        sizeClass = WindowSizeClass.Compact,
+        density = Density.Default
     ) {
-        Text(color = BildTheme.colors.textColorPrimary)
+        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
+            )
+        }
     }
 }
+
+// Multi-brand apps: Use DesignSystemTheme
+import com.bild.designsystem.shared.Brand
+import com.bild.designsystem.shared.DesignSystemTheme
+
+DesignSystemTheme(brand = Brand.Bild) { /* ... */ }
 ```
 
 ### Icon Usage
@@ -365,6 +388,8 @@ npm run clean:icons        # Remove dist/icons/
 |----------|-------------|
 | [📖 README.tokens.md](./README.tokens.md) | Complete token pipeline documentation |
 | [📖 README.icons.md](./README.icons.md) | Complete icon pipeline documentation |
+| [📖 README.android.md](./README.android.md) | Android Jetpack Compose (Dual-Axis) |
+| [📖 README.ios.md](./README.ios.md) | iOS SwiftUI (Dual-Axis) |
 
 ### Quick Links
 

package/README.tokens.md

@@ -144,6 +144,44 @@ npm run build:tokens   # Style Dictionary → 7 platforms
 npm run build:bundles  # Generate CSS bundle files
 ```
 
+## 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
@@ -201,29 +239,133 @@ Container(
 )
 ```
 
-### Android Jetpack Compose
+### Android Jetpack Compose (Dual-Axis Architecture)
+
+> **See [README.android.md](./README.android.md) for complete documentation**
 
 ```kotlin
-import com.bild.designsystem.bild.theme.BildTheme
-import com.bild.designsystem.bild.semantic.BildSemanticTokens
+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.DesignTokenPrimitives
-
-// Theme Provider (with automatic Light/Dark, WindowSizeClass support)
-BildTheme(
-    darkTheme = isSystemInDarkTheme(),
-    sizeClass = WindowSizeClass.Compact
-) {
-    // Access via BildTheme object
-    Text(color = BildTheme.colors.textColorPrimary)
+
+@Composable
+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
+    ) {
+        // 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
+    }
 }
 
-// Direct token access (camelCase naming)
-val primaryColor = BildSemanticTokens.Colors.Light.textColorPrimary
-val buttonBg = ButtonTokens.Colors.Light.buttonPrimaryBrandBgColorIdle
-val red = DesignTokenPrimitives.Colors.bildred
+// 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 [README.ios.md](./README.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
+                )
+        }
+    }
+}
+
+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) |
+
 ### Android XML (Disabled)
 
 > **Note:** Android XML output is disabled by default. Jetpack Compose is the preferred format.
@@ -281,24 +423,46 @@ Breakpoints use native `@media` queries instead of `data-breakpoint` attributes:
 
 ### Native Sizeclass Mapping (iOS/Android)
 
-For native platforms, 4 web breakpoints map to 2 size classes:
+Native platforms use different size class systems:
+
+#### iOS (2 Size Classes - Apple HIG)
 
 ```
-Web Breakpoints         Native Size Classes
-─────────────────       ───────────────────
+Web Breakpoints         iOS Size Classes
+─────────────────       ────────────────
 xs (320px) ─────┐
-                ├────→  compact (small screens)
+                ├────→  compact (Phones)
 sm (390px) ─────┘
 
 md (600px) ─────┐
-                ├────→  regular (large screens)
+                ├────→  regular (Tablets)
 lg (1024px) ────┘
 ```
 
-| Platform | Compact | Regular |
-|----------|---------|---------|
-| iOS | `UITraitCollection.horizontalSizeClass == .compact` | `.regular` |
-| Android | `sw320dp` | `sw600dp` |
+| Size Class | iOS Trait | Web Breakpoint |
+|------------|-----------|----------------|
+| `compact` | `.compact` | sm (390px) |
+| `regular` | `.regular` | lg (1024px) |
+
+#### Android (3 Size Classes - Material 3 WindowSizeClass)
+
+```
+Web Breakpoints         Android WindowSizeClass
+─────────────────       ───────────────────────
+xs (320px) ─────┐
+                ├────→  Compact (< 600dp)
+sm (390px) ─────┘
+
+md (600px) ──────────→  Medium (600-839dp)
+
+lg (1024px) ─────────→  Expanded (≥ 840dp)
+```
+
+| Size Class | Material 3 Range | Web Breakpoint |
+|------------|------------------|----------------|
+| `Compact` | width < 600dp | sm (390px) |
+| `Medium` | 600dp ≤ width < 840dp | md (600px) |
+| `Expanded` | width ≥ 840dp | lg (1024px) |
 
 ---
 
@@ -316,6 +480,21 @@ lg (1024px) ────┘
 | Android XML | `snake_case` | `text_color_primary` |
 | Flutter | `camelCase` | `textColorPrimary` |
 
+### Name Transformations
+
+The pipeline applies these transformations to token names:
+
+| 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.
+
 ### Token Types
 
 #### Colors
@@ -334,19 +513,33 @@ lg (1024px) ────┘
 |----------|--------|---------|
 | CSS | `Xpx` | `16px` |
 | iOS Swift | `CGFloat` number | `16` |
-| Android Compose | `X.dp` / `X.sp` | `16.dp`, `15.sp` |
+| Android Compose | `X.dp` | `16.dp` |
 | Android XML | `Xpx` dimen | `16px` |
 | Flutter | `"Xpx"` string | `"16px"` |
 
+#### Typography (Compose)
+
+Typography tokens in Compose use `.sp` for accessibility scaling:
+
+| 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"` |
+
 #### Opacity
 
 | Platform | Format | Example |
 |----------|--------|---------|
 | CSS | `0-1` number | `0.5` |
 | iOS Swift | `CGFloat` | `0.5` |
+| Android Compose | `Float` | `0.5f` |
 | Flutter | `double` | `0.5` |
 
-**Note:** Figma exports opacity as percentage (5, 10, 70). Transform converts to decimal: `5` → `0.05`
+**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
 
@@ -396,12 +589,23 @@ dist/
 ├── android/
 │   └── compose/                     # Jetpack Compose (Kotlin)
 │       ├── shared/
-│       │   └── DesignTokenPrimitives.kt   # All primitives consolidated
+│       │   ├── 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 Colors/Sizing/Density/Typography
+│           │   └── {Component}Tokens.kt   # Aggregated with current() accessors
 │           ├── semantic/
-│           │   └── {Brand}SemanticTokens.kt   # Aggregated Light/Dark + Compact/Regular
+│           │   ├── {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
 └── flutter/                         # Dart Classes (disabled by default)
@@ -411,12 +615,32 @@ dist/
 
 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 |
 |------|---------|----------------|
-| `DesignTokenPrimitives.kt` | All primitives (Colors, Space, Size, Font) | `DesignTokenPrimitives.Colors.bildred` |
-| `{Brand}SemanticTokens.kt` | Colors (Light/Dark), Sizing (Compact/Regular) | `BildSemanticTokens.Colors.Light.textColorPrimary` |
-| `{Component}Tokens.kt` | All component modes aggregated | `ButtonTokens.Colors.Light.buttonPrimaryBrandBgColorIdle` |
-| `{Brand}Theme.kt` | CompositionLocal-based Theme Provider | `BildTheme { /* content */ }` |
+| `{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
 
@@ -424,11 +648,39 @@ Compose output is optimized for Android development:
 
 | 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), CGFloat (iOS) |
-| `GAP` | `dimension` | Same as above |
-| `FONT_SIZE` | `fontSize` | px with transform |
-| `FONT_WEIGHT` | `fontWeight` | Unitless integer |
+| `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