@marioschmidt/design-system-tokens 1.0.63 → 1.0.65

package/README.md

@@ -49,6 +49,7 @@ 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) |
+| **JavaScript/React** | ESM + ThemeProvider (Dual-Axis) | - | [📖 README.js.md](./README.js.md) |
 | **Android Compose** | Jetpack Compose (Dual-Axis) | - | [📖 README.android.md](./README.android.md) |
 | **iOS SwiftUI** | SwiftUI (Dual-Axis) | - | [📖 README.ios.md](./README.ios.md) |
 
@@ -112,7 +113,7 @@ Both pipelines use the **TokenSync Figma Plugin** for automated exports.
 │  ├── css/     (CSS Vars)    │    │  ├── svg/      (Optimized)  │
 │  │   └── bundles/ (Quick)   │    │  ├── react/    (ESM + d.ts) │
 │  ├── scss/    (SCSS Vars)   │    │  ├── android/  (XML)        │
-│  ├── js/      (ES Modules)  │    │  ├── flutter/  (TTF + Dart) │
+│  ├── js/      (ESM + React) │    │  ├── flutter/  (TTF + Dart) │
 │  ├── json/    (Raw Data)    │    │  └── ios/      (xcassets)   │
 │  ├── ios/     (Swift)       │    │                             │
 │  └── android/ (Compose/Kt)  │    │                             │
@@ -155,8 +156,13 @@ npm install @marioschmidt/design-system-icons
 ```
 
 ```javascript
-// JavaScript
-import { textColorPrimary, space2x } from '@marioschmidt/design-system-tokens/js/brands/bild/semantic/color/colormode-light';
+// JavaScript (ES Modules) - Values are CSS-ready strings
+import { createTheme } from '@marioschmidt/design-system-tokens/themes';
+import { ThemeProvider, useTheme } from '@marioschmidt/design-system-tokens/react';
+
+const theme = createTheme({ colorBrand: 'bild', colorMode: 'light' });
+console.log(theme.colors.textColorPrimary);   // "#232629"
+console.log(theme.spacing.gridSpaceRespBase); // "12px" - CSS-ready!
 ```
 
 ```swift
@@ -363,7 +369,7 @@ npm run clean:icons        # Remove dist/icons/
 |----------|--------|-------|--------|
 | CSS | Custom Properties | `dist/css/**/*.css` | ✅ Production |
 | SCSS | Variables | `dist/scss/**/*.scss` | ✅ Production |
-| JavaScript | ES6 Modules | `dist/js/**/*.js` | ✅ Production |
+| JavaScript | ES Modules + React | `dist/js/**/*.js` | ✅ Production |
 | JSON | Raw Data | `dist/json/**/*.json` | ✅ Production |
 | iOS Swift | UIColor, CGFloat | `dist/ios/**/*.swift` | ✅ Production |
 | Android | Jetpack Compose (Kotlin) | `dist/android/compose/**/*.kt` | ✅ Production |
@@ -387,6 +393,7 @@ npm run clean:icons        # Remove dist/icons/
 | Document | Description |
 |----------|-------------|
 | [📖 README.tokens.md](./README.tokens.md) | Complete token pipeline documentation |
+| [📖 README.js.md](./README.js.md) | JavaScript/React integration (Dual-Axis) |
 | [📖 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) |
@@ -399,6 +406,12 @@ npm run clean:icons        # Remove dist/icons/
 - [Figma Integration](./README.tokens.md#-figma-integration--dependencies)
 - [Troubleshooting](./README.tokens.md#-troubleshooting)
 
+**JavaScript/React:**
+- [Quick Start](./README.js.md#quick-start)
+- [React ThemeProvider](./README.js.md#react-themeprovider)
+- [Token Type Mapping](./README.js.md#token-type-mapping)
+- [Multi-Brand Apps](./README.js.md#multi-brand-apps)
+
 **Icons:**
 - [Platform Usage Examples](./README.icons.md#usage)
 - [Naming Conventions](./README.icons.md#naming-conventions)

package/README.tokens.md

@@ -154,15 +154,15 @@ Figma token types (`$type`) are automatically mapped to platform-specific types:
 | `fontSize` | `var(--token)` (px) | `CGFloat` | `TextUnit` (.sp) |
 | `lineHeight` | `var(--token)` (px) | `CGFloat` | `TextUnit` (.sp) |
 | `letterSpacing` | `var(--token)` (px) | `CGFloat` | `TextUnit` (.sp) |
-| `fontWeight` | `var(--token)` | `CGFloat` | `Int` |
+| `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-100) | `Int` | `Int` |
+| `opacity` | `var(--token)` (0-1) | `CGFloat` | `Float` |
 | `color` | `var(--token)` (hex/rgba) | `Color` | `Color` |
-| `shadow` | `box-shadow` | `ShadowStyle` | `Shadow` |
-| `typography` | CSS classes | `TextStyle` | `TextStyle` |
+| `shadow` | `box-shadow` | `ShadowStyle` | `ShadowStyle` |
+| `typography` | CSS classes | `TextStyle` | `DesignTextStyle` |
 
 ### Token Type Distribution
 
@@ -198,18 +198,57 @@ Figma token types (`$type`) are automatically mapped to platform-specific types:
 
 ### JavaScript / React
 
+> **See [README.js.md](./README.js.md) for complete documentation**
+
 ```javascript
-import {
-  textColorPrimary,
-  space2x
-} from '@marioschmidt/design-system-tokens/js/brands/bild/semantic/color/colormode-light';
-
-const Button = styled.button`
-  background-color: ${textColorPrimary};
-  padding: ${space2x};
-`;
+// With React ThemeProvider (Dual-Axis Architecture)
+import { ThemeProvider, useTheme } from '@marioschmidt/design-system-tokens/react';
+
+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"
 ```
 
+#### 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
@@ -286,21 +325,30 @@ Separates color selection from content selection:
 
 #### Unified Interfaces (Polymorphic Access)
 
-| Interface | Purpose | Property Count |
-|-----------|---------|----------------|
-| `DesignColorScheme` | All color tokens | 80+ colors |
-| `DesignSizingScheme` | All sizing tokens | 180+ sizing values |
+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 | Values |
-|----------|-----------------|--------|
-| `Colors.current()` | `DesignSystemTheme.isDarkTheme` | Light / Dark |
-| `Sizing.current()` | `DesignSystemTheme.sizeClass` | Compact / Regular |
-| `Typography.current()` | `DesignSystemTheme.sizeClass` | Compact / Regular |
-| `Density.current()` | `DesignSystemTheme.density` | Dense / Default / Spacious |
+| 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)
 
@@ -327,8 +375,13 @@ 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") { }
@@ -349,7 +402,8 @@ struct MyView: View {
 |----------|---------|
 | `DesignColorScheme` | All color tokens |
 | `DesignSizingScheme` | All sizing tokens |
-| `DesignEffectsScheme` | Shadow/effect tokens |
+| `DesignTypographyScheme` | All text styles (TextStyle composites) |
+| `DesignEffectsScheme` | Shadow tokens (ShadowStyle composites, brand-independent) |
 
 ### Android XML (Disabled)
 
@@ -408,24 +462,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) |
 
 ---
 
@@ -499,9 +575,10 @@ Typography tokens in Compose use `.sp` for accessibility scaling:
 |----------|--------|---------|
 | 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
 
@@ -545,7 +622,13 @@ dist/
 │               ├── typography/
 │               └── effects/
 ├── scss/                            # Same structure
-├── js/                              # 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/
@@ -553,20 +636,21 @@ dist/
 │       ├── shared/
 │       │   ├── DesignTokenPrimitives.kt   # All primitives consolidated
 │       │   ├── Density.kt                 # Dense/Default/Spacious enum
-│       │   ├── WindowSizeClass.kt         # Compact/Regular 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/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
-│           │       └── SizingRegular.kt   # BildSizingRegular object
+│           │       ├── SizingMedium.kt    # BildSizingMedium object (Material 3)
+│           │       └── SizingExpanded.kt  # BildSizingExpanded object
 │           └── theme/
 │               └── {Brand}Theme.kt        # CompositionLocal Theme Provider
 └── flutter/                         # Dart Classes (disabled by default)
@@ -582,9 +666,16 @@ Compose output is optimized for Android development:
 |------|---------|----------------|
 | `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` | Responsive layout enum | `WindowSizeClass.Compact`, `WindowSizeClass.Regular` |
-| `shared/Brand.kt` | Available brands enum | `Brand.Bild`, `Brand.Sportbild`, `Brand.Advertorial` |
-| `shared/DesignSystemTheme.kt` | Multi-brand theme provider | `DesignSystemTheme(brand = Brand.Bild) { }` |
+| `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:**
 
@@ -699,6 +790,10 @@ grep "Space2x" dist/ios/shared/Spaceprimitive.swift
 | Document | Description |
 |----------|-------------|
 | [📖 README.md](./README.md) | Main project overview |
+| [📖 README.css.md](./README.css.md) | CSS Custom Properties documentation |
+| [📖 README.js.md](./README.js.md) | JavaScript/React integration (Dual-Axis) |
+| [📖 README.android.md](./README.android.md) | Android Jetpack Compose (Dual-Axis) |
+| [📖 README.ios.md](./README.ios.md) | iOS SwiftUI (Dual-Axis) |
 | [📖 README.icons.md](./README.icons.md) | Icon pipeline documentation |
 | [Style Dictionary](https://styledictionary.com/) | Build tool documentation |