michaelschiemer/docs/design-token-system.md

# Design Token System Dokumentation

## Übersicht

Das Design Token System ermöglicht die zentrale Verwaltung von Design-Tokens (Farben, Abstände, Typografie, etc.) in PHP mit automatischer CSS-Generierung. Es unterstützt moderne CSS-Features wie OKLCH-Farben, HDR/P3-Support, Dark Mode und State-basierte Token-Variationen.

## Architektur

### Kernkomponenten

1. **TokenRegistry** - Basis-Klasse für Token-Registries
2. **ColorVariation** - Verwaltet Farben mit Light/Dark/P3/Fallback-Varianten
3. **ColorManipulator** - Service für Farbmanipulation
4. **StateMutation** - Definiert Mutationen für Token-States
5. **TokenStateRegistry** - Verwaltet Tokens mit States
6. **CssAstBuilder** - Generiert CSS aus Tokens

### Token-Typen

- **ColorToken** - Farb-Token mit Variationen
- **StatefulColorToken** - Farb-Token mit States (hover, disabled, etc.)
- **SpacingToken** - Abstands-Token
- **TypographyToken** - Typografie-Token

## Farbmanipulation

### ColorManipulator Service

Der `ColorManipulator` Service bietet Methoden zur Manipulation von Farben:

```php
use App\Framework\Design\Services\ColorManipulator;
use App\Framework\Design\ValueObjects\CssColor;
use App\Framework\Design\ValueObjects\ColorFormat;

$manipulator = new ColorManipulator();
$primary = new CssColor('oklch(70% 0.2 295)', ColorFormat::OKLCH);

// Helligkeit anpassen
$lighter = $manipulator->lighten($primary, 0.1);  // 10% heller
$darker = $manipulator->darken($primary, 0.2);    // 20% dunkler

// Sättigung anpassen
$moreSaturated = $manipulator->saturate($primary, 0.15);
$lessSaturated = $manipulator->desaturate($primary, 0.5);

// Transparenz ändern
$semiTransparent = $manipulator->adjustOpacity($primary, 0.5);

// Farben mixen
$secondary = new CssColor('oklch(60% 0.2 145)', ColorFormat::OKLCH);
$mixed = $manipulator->mix($primary, $secondary, 0.3); // 30% primary, 70% secondary

// Farbton verschieben
$shifted = $manipulator->adjustHue($primary, 30); // 30 Grad verschieben
```

### CssColor Methoden

Farben können auch direkt manipuliert werden:

```php
$primary = new CssColor('oklch(70% 0.2 295)', ColorFormat::OKLCH);

$hover = $primary->lighten(0.1);
$active = $primary->darken(0.15);
$disabled = $primary->desaturate(1.0)->withOpacity(0.5);
$mixed = $primary->mix($secondary, 0.3);
```

## Token States

### TokenState Enum

Das `TokenState` Enum definiert verschiedene States für Tokens:

- `DEFAULT` - Standard State
- `DISABLED` - Deaktiviert
- `HOVER` - Hover State
- `ACTIVE` - Aktiv (z.B. gedrückt)
- `SELECTED` - Ausgewählt
- `FOCUSED` - Fokussiert
- `LOADING` - Lade-Zustand
- `ERROR` - Fehler-Zustand
- `SUCCESS` - Erfolgs-Zustand
- `WARNING` - Warnung-Zustand

### StateMutation

`StateMutation` definiert, wie ein Token für einen bestimmten State mutiert werden soll:

```php
use App\Framework\Design\ValueObjects\StateMutation;
use App\Framework\Design\ValueObjects\TokenState;

// Disabled State: 0% Sättigung, 50% Transparenz
$disabledMutation = new StateMutation(
    saturationAdjustment: -1.0,  // 0% Sättigung
    opacityAdjustment: 0.5        // 50% Transparenz
);

// Hover State: 10% heller
$hoverMutation = new StateMutation(
    lightnessAdjustment: 0.1
);

// Komposition mehrerer Mutationen
$desaturateMutation = new StateMutation(saturationAdjustment: -1.0);
$opacityMutation = new StateMutation(opacityAdjustment: 0.5);
$composedMutation = $desaturateMutation->compose($opacityMutation);
```

### StatefulColorToken

Ein `StatefulColorToken` repräsentiert einen Farb-Token mit einem spezifischen State:

```php
use App\Framework\Design\ValueObjects\Tokens\StatefulColorToken;
use App\Framework\Design\ValueObjects\ColorVariation;
use App\Framework\Design\ValueObjects\TokenState;
use App\Framework\Design\ValueObjects\StateMutation;

$primaryVariation = new ColorVariation(
    name: 'primary',
    light: new CssColor('oklch(70% 0.2 295)', ColorFormat::OKLCH),
    dark: new CssColor('oklch(60% 0.22 295)', ColorFormat::OKLCH)
);

// Default State
$defaultToken = new StatefulColorToken(
    name: 'button-primary',
    variation: $primaryVariation,
    state: TokenState::DEFAULT
);

// Disabled State (abgeleitet)
$disabledToken = new StatefulColorToken(
    name: 'button-primary',
    variation: $primaryVariation,
    state: TokenState::DISABLED,
    baseState: TokenState::DEFAULT,
    mutation: new StateMutation(
        saturationAdjustment: -1.0,
        opacityAdjustment: 0.5
    )
);
```

### TokenStateRegistry

Der `TokenStateRegistry` verwaltet Tokens mit States:

```php
use App\Framework\Design\ValueObjects\TokenStateRegistry;
use App\Framework\Design\ValueObjects\TokenState;
use App\Framework\Design\ValueObjects\StateMutation;

// Default Mutationen für States definieren
$registry = new TokenStateRegistry(
    tokens: [],
    stateMutations: [
        TokenState::DISABLED => new StateMutation(
            saturationAdjustment: -1.0,
            opacityAdjustment: 0.5
        ),
        TokenState::HOVER => new StateMutation(
            lightnessAdjustment: 0.1
        ),
        TokenState::ACTIVE => new StateMutation(
            lightnessAdjustment: -0.15
        ),
    ]
);

// Token hinzufügen
$registry = $registry->addToken($defaultToken);

// Token für State abrufen
$hoverToken = $registry->getTokenForState('button-primary', TokenState::HOVER);

// Alle States für Token abrufen
$allStates = $registry->getAllStatesForToken('button-primary');
```

## CSS-Generierung

### Automatische CSS-Generierung

Das System generiert automatisch CSS aus Tokens:

```php
use App\Framework\Design\ValueObjects\FrameworkTokenRegistry;

$registry = new FrameworkTokenRegistry();
$css = $registry->toCss('framework-settings', includeHdr: true);
```

### CSS Output

Das generierte CSS nutzt moderne Features:

```css
@layer framework-settings {
    :root {
        --color-primary: oklch(70% 0.2 295);
        --color-primary-p3: color(display-p3 0.8 0.3 1);
    }
}

@layer framework-settings {
    @media (prefers-color-scheme: dark) {
        :root {
            --color-primary: oklch(60% 0.22 295);
        }
    }
}

@layer framework-settings {
    @media (dynamic-range: high) {
        :root {
            --color-primary: var(--color-primary-p3);
        }
    }
}
```

### State-basierte CSS mit Pseudo-Klassen

Für StatefulTokens werden Pseudo-Klassen generiert:

```css
.button-primary {
    background: oklch(70% 0.2 295);
}

.button-primary:hover {
    background: oklch(77% 0.2 295); /* Automatisch generiert */
}

.button-primary:active {
    background: oklch(59.5% 0.2 295); /* Automatisch generiert */
}

.button-primary:disabled {
    background: oklch(70% 0 295 / 0.5); /* Komponierte Mutation */
}
```

## Verwendung

### FrameworkTokenRegistry

Framework-weite Tokens:

```php
use App\Framework\Design\ValueObjects\FrameworkTokenRegistry;

$registry = new FrameworkTokenRegistry();
$primaryColor = $registry->get('color-primary');
```

### AdminTokenRegistry

Admin-spezifische Tokens:

```php
use App\Application\Admin\ValueObjects\AdminTokenRegistry;

$registry = new AdminTokenRegistry();
$adminBg = $registry->get('admin-bg-primary');
```

### Token generieren

```bash
# Framework Tokens generieren
php console.php design:generate-tokens --scope=framework

# Admin Tokens generieren
php console.php design:generate-tokens --scope=admin

# Beide generieren
npm run build  # Generiert automatisch beide vor dem Build
```

## Best Practices

### Farben definieren

1. **OKLCH verwenden**: Perzeptuell uniforme Farbmanipulation
2. **ColorVariation nutzen**: Zentrale Verwaltung von Light/Dark/P3
3. **HDR-Support**: Automatische P3-Varianten für HDR-Displays

### States definieren

1. **Basis-State**: Immer einen DEFAULT State definieren
2. **Mutationen komponieren**: Mehrere Mutationen kombinieren
3. **Konsistente Mutationen**: Gleiche Mutationen für ähnliche States

### Token-Organisation

1. **Scopes trennen**: Framework vs. Admin Tokens
2. **Naming Convention**: Klare, konsistente Namen
3. **Beschreibungen**: Immer Beschreibungen hinzufügen

## Erweiterte Features

### Custom State Mutationen

```php
// Komplexe Mutation: Desaturate + Opacity + Mix
$complexMutation = new StateMutation(
    saturationAdjustment: -0.5,
    opacityAdjustment: 0.7,
    mixColor: new CssColor('oklch(50% 0 0)', ColorFormat::OKLCH), // Grau
    mixWeight: 0.3
);
```

### State-Hierarchien

```php
// Disabled kann von Hover abgeleitet werden
$disabledFromHover = new StatefulColorToken(
    name: 'button-primary',
    variation: $primaryVariation,
    state: TokenState::DISABLED,
    baseState: TokenState::HOVER, // Basis ist Hover, nicht Default
    mutation: new StateMutation(
        saturationAdjustment: -1.0,
        opacityAdjustment: 0.5
    )
);
```

## Performance

- **Caching**: Generierte CSS wird gecacht
- **Lazy Loading**: Tokens werden nur bei Bedarf geladen
- **Optimierte Konvertierung**: OKLCH-Konvertierung ist optimiert

## Browser-Unterstützung

- **OKLCH**: Moderne Browser (Chrome 111+, Safari 15.4+, Firefox 113+)
- **Display P3**: HDR-Displays mit Wide-Gamut-Support
- **Fallbacks**: Automatische RGB/HEX-Fallbacks für ältere Browser

## Migration von bestehenden Tokens

Bestehende Tokens können schrittweise migriert werden:

1. **ColorVariation erstellen**: Light/Dark Varianten definieren
2. **States hinzufügen**: Mutationen für States definieren
3. **CSS aktualisieren**: Generierte CSS verwenden

## Troubleshooting

### Farben sehen falsch aus

- Prüfe OKLCH-Werte (Lightness 0-1 oder 0-100%, Chroma 0-0.4+, Hue 0-360)
- Verwende ColorManipulator für konsistente Manipulation

### States funktionieren nicht

- Prüfe ob Token StatefulTokenInterface implementiert
- Prüfe ob Mutation korrekt definiert ist
- Prüfe CSS-Output auf Pseudo-Klassen

### CSS wird nicht generiert

- Prüfe ob TokenRegistry korrekt initialisiert ist
- Prüfe ob Output-Pfad existiert und beschreibbar ist
- Prüfe Console-Output für Fehlermeldungen